Canvas Basics
Asha needs an agent that answers WhatsApp messages from Acme Support's help docs — and she wants to try it before a single real customer sees it. The Agent Builder canvas is where all of that happens: you describe or draw the agent, wire nodes together, and test it on the same screen.
This page is for anyone building or editing agents for the first time. You'll learn how the builder is laid out, the three ways to add nodes (including letting Build with AI draft the whole agent), how nodes connect, how activation and publishing changes work, and how to test before you go live.

Creating an agent
Go to Build → Agents and click New Agent. The Create New Agent dialog asks for:
| Field | What it's for |
|---|---|
| Name | The agent's name in the list and toolbar. |
| Description (optional) | A one-line summary. |
| Tags (optional, comma-separated) | Labels for finding the agent later. |
| Compute | Where the agent runs: Standard (shared, runs instantly — right for most agents), Premium, or Dedicated (a machine reserved for this agent). You can change this later in the agent's settings. |
Click Create Agent and the builder opens on an empty canvas.
What you're looking at
The builder fills the screen and has five regions:
- a toolbar across the top — the agent name, its status, save state, and every top-level action;
- the Build with AI panel on the left — a co-pilot you can describe the agent to (collapse it with the
‹button); - the canvas — a dotted surface with zoom, fit-to-view and undo/redo controls in the bottom-left and a mini-map in the bottom-right;
- a node picker drawer that slides in from the right when you add a node;
- a properties modal that opens when you configure any node.
An agent is a graph of nodes. Flow nodes (a trigger, the AI Agent, a Condition, a Collect Info step…) run as steps, one after another. Agent parts (Personality, AI Model, Knowledge, Integration, Operator) hang off an AI Agent and describe it — they never run as steps of their own.
Build with AI
The fastest way to start is to describe the agent in plain language. On an empty canvas the Build with AI panel shows Describe your agent, a text box, and six starter recipes — Website support, Email support & triage, Order status assistant, Appointment booking, Lead capture, and FAQ bot. Clicking a recipe fills in the description for you.

Keep each message under 2,000 characters — a counter appears as you get close, and Build is disabled past the limit. To give the agent a long document, upload it to the Knowledge Base and connect the folder instead.
Press Build (or ⌘/Ctrl + Enter) and the co-pilot answers with a plan before it touches the canvas:
- a short numbered plan of what the agent will do;
- Which channels? — pick one or more of web, SMS, email, WhatsApp, and phone (at least one stays selected). For an agent that runs on a schedule, the card shows a Trigger (runs on a schedule) chip instead;
- Capabilities — chips the co-pilot suggests and you decide on: Knowledge Base, Integration, Call an HTTP endpoint, Query a database, Read a file, Google Sheets, Generate a report, Send email, Send SMS, Send WhatsApp, Reply on a messaging app, Make a phone call, Call another agent, Show cards / choices, and Human hand-off.

Adjust the chips, then click Build it →. The co-pilot builds a complete draft on the canvas — trigger, AI Agent, Personality, AI Model and the parts you chose — and then walks you through anything only you can provide, such as which Knowledge Base folder to answer from, right inside the chat. When everything is connected it tells you you're ready to publish. Nothing is activated for you: you review the draft and click Activate yourself.
Once the canvas has nodes, the same panel becomes Describe a change — ask it to "add WhatsApp" or "explain this" and it updates the canvas or answers. On an active agent, its edits land in your unpublished changes like any other edit (see Publishing changes).
Adding nodes by hand
The node picker
Click the orange + button on the right edge of the canvas to open the picker drawer. It has two levels: the first shows a card per category, the second lists the nodes in that category. Type in Search nodes… at any level to jump straight to a flat list of matches.
A node you pick here lands next to the node you have selected — or, with nothing selected, next to the last node of the flow — and is connected to it when it can follow that node, exactly as if you had used that node's own +. It is placed one card to the right, moved down if something is already there. A sticky note, your first trigger, or a node that can't follow the last one gets a free spot without a connection.

| Category | What it holds |
|---|---|
| Triggers | What starts the agent — under Channels: Phone Call, SMS, Email, WhatsApp, the messaging apps (Telegram, Slack, Messenger, Instagram, Microsoft Teams, Discord, Google Chat, RCS — "On a message to your … bot") and Web Chat; plus Webhook, Schedule, Internal Event, Knowledge Base, Folder Watch, Sub-Workflow and Manual Test. See Trigger Nodes. |
| Core | The backbone: AI Agent, Agent Team (a supervisor coordinating several worker agents), Condition (IF/ELSE), and Human Handoff. |
| Agent Parts | What an AI Agent is made of: Personality and AI Model (both required), Integration, Knowledge, Operator, and Action (run another agent). |
| Actions | Tools the agent can use, grouped as Messaging (Email Sender, SMS Sender, WhatsApp Sender, Chat Sender — reply on a messaging app, in the chat the customer wrote from — and Phone Caller), Integrations (HTTP Request, Google Sheets), Databases (Postgres, MySQL, MongoDB), Documents (Extract Document, Detect Document Type and ready-made document types), and Memory (Upload Document). Handing off to a person is set on the Operator part, not added as an action. See Actions. |
| Output | Render View (turn data into a picker, cards or a checklist) and Track Event. |
| Agent process | The lightweight steps of an agent's Steps sub-flow — Ask agent and Tool. |
| Data | Collect Info, Look up Data, HTTP Request, and KB Index (index a previous step's output or a URL into a Knowledge Base folder). |
| Documents | Document Processing and its presets — Audio → Transcript, Spreadsheet → Text, File → Text (raw), Medical Report, Invoice / AP, Resume / ATS, Contract / Legal, and more. |
| Annotations | Sticky Note — a canvas-only comment. |
The picker only ever offers what can legally go where you are adding it. An empty canvas offers only Triggers. After a flow node it offers the next steps (no second trigger in a row). On an AI Agent's port it offers only the part that fits that port.
Every "+" on the canvas
Nodes can be added from several places, and each one opens a picker already filtered to valid choices:
- the orange + on the right edge of the canvas (the drawer above);
- the + on a node's right edge — What happens next?;
- the + that appears at the middle of a connection when you hover it — inserts a node between two nodes;
- the + under each of the AI Agent's ports — Add Personality, Add AI Model, Add Action, Add a step, and so on;
- the + on the AI Agent's left edge — What triggers this? — which adds another trigger feeding the same agent.
Connecting nodes
Every + is also a connection handle. Click it to open the picker, drag it onto another node to connect the two, or drag it onto empty canvas to add and connect a new node in one move. While you drag, the line turns green over a valid target and red over an invalid one.
Two rules are checked before any connection is made:
- The right kind of node. Flow nodes connect to flow nodes; each AI Agent port accepts only its own part (a Personality port accepts a Personality, the Action port accepts action tools, and so on).
- One-of-a-kind ports. An AI Agent takes exactly one Personality, one AI Model and at most one Operator — a second connection to those ports is refused.
One agent can have several triggers — for example Web Chat, WhatsApp and Email all feeding the same AI Agent — so you build the conversation logic once and serve every channel.
Working on the canvas
Node toolbar. Hover a node to see three small buttons above it: Execute step (opens the node's panel), Delete node, and More actions. More actions opens a menu with Open…, Execute step, Rename, Copy, Duplicate and Delete.
Keyboard shortcuts.
| Action | Shortcut |
|---|---|
| Undo | ⌘/Ctrl + Z (or the undo button in the bottom-left controls) |
| Redo | ⌘/Ctrl + Shift + Z or ⌘/Ctrl + Y (or the redo button) |
| Copy / Paste | ⌘/Ctrl + C / ⌘/Ctrl + V |
| Duplicate | ⌘/Ctrl + D |
| Delete selected nodes | Delete or Backspace |
Undo keeps the last 50 changes. Copies and duplicates keep the connections between the copied nodes and land slightly offset from the originals. A copy never carries a stored secret (for example a webhook or HTTP authentication secret) — set it again on the copy. All canvas shortcuts are switched off while a node's properties modal is open, so pressing Delete inside a text field never deletes the node behind it.
Zoom. The canvas opens fitted to the window. Zoom from 10% to 200% with the controls or your trackpad; the mini-map helps on large agents.
Validation — errors and warnings
The builder checks the agent continuously and shows the result in a banner under the toolbar:
- Validation errors — cannot publish (red). These block Activate and Publish changes, and the node at fault gets a red marker. Typical errors: no trigger, no AI Agent, an AI Agent without exactly one Personality and one AI Model, or a channel trigger with no business contact picked. Click an error to open that node; its properties modal lists every problem on it so you can fix them in one go.
- Warnings — you can still publish (amber). Worth a look but not blocking — for example, an Email or WhatsApp trigger with no matching sender node, which means the agent will receive messages on that channel but not reply on it.

The ✕ on the banner hides it; the checks keep running.
The properties modal
Double-click a node (or choose Open…) to configure it in a centred three-pane modal: Input on the left (the variables available to this node), the node's configuration in the centre, and Output on the right (the variables it produces). The centre has Config, Settings and Notes tabs. Changes save automatically — there is no Save button — and Escape closes the modal. See The Properties Modal.
Variables — {{ }} expressions
Many fields accept {{ }} expressions that are filled in when the agent runs. The Input pane lists everything reachable from the node, grouped by where it comes from:
- Trigger — for example
{{ trigger.channel }},{{ trigger.customer_id }},{{ trigger.subject }}and{{ trigger.attachments[0].url }}; a Webhook adds the request body, query and headers; - Customer — the customer's phone, email and id;
- Each earlier node's outputs — for example the AI Agent's reply, or an HTTP Request's status and body.
Click ↵ next to a variable to insert it into the field you're editing, or the copy icon to copy its path. Fields with a {x} button open the same picker inline. Parts such as a Personality see the variables of the AI Agent they belong to.
Expressions only read values — they never run code — so a template or condition can't do anything unexpected.
The toolbar
Left side: Back, the agent name (click to rename — Enter saves, Escape cancels), a status pill — green Active (answering customers) or grey Inactive — an amber Unpublished changes chip when an active agent has edits customers don't have yet, an Auto-save on chip, and a save indicator (Saving…, Saved 5s ago).
Right side: Import (load an agent from a .json file), Export, the settings gear, the Editor / Runs switch, and the lifecycle buttons:
- an Inactive agent shows Activate. It's disabled while there are validation errors — hover it to see how many.
- an Active agent shows Deactivate, which takes it offline so it stops answering.
- an Active agent with unpublished edits also shows Discard and Publish changes (below).
On a phone-sized screen these actions collapse into a single ⋮ menu.
Activating — and what "live" means
Everything autosaves about a second and a half after you stop editing. Activate checks the agent and puts it live; from then on it answers on every trigger it has. Until an agent has been activated, your edits simply save onto it.
Publishing changes to an active agent
Once an agent is Active, editing it no longer changes what customers get. Your edits still autosave, but into unpublished changes — customers keep talking to the version you last published.
- The toolbar shows Unpublished changes ("Customers still get v3 — publish to make these edits live, or discard them.").
- Publish changes checks the agent and makes your edits the new live version (v4, v5, …). It's disabled while there are validation errors. If the edits changed while you were publishing, you are asked to publish again.
- Discard (after a confirmation) throws your edits away and goes back to the version customers have now. Changes to sub-flows the agent runs are published or discarded with it.
- Tests in the builder — the Web Chat Live preview and a trigger's Execute / Run now — run your unpublished changes, so you can try them before any customer sees them. Those test runs show in the agent's Runs.
- If your edits end up identical to the live version, the unpublished changes simply disappear. Deactivating the agent makes your edits its saved version.

Agent settings
The gear in the toolbar opens Agent settings with two tabs:
- Compute — switch between Standard (shared), Premium and Dedicated. Dedicated gives the agent its own machine, which is prepared when you apply the change (or when you activate) — the status pill shows Provisioning until it's ready.
- Reusable agent — Save this as reusable agent turns the canvas into a template in the Agent Marketplace, with a name, description, category and tags. Business contacts and provider keys are removed so the template is portable; the persona, model choices, integrations, knowledge references and all other settings are kept.
Testing before you go live
- Web Chat live preview. Open a Web Chat trigger and click Live preview. A working chat widget opens beside the settings and runs your current draft — including an active agent's unpublished changes, no activation needed — so you can chat with the agent, try voice, and upload files. Test as lets you pretend to be a known customer by phone, email or your own customer id. Every change to the widget settings shows in the preview straight away, and the widget's ⛶ button fills your whole browser window. See Trigger Nodes.
- Manual Test trigger. Add a Manual Test trigger, paste a sample payload, and click Execute to run the draft once; a toast confirms it and the run appears in Runs.
- Schedule — Run now. A Schedule trigger has a Run now button that fires one run of the draft immediately instead of waiting for the next scheduled time.
- Test on external site (in the Web Chat trigger's install view) runs the published agent only.
A structurally incomplete draft still fails with a clear error rather than silently doing nothing.
A worked example — Asha builds an FAQ agent for Acme Support
Setup: Asha clicks New Agent, names it "Support Agent", and in Build with AI picks the FAQ bot recipe. The plan card suggests the web channel and the Knowledge Base capability; she also ticks whatsapp and clicks Build it →. When the co-pilot asks which folder to answer from, she picks "Help Center".
Action: She opens the Web Chat trigger, clicks Live preview, and asks "What are your support hours?". The draft answers from the Help Center folder. The validation banner shows one error — the WhatsApp trigger has no business contact — so she opens it and picks Acme Support's WhatsApp number. The banner clears and she clicks Activate.
Result: A customer named Priya messages Acme Support on WhatsApp: "What are your support hours?" The WhatsApp trigger fires, the AI Agent answers from the same folder, and Priya gets her reply.
What just happened: Build with AI drafted the whole agent; the live preview let Asha test it without going live; validation caught the missing WhatsApp number before any customer could hit it; and one AI Agent now serves both web chat and WhatsApp.
Replaying past runs
Click Runs in the toolbar to see every past run of the agent. Each run replays on a read-only copy of the canvas, with every node coloured by how it did, and a bottom panel with Chat, Logs, Diagram, Tokens and Usage tabs.

See Runs & Executions for the full tour.
What's next
- AI Agent Node — configure the centre of every agent.
- Trigger Nodes — every way an agent can start.
- The Properties Modal — Input / Config / Output, Settings and Notes.
- Condition (IF/ELSE) — branch a flow.
- Agent Marketplace — start from a ready-made template.
- Runs & Executions — debug past runs.