From first sign-in to production agents

Outcome: you can explain the platform's architecture, its vocabulary, and the build-versus-run model split to a colleague.

1.1 The mental model: ETL for AI

Weavr treats every system in your business as a live data stream. An agent extracts context from those systems through its tools, transforms it with AI reasoning, and loads actions back: a draft reply in a mailbox, a note in the CRM, a CSV report, a workflow hand-off. If a system has an API, Weavr can put it to work.

1.2 Your instance

Every organization runs on its own dedicated, single-tenant instance. Your agents, workflows, connections, credentials, and usage data live only there. Managed plans run on Powdr-held provider keys with automatic failover across Gemini, Groq, Anthropic, and OpenAI, so a single provider outage never stops a workflow. Enterprise Max instances bring their own keys instead.

1.3 The build-versus-run split

Weavr uses the most capable model available to design things and a cost-efficient model to run them. When the Agent Builder designs an agent, a frontier model (Anthropic Opus by default) writes the instructions and picks the tools. The agent you save then executes on the platform default (Gemini). You will see this on the Review step as "Designed by ... will run on ...". The same split appears in your usage dashboard as build cost versus run cost.

1.4 Vocabulary you will use every day

Outcome: you can sign in, invite teammates with the right roles, block access, and enable company SSO.

2.1 Signing in

1. Go to your instance's login page and enter your work email (personal domains like gmail.com are rejected).
2. If your company has SSO enabled, the button becomes Continue with Microsoft (or Google). Otherwise you receive a six-digit one-time code by email. No passwords exist anywhere in Weavr.
3. First user on a company domain becomes the organization admin; later users on the same domain join automatically as operators.

2.2 The four organization roles

2.3 Managing users (Org Admins)

1. Open Settings → User Management.
2. Invite: enter a work email, pick a role, press Send Invite. They receive a sign-in link and join with that role on first login, even from a domain you have not claimed.
3. Change a role: use the dropdown on the member's row.
4. Block: reversibly cuts a member's access (they keep their history); Remove is permanent. Nobody can block or demote the organization creator.

2.4 Enabling SSO (Org Admins)

1. In your identity provider (Microsoft Entra or Google Workspace), create an app registration with the redirect URI shown on your Account page (it ends in /api/v1/auth/sso/callback).
2. On the Account page, open the SSO card and enter the client ID, client secret, and (for Microsoft) the directory tenant ID, then enable it.
3. Add every email domain your staff sign in with under allowed domains, including alias domains, so nobody is turned away at the door.

Outcome: you can connect a supported system, verify it works, and stand up a connection to a system Weavr has never seen.

3.1 What a connection is

A connection is one system's credentials, stored encrypted on your instance and shared by every agent you attach it to. The catalog covers CRMs (HubSpot, Salesforce, Pipedrive, Dynamics), ERPs (Odoo), email (Outlook, Gmail), chat (Teams, Slack), finance (Plaid), IT (NinjaOne), databases, and more.

3.2 Creating a connection from the catalog

1. Open Connections and choose the system type.
2. Fill the required credential fields. For Microsoft systems this is a tenant ID, client ID, and client secret from an Entra app registration; the catalog entry lists exactly what each type needs and links to the vendor's documentation.
3. Press Test. A green result means Weavr reached the system with those credentials. Fix red results before saving; the error text names the failing step.
4. Optionally set a default target (for example a default mailbox for an Outlook connection). Agents can override it per call.

3.3 Quick Connect and the Connection Builder

If your system is not in the catalog, you do not wait for a plugin. Use Quick Connect: describe the platform (or just name it), and the Connection Builder designs a connector from the target system's own API framework: the endpoints, the auth style, the required fields, and a real read-only test request. You review the design, add credentials, and publish. The definition becomes available to your whole organization.

3.4 Health and hygiene

• When an agent reports "connection missing" or a tool silently does nothing, check that the agent actually has the connection attached and that the connection still tests green.
• Rotated a secret in the source system? Update the connection immediately; agents fail with a clear credential error otherwise.
• Delete connections nothing uses. Fewer live credentials is always better.

Outcome: you can take a business need from plain English to a saved, review-approved agent, and you know what every field in the editor does.

4.1 The guided Agent Builder (recommended path)

Open Agent Builder in the sidebar. The wizard has four steps:

1. Describe. State your role and the business need the way you would to a colleague. Name the systems your data lives in. You can attach files, add reference links, or dictate. Example: "I'm the director of sales. I want an agent that pulls our pipeline from our CRM with revenue history per client and recommends the next best action for every account."
2. Review. The frontier model returns a full design: name, objective, a numbered plan of exactly which tools it will call and in what order, the standing instructions, and an honest "Not covered" list for anything your request needs that the tools cannot do. Read the instructions. Edit anything. Nothing is saved yet.
3. Connect. The wizard shows which required systems are already connected and which still need credentials, with a Set up button for each gap. You can create the agent with gaps; it will say what it cannot reach rather than guess.
4. Create. The agent is saved and appears on the Agents page, configured to run on the cost-efficient default model.

4.2 The quick generate box

On the Agents page, Create Agent opens the editor with a "Describe the agent you need" box at the top. Type the need, press Generate with AI, and the whole form pre-fills for your review, including suggested tools, connections, and a schedule when the work is clearly recurring. You still press Save yourself.

4.3 Anatomy of an agent

4.4 Writing a system prompt like the platform does

Every strong Weavr agent prompt has seven parts. The builder writes these for you; when you edit by hand, keep all seven:

1. Persona: the professional role and who it reports to.
2. Objective: the business question a successful run answers.
3. Numbered execution plan: each tool by exact name, in order, and what feeds what.
4. Data rules: report real retrieved data only; never invent or estimate figures; say plainly when a source returns nothing.
5. Output format: the exact sections of the final report, in order, so every run is consistent.
6. Edge cases: what to do when a connection is missing, a tool errors, or data is empty. Say so and continue; never guess.
7. Tone: concise, professional, decision-ready.

4.5 Versioning

Every save creates a version. From the agent card, History lets you inspect and roll back, so experimenting with prompts is safe.

Outcome: you can execute agents on demand and on schedules, read run results, and diagnose the common failure modes.

5.1 Three ways to execute

• Run: the button on the agent card executes the run prompt once, now.
• Chat: talk to the agent directly for a one-off task within its tools and rules.
• Schedules: standing execution. Three types:
  • once: run at a specific time.
  • interval: run every N minutes.
  • inbox_poll: run continuously every N seconds, built for mailbox watching.
  Schedules persist across platform restarts and deployments; an active schedule resumes on its own.

5.2 Reading a run

The Monitor page is a live feed of everything the platform does. For a single agent, its card's Monitor view shows each run: the tools it called round by round, what came back, the final report, and any errors with a plain-language cause and fix. A well-built agent ends every run with the structured report its prompt demands, so you can skim runs in seconds.

5.3 Diagnosing failures

Outcome: you can compose multi-agent workflows on the canvas, run them in the background, and trigger them from outside systems.

6.1 The canvas

Open Workflow. Drag agents from the left rail onto the canvas and connect them. Every unconnected step receives the Client Ask (the request you type when running the flow); downstream steps receive the original ask plus the upstream agent's output plus your hand-off prompt, which tells the next agent what to do with what it received.

• Steps with no dependency on each other run in parallel.
• Ready-made templates (Inbox Summary → Draft Replies, Documents → Key Points, Analyze → Build Report, Plan My Day) are one-click starting points.
• Name and save flows to reuse them.

6.2 Hand-off prompts that work

A hand-off prompt is the contract between two agents. Be explicit about what arrives and what must leave: "You are receiving a list of categorized emails. Draft a reply for each one marked client-question, and output a table of subject, category, and draft status." Vague hand-offs ("continue the workflow") produce vague results.

6.3 Background runs and the queue

Workflows run in the background. Start one and keep working; the queue on the Workflow page shows each run's status (queued, running, completed, failed) and its per-step results. History is kept so you can compare runs.

6.4 Triggering from outside

Every saved workflow has a trigger endpoint, so any external system can start it:

POST /api/v1/agents/workflows/{workflow_id}/trigger
{ "message": "the ask", "source": "your-system", "context": { ... } }

The call returns immediately with a run id and a status URL. Combine this with Module 8's intake API and your other platforms can both report into Weavr and set it to work.

Outcome: you can read the usage dashboard, set guardrails, and explain exactly where every AI dollar went.

7.1 The guardrail stack

1. Plan ceiling: the hard monthly cap included in your tier ($50 Basic, $200 Standard, $750 Enterprise; Enterprise Max has none because it runs on your own keys). At the ceiling, model calls stop with a clear message. Nothing bills past it.
2. Platform daily and monthly limits: optional stricter limits you set in Settings → Usage & Cost Controls. You can lower your effective cap, never raise it above the plan.
3. Per-agent limits: daily request and cost caps per agent, plus an enable/disable switch. Cap experimental agents low.

7.2 Build cost versus run cost

Every model call is metered and categorized. Build is creation work: the Agent Builder, the Connection Builder designer, presentation and project-plan generation. Run is agents doing their day jobs, including every intermediate step in a tool loop and even failed provider attempts (which still consume input tokens). Your dashboard and, for platform admins, the Tenants page show both numbers, so "why was this month expensive" always has an answer: you built a lot, or you ran a lot.

7.3 Tiers and the trial

• Monthly plans start with a 14-day free trial that includes $5 of AI usage; the card on file converts automatically on day 15 unless cancelled.
• Trials are capped at $5 no matter the tier; conversion lifts the cap to the tier's ceiling.
• Enterprise Max bills annually, uses your own provider keys, and has no ceiling; its spend is your provider bill, not Weavr's.

Outcome: you can pipe events from any platform into Weavr, escalate errors to an agent automatically, and drive Weavr from your own software.

8.1 Event intake

Any system that can make an HTTP call can report into your instance:

POST /api/v1/intake/{source}/events
{ "events": [ { "level": "error", "message": "...", "timestamp": "..." } ],
  "instance_id": "optional" }

• Error events land in the Monitor feed with a diagnosed cause and fix.
• Identical errors repeating batch after batch are muted for six hours and surface once with a repeat count, so a stuck upstream cannot flood your feed.
• Set the WEAVR_INTAKE_API_KEY environment variable to require a shared key (X-Api-Key header) on intake calls.

8.2 Escalation agents

Name an agent "<source> support", "<source> intake", or "<source> monitor" (for example Kyni Support for source kyni) and give it a Teams or Outlook connection. When a batch brings three or more fresh errors from that source, Weavr hands the batch to that agent in the background to triage, group, and notify. One escalation per mute window, not one per batch.

8.3 The platform API

Everything the UI does, the API does: /docs on your instance is the full interactive reference. The endpoints you will use most from outside:

Outcome: your team asks an agent for work from the channel they already live in, and the answer comes back to that channel - drafts as attachments, long jobs with progress updates.

9.1 Slack - about a minute

Weavr runs one Slack app for the whole platform, so you install it rather than build anything. There is no app to create, no token to copy, and no secret to paste. Every organization installs that same app into its own Slack workspace and gets its own, isolated connection - your workspace can only ever be attached to your organization.

1. Install. Connections → choose Slack → Add to Slack. Slack shows one approval screen listing what the app can do; click Allow. You land back in Weavr, connected. The install is tied to your organization - it can never attach to anyone else's, and a workspace already connected to another Weavr organization is refused rather than taken over.
2. Requirements. Your Weavr subscription must be active - the install is refused otherwise, with the reason. Starting the install from Slack's own directory does not work by design: only a link that begins inside Weavr knows which organization you are.
3. Bind a channel. A channel answers only when it is bound to an agent or a workflow - an unbound channel says so rather than guessing. Create a channel (or use an existing one), then bind it from the guided setup, or via the API:

   POST /api/v1/slack/bindings
   { "team_id": "T…", "channel_id": "C…", "channel_name": "nimbus",
     "target_type": "workflow", "target_id": "<workflow id>" }

   Use "channel_id": "*" to set a workspace-wide default that also covers DMs.
4. Use it. In a bound channel, just type - every message goes to its agent, no mention needed. Elsewhere, mention the app - @Weavr draft a blog post on lead times - or DM it. If the workspace's app defines a slash command, that works too: the command name belongs to whatever the connection is defined as, not to Weavr itself, so each organization's app can name its own. You get an acknowledgement immediately, a progress note every 30 seconds on long jobs, and the answer when it lands. Replies in the same thread continue the conversation: if the agent asks a clarifying question, just answer it - no need to mention the app again. The same thread is where you give feedback. Reply with what you want different - shorter, add pricing, make it about Q3 - and the agent revises the piece and posts the updated version, keeping everything you didn't mention as it was. Keep going until it's right; that back-and-forth is the point, not a one-shot answer.
5. DMs pick their handler. A DM is its own channel, so it routes in order of how explicit you are: start the message with a bound channel's name - #nimbus draft a launch post - to use that channel's agent; once a #channel prefix has picked an agent, plain replies in that DM keep going to it - to whatever that channel is bound to right now - so answering an agent's clarifying question continues the work instead of starting over. Naming another bound channel switches; after two quiet hours the DM resolves the normal way again. Otherwise the workspace-wide * default answers if one is bound; and when the workspace has exactly one bound channel, a plain DM goes there automatically. A DM that can't resolve replies with the bound channels to choose from - never a dead end.

• Long answers arrive as a markdown attachment named after the piece, with a short summary in the message - not as a wall of chat.
• If Weavr restarts mid-run, the answer is delivered late or you are told plainly the request was interrupted. Silence is never the outcome.

9.2 Microsoft Teams - about five minutes, no administrator needed

Teams has no one-click install like Slack's. A conversational Teams bot normally needs an Azure Bot registration and admin consent - so Weavr uses Power Automate instead, which you build from inside Teams yourself. The flow does the talking: it catches channel messages, sends them to Weavr, waits for the answer, and posts it back.

1. Create an API key. The flow proves which organization it belongs to with a key. The guided setup creates one for you (shown once - paste it straight into the flow), or an org admin can mint one at POST /api/v1/api-keys/.
2. Pick the agent. Still in the guided setup, bind a channel name (or * as the default for every channel) to the agent or workflow that should answer. The flow you build next carries that name - you never look up an agent id, and you can change which agent answers later without touching the flow.
3. Start the flow. In the Teams channel: … menu → Workflows → create from blank. Trigger: When a new channel message is added, pointed at your team and channel.
4. Add the HTTP action. The guided setup generates this block exactly - copy it rather than typing. In outline: POST to /api/v1/teams/message with headers Content-Type: application/json and X-Weavr-Key: <your key>, and a body carrying the message text, the conversation id, and the channel name you bound in the previous step.
5. Post the answer back. Add Post message in a chat or channel, pick the same channel, and set the message to the HTTP action's reply field. Weavr answers synchronously, so the flow owns the whole round trip - there is nothing else to wire.
6. Try it. Post in the channel. If nothing comes back, Power Automate's run history shows each step's input and output - the failing step is highlighted, and the guided setup can read the error back to you in plain language.

Build the flagship sales agent end to end and prove every module at once. Allow 45 minutes.

Step 1: connections (Module 3)

Confirm your CRM connection tests green. If your CRM is unsupported, use Quick Connect to design the connector first. If you also bill from an ERP like Odoo, connect it too so revenue history is available.

Step 2: design (Module 4)

Open Agent Builder and describe: "I'm the director of sales. I want an agent that pulls our sales and lead pipeline from our CRM along with the revenue history for each client, then gives me a summary of the pipeline plus the next best action for every client, based on an engagement score built from active projects and services and how that correlates to average invoice size, so I can see which accounts we can grow and which are starting to slow down."

On Review, verify the plan: pipeline retrieval, portfolio retrieval, revenue summaries, engagement scoring, a CSV report, and a structured executive summary. Verify the instructions carry all seven prompt parts and an honest Not-covered list. Continue through Connect and Create.

Step 3: run and read (Module 5)

Press Run. In Monitor, follow the tool rounds and confirm the final report has the exact sections the prompt promised, with a downloadable CSV link. If the Kyni or CRM key is rejected, fix the connection and run again; the agent should have said plainly what it could not reach.

Step 4: schedule and govern (Modules 5 and 7)

Schedule it weekly (interval, 10080 minutes) and set a per-agent daily cost cap of $1. Check the usage dashboard after the run: the design shows as build cost, the run as run cost.

Step 5: compose (Module 6)

On the Workflow canvas, chain it into a second agent whose hand-off prompt produces a five-bullet summary for the leadership channel. Save the flow and note its trigger URL.

Pass criteria

• The agent runs green with a consistent, sectioned report and real (never invented) figures.
• Missing systems are stated plainly, not guessed around.
• The schedule survives a page reload; the workflow run appears in the queue with both steps completed.

Build a mailbox-watching agent that drafts replies in a person's own voice and never sends. Allow 45 minutes.

Step 1: the mailbox connection

Connect Outlook with credentials that can read the target mailbox and create drafts (the Microsoft Graph application permissions Mail.Read and Mail.ReadWrite).

Step 2: learn the voice

Create the agent with the sent-mail reading tool (outlook_list_sent_messages) plus inbox reading and the threaded draft tool (outlook_create_reply_draft). In chat, ask it to study the owner's sent mail in windows across recent months and produce a style profile: voice and tone, structure, characteristic phrases, response patterns, and verbatim example snippets. Paste the profile into the system prompt so the voice is fixed, not re-learned every run.

Step 3: the drafting workflow

Write the workflow section of the prompt with a strict tool budget: one client-list lookup, one inbox scan, one sent-mail snapshot to see what the owner already answered, then for each of at most five candidates: read the message, immediately create the threaded draft, move on. Skip newsletters, receipts, and anything already answered. End with a fixed-format run report. Above all: the agent never sends; drafts only. The draft tool also refuses to double-draft a thread that already has one, so polling is safe.

Step 4: schedule

Create an inbox_poll schedule at 300 seconds. Confirm the first cycle in Monitor, and confirm a real draft appears threaded in the mailbox's Drafts folder for a qualifying email.

Pass criteria

• Drafts appear on the correct threads, in the learned voice, and nothing is ever sent.
• Repeated polls never produce duplicate drafts.
• Money or contract emails are flagged in the run report, not drafted.