The multi agent flow canvas
A multi agent runs the exact steps you design, in the same order every time. You author those steps on the flow canvas - a visual node graph where each node does one job and the lines between them decide what happens next. Open a multi agent from the Multi agents tab on the Agents page, or create a new one from the Create picker, and the canvas opens at /build/flows/<slug>?from=guided-agents.
This page is a tour of the canvas: the tabs and toolbar, the Start node, the node types you wire together, how branches connect them, and the journey variables that carry data across the flow. The Agent node - the workhorse node where most of your logic lives - is documented in depth on its own page.
The canvas tour
When you open a multi agent, the header carries the flow's name plus a few actions, and the body is a scrollable, zoomable node graph.
A multi agent is a graph of nodes wired by each node's exits. A typical order-return flow looks like this:
Tabs
The canvas has three tabs:
| Tab | What it's for |
|---|---|
| Editor | Build the flow - add nodes, write their instructions, and wire branches. This is where you spend most of your time. |
| Execute | Run the flow end to end and watch it step through your nodes, so you can confirm the path a given input takes. |
| Logs | Inspect past runs - which nodes fired, which exit each one took, and the variables along the way. Use this to debug a run that didn't go where you expected. |
Toolbar actions
- Run - start a test conversation against the current draft of the flow, without publishing. Use it constantly as you build.
- Publish - make your edits live. Unlike single agents, a multi agent has no Live/Draft status badge in the list - publishing is how your canvas changes reach customers.
- What's new - release notes for the canvas itself.
- Search for nodes - a search box that finds a node by name and jumps to it. On a large flow with a dozen nodes, this is faster than panning the canvas.
Navigating the graph
The canvas is a node graph built on React Flow. To find your way around:
- Minimap - a small overview of the whole graph in the corner; click or drag within it to jump to a region.
- Zoom and fit - zoom in/out and a fit-to-screen control to frame the entire flow.
- Auto-layout - re-tidies the nodes into a clean top-to-bottom arrangement after you've added or rewired several. Reach for it when the graph starts to look tangled.
Tip - let auto-layout do the tidying. Don't fuss over pixel-perfect node placement while you build. Wire the logic first, then run auto-layout to make the flow readable. Position is cosmetic; the branches are what matter.
The Start node
Every multi agent begins at a single Start node. It is the entry point of the graph and it carries the trigger - the natural-language description of when this multi agent should run.
The trigger plays the same role here that an agent's Trigger plays for a single agent: it's how the bot decides this multi agent is the right thing to run for an incoming request. Write it the same way - concrete about the situations it covers, and explicit about what it does not handle.
Example trigger. "When the customer wants to return or exchange an item they've already received - start a return. Do not handle order tracking or delivery-status questions; those have their own agent."
The Start node has exactly one outgoing edge: it hands control to the first real node in your flow (usually an Agent node). From there, the path is decided by each node's exits.
Note: Multi agents are reachable from your single agents as delegation targets, not through the tools picker. Open Routing Logic and look at Available agents - a single agent can hand off a multi-step task to a multi agent the same way it would hand off to any other agent; there's no separate "use as tool" toggle. See the Agents page overview for how the two agent types relate.
Node types you wire together
A multi agent is built from nodes, each with a focused job. You drop a node onto the canvas, configure it, and connect it to the next node by its exits. The most common node types:
| Node | What it does |
|---|---|
| Start | The flow's single entry point. Carries the trigger that decides when the multi agent runs. One per flow. |
| Agent | A focused agent that owns one step of the conversation - collect details, confirm a choice, answer a scoped question. It has its own instructions, tools, variables, and exits (the outcomes it can finish on). This is where most of your logic lives. See The Agent node. |
| Execute Workflow | Calls a workflow - a callable, deterministic skill (an API call, a lookup, a record update). Use it when a step is pure business logic with no conversation, e.g. check return eligibility or book a pickup slot. Available in every v3 flow. |
| Transfer to Agent | Hands the conversation to another agent or flow, then ends this one. Use it as the exit path when a different agent or flow should take over - for example, escalating to a specialist agent, or (paired with the Escalate to Agent tool) an explicit "talk to a person" request. |
The node search/palette offers more node types than the four above - open it from the canvas to see everything available for your bot. Build the backbone of your flow with Agent nodes, and reach for Execute Workflow and Transfer to Agent at the points where the journey needs to run logic (Execute Workflow) or hand off to a different agent or flow (Transfer to Agent).
A multi agent is never a "workflow." "Workflow" is a reserved, distinct term - a callable scheduler skill you build in the workflow editor and invoke from an Execute Workflow node (or as a Workflow tool). The multi agent is the conversation; a workflow is a subroutine it can call. Don't conflate the two.
Branches and edges
Nodes connect to each other through exits. Each node finishes on one of its named exits, and each exit is an output handle that you wire - with a branch (the line on the canvas, an edge) - to the next node that should run.
How it works:
- An Agent node declares a list of exits, each a label plus a short natural-language description of when it applies. For example, an order-return node might exit on
eligible,not_eligible, ormax_retry(the user couldn't decide after a few attempts). Every node also has anon_errorexit for the failure path. - You connect each exit to a target node by dragging a branch from the exit's handle to the next node's input. That branch is the routing: when the node finishes on an exit, control follows that exit's branch.
- An exit that isn't wired anywhere ends the flow after that node. Wire the exits you want to continue; leave terminal outcomes (e.g. a successful completion) unwired to finish.
- Branches can point forward (collect → confirm) or back to an earlier node (e.g. confirm → collect to re-collect a changed detail), letting you build loops and retries.
Because every path is an explicit branch you drew, a multi agent's behaviour is deterministic and auditable: there's no path through the flow that you didn't wire. That predictability is the whole point of choosing a multi agent over a conversational one for multi-step, must-not-miss-a-step journeys.
Note: An exit's description is for the Agent node - it's how that node's agent decides which outcome it has reached (e.g. "if the intent is a return", "when the user can't decide after 3 attempts"). The branch is how the canvas turns that outcome into the next node. You author exits and their descriptions inside the node; you draw branches on the canvas. See The Agent node for authoring exits.
Journey variables
A multi agent has its own journey variables - flow-local memory shared across every node in the flow. Use them to carry data from one step to the next: an order_id collected by an early node, a return_eligible flag set by an Execute Workflow node, a pickup_slot chosen later on.
- Scope. Journey variables are local to the flow. They're the flow's working memory, separate from the bot-wide global memory that every agent shares. An Agent node reads and writes them through its Variables capability; an Execute Workflow node can read inputs from them and write its results back.
- They persist across nodes within a run. A value written in step one is available in step five - that's what lets a multi agent "remember" what it has collected as it walks the journey.
- Global memory still works. If a value needs to be visible to the rest of the bot (not just this flow), use a global memory variable instead. Reach for a journey variable when the data only matters inside this flow.
See Memory in Nexus agents for the full memory model and when to choose local (journey) vs global.
Step 1: Add a node
In the Editor tab, open the node search/palette and pick the node type you want - for an order-return flow, you might add an Agent node to collect the order ID. Drop it onto the canvas. (You can also let the AI layer scaffold the node from a description.)
Step 2: Configure the node
Click the node to open its configuration drawer and give it a clear job. For an Agent node that means a Name, its Instructions (the goal/prompt), any Tools, Variables, and its Exits - the outcomes it can finish on. The full walkthrough is on The Agent node. For an Execute Workflow node, pick the workflow to call and map its inputs from your journey variables.
Step 3: Wire its exits
Drag a branch from each exit handle to the node that should run next:
- Wire the success exit (e.g.
eligible) to the next step in the journey. - Wire fallback exits (e.g.
not_eligible,max_retry,on_error) to a Transfer to Agent node, or back to an earlier node to retry. - Leave any terminal exit unwired so the flow ends cleanly there.
Step 4: Run and refine
Click Run to start a test conversation and walk the path your input takes. If a run goes somewhere unexpected, open the Logs tab to see which node fired and which exit it took, then adjust the node's instructions, its exit descriptions, or the branch wiring. When the flow behaves the way you want, click Publish to make it live.
Tip - test the unhappy paths first. It's easy to get the success path right. The value of a multi agent is that the edge cases also stay consistent. Run the flow with inputs that should hit
not_eligible,max_retry, andon_error, and confirm each lands somewhere sensible (usually a Transfer to Agent or a graceful end). See Testing a multi agent.
Continue to: The Agent node - the node where each step's goal, tools, variables, and exits live.