Teams & mesh

In one line. Two ways to compose many runnables when one agent isn’t enough — an in-process Multi-Agent Team (a leader delegating to member agents) and a durable, restart-proof Mesh (a pipeline wiring runnables together by queues). You’ll be able to. Build a 2-member team from the Subagents tab, recognise the Mesh designer, and decide between Team, Mesh, and XFlow for a given job. Where this lives. Studio > Agents > Agent Toolkit > Agents — the same list and + Agent picker you already know.

When one agent isn’t enough

One agent is the right answer surprisingly often. Reach for composition only when a single agent genuinely can’t do the job well:

Specialists. The work splits into distinct skills — an extractor, a fraud-checker, a summariser — and you want each tuned and tested on its own, not crammed into one mega-prompt.
Parallelism. Two independent checks (credit and compliance) can run at the same time instead of one-after-the-other.
Long, durable, multi-stage automations. The whole process takes minutes, has branches and joins, and must survive a restart without losing its place.

The platform gives you two tools for this, and they are not the same thing. Learn the difference once and you’ll always pick the right one:

	Multi-Agent Team	Mesh
What it is	One leader agent delegating to member agents	A pipeline wiring runnables by queues
Runs where	Inside one agent run	Across steps, each hand-off written down first
Members are	Other agents only	Any runnable: agent, XFlow, mesh, or Service
Survives a restart?	No (it’s one live conversation)	Yes (a hand-off in flight is not lost)
Reach for it when	Several specialists must collaborate right now	A long, branching, multi-stage automation

Why the difference. A team runs entirely inside one agent run; a mesh hands work between members over durable storage. That is why only a mesh survives a restart — and why only a mesh can have an XFlow or a parked Service as a member.

Multi-Agent Teams — the Subagents tab

A Multi-Agent Team is just an ordinary agent that has subagents. You don’t create a separate “team” object — you add subagents to an agent on its Subagents tab, and that agent becomes the leader. In the list it still carries the A kind badge (tooltip “Multi-Agent”), and the Kind filter has a Multi-Agent option to find them.

The leader is the agent you’re editing — its Persona and Instructions decide how it delegates and synthesises. Each subagent row adds one member agent, picked from agents in the project. Until you add the first one, the tab just invites you to add a child agent — and says, correctly, that doing so turns this agent into a coordinator over the team.

Control	What it does	Notes
Coordination mode	How the leader uses its members	The four modes below. Appears once you have at least one subagent.
+ Add subagent	Adds a member row	Adding the first one turns this agent into a coordinator/team leader.
Agent (per row)	Which existing agent is this member	The dropdown lists team-eligible agents in the project.
Prefix instructions	Extra instructions prepended for this member	Use it to tell one member how to behave inside the team.
Reasoning toggle	Lets this member use extended reasoning	Costs latency; turn on only where it earns its keep.
Remove (x)	Drops the member	Removing the last member makes the agent a plain single agent again.

Member approvals live on the agent’s Governance tab, in the Approvals section under Team agents — you can require a human’s approval before the leader hands work to a specific member.

The four team modes

Coordination mode is the single most important choice — it decides how the leader uses its members:

Mode	What the leader does	One-line example
Auto Select	Picks one member best suited to the request and hands off	A triage leader sends a billing question to the Billing agent, a returns question to the Returns agent.
Collaborate	Runs all members in parallel on the same input, then combines	Three reviewers each red-flag a contract at once; the leader merges the flags.
Coordinate	Delegates sub-tasks to members, then synthesises their answers into one	“Read this claim” → asks Extractor for fields and Policy-checker for coverage, then writes the recommendation.
Sequential	Pipes output member → member in order	Extract → normalise → summarise, each step consuming the previous one’s output.

Watch out. A team runs as one in-process agent run — it does not survive a restart, and every member is an agent (you can’t drop an XFlow or a Service into a team). If you need either of those, you need a Mesh, not a team.

Build one — a 2-member sequential team

Open Studio > Agents > Agent Toolkit > Agents. Select (or create) the agent you want as leader — say Claims Lead — and click Edit.
Go to the Subagents tab. Set Coordination mode to Sequential.
Click + Add subagent. In Agent, pick your first specialist (e.g. Field Extractor). In Prefix instructions, add a line like “Extract every field; output JSON only.”
Click + Add subagent again. Pick the second specialist (e.g. Risk Scorer) and prefix it “Read the extracted fields above and score risk 0–100.”
Click Save Agent. Order matters in Sequential mode — Field Extractor runs first, its output feeds Risk Scorer.
Open the Playground: send a sample document and watch the leader run the two members in order.

Mesh — the durable pipeline designer

A Mesh is a durable pipeline that wires runnables together by queues. Each node is a member that references any runnable — an agent, an XFlow, another mesh, or a Service — and members hand a small baton (the payload passed along, not a step’s return value) to the next through a queue. Each hand-off is written down before the next member picks it up, so a mesh survives a restart: a baton mid-flight is not lost. That is the whole reason Mesh exists and Teams don’t cover it.

Advanced surface — always available. The Mesh designer is the XFlow designer in mesh mode, not a separate screen: + Agent ▸ Mesh is offered whenever you can add an agent. In mesh mode the palette narrows to exactly three tiles — Xflow Operator, Queue and Service. Treat this section as “recognise it and understand the model”; most builders ship Teams and XFlows long before they author a Mesh by hand.

From the Agents list footer, + Agent opens a three-option picker:

Option	Opens
Agent	The single/team agent builder.
XFlow	The XFlow create dialog → the visual pipeline designer (XFlows & pipelines).
Mesh	The same create dialog in mesh mode — the palette narrows to Xflow Operator + Queue + Service.

A saved Mesh appears in the list with the M kind badge; selecting it swaps the right pane to the embedded designer in mesh mode. The designer has Mesh, Runs and Status tabs, plus Save Mesh and Run actions; members are the nodes, queues are the boxes between them, and the baton is the output that hops.

Control	What it does	Notes
Xflow Operator node	A member referencing a runnable	The member’s “work” — an XFlow, agent, or mesh.
Queue node	The pipe between members	Node→queue = publish; queue→node = subscribe. Carries the baton.
Service node	A parked member	The member sits `awaiting` while an external worker does long work — see below.
Save Mesh	Saves the mesh	It then appears in the Agents list with the M badge, alongside your agents and XFlows.
Run	Starts a mesh run	Results land in the Runs tab.

Behaviours to know — long steps, fan-out, fan-in

A member is expected to finish its own step, not to hold the line for hours. If a step is genuinely long-running — a GPU model, OCR on a 200-page scan, an overnight batch, a slow partner API — make it a Service (LLMs & services) rather than an ordinary member, or the run risks timing out on it. As a Service, the member parks in an awaiting state holding no worker, your external program pulls the job and does the work, then reports back and the member resumes. Parking can wait minutes or hours without tying up platform resources.
Fan-out (1→N). Two members subscribed to the same queue both receive the baton and run one after the other. To run branches at the same time — e.g. score-credit and check-fraud at once — give each branch its own queue: separate queues are dispatched concurrently.
Fan-in (N→1). One member with two incoming queues runs once per arriving baton — it does not wait by itself. To act only when everything is in, the member asks bm.mesh_gather_when_complete — only the run whose arrival completes the set gets the batons; the others stay silent — e.g. decide hands on only after both credit and fraud have reported.
A run is done when nothing is running, nothing is waiting in a queue, and nothing is parked.

                       ┌──────────┐
        document ─────▶│  intake  │ (member: XFlow)
                       └────┬─────┘
                       publishes baton
                    ┌───────┴────────┐  fan-out: a queue EACH, so they run in parallel
              ┌─────▼─────┐    ┌──────▼──────┐
              │  score    │    │  check      │   <- run in parallel
              │ (XFlow)   │    │  fraud      │
              └─────┬─────┘    │ (Service)   │   <- parks; an external worker does it
                    │          └──────┬──────┘
                    └──────┬──────────┘  fan-in: decide gathers, acts when BOTH are in
                       ┌───▼────┐
                       │ decide │  (member: agent) -> writes the doc Summary
                       └────────┘

Try it, but don’t save: open + Agent ▸ Mesh, drop two Xflow Operator nodes with a Queue between them, and read the Mesh and Runs tabs. The goal is to recognise the surface, not to ship a mesh.

How a team or mesh is run and observed

A Team runs whenever its leader agent runs — from the Playground, as a collection’s intake agent, or wherever a single agent would run. There’s no separate “team run”; you observe it on the leader’s Runs tab and watch the member hand-offs live in the Playground transcript.
A Mesh runs from Run in the designer, or as a collection’s intake runnable — a collection can hand each arriving document to a mesh exactly as it would to a single agent. Observe it on the designer’s Runs tab: a run list, and behind each run a readable Run trace — the run’s status, how many stages and hand-offs it has, the members laid out as a pipeline with a state each (done / failed / running / awaiting) and per-member logs, a progress summary, and the Baton trail of hops with the payload that moved.

For observing agent, xflow, and mesh crews as they run, see Crew & evaluations.

Tip. The awaiting state in a Run trace is your friend — hover it and it says the member is parked, waiting on an external Service. That member is waiting on your external worker, not stuck. The Baton trail shows exactly which hop is in flight.

Team vs Mesh vs XFlow — which do I reach for?

Need	Use	Why
One job, several agent specialists collaborating now	Multi-Agent Team	Delegation inside one run; fastest to build (just the Subagents tab).
Deterministic, multi-step processing of each document (python, SQL, API, agent call)	XFlow (A10)	A single pipeline of operators; no durable cross-runnable wiring needed.
Long, branching, multi-stage automation that must survive restarts	Mesh	Hand-offs are written down; members fan-out/fan-in; members can be XFlows/agents/meshes.
A genuinely long-running step (GPU/OCR/overnight/slow partner API)	Mesh + Service (A2)	The member parks while an external worker pulls and does the work.
Pick one of several agents per request	Team (Auto Select mode)	Leader hands off to the single best member.
Two independent checks at the same time, then a join	Mesh (fan-out → fan-in)	Parallel members (a queue per branch) with a durable, member-gated join.

Watch out. Don’t reach for a Mesh just because you have “several agents.” If they collaborate inside one conversation and don’t need durability, a Team is simpler. Mesh earns its complexity only when you need durability, cross-runnable members, or true parallel fan-out/fan-in.

Where to go next

Library & bots — the reusable Python assets and RPA workers that mesh nodes and tools draw on.
Your first agent — a single agent’s anatomy, including the Subagents tab.
XFlows & pipelines — the pipeline primitive and the Runs tab in depth.
LLMs & services — long-running external work via parked Services.