Skip to main content
The question is not “how many agents can I have” but “where do the boundaries go”. This page covers the two shapes worth building, how a message reaches an agent, and the four things that have to agree for routing to keep working.

​
Two shapes

One agent. A single agent holding every tool. Correct more often than people expect. Prefer it until tool selection starts to degrade — the model reaching for the wrong tool, or ignoring one it has. A flat network. A routing classifier reads the message and hands the whole turn to exactly one agent. No orchestrator answering on top, no agent-to-agent chatter. There is deliberately no third shape. A hub agent that answers and delegates costs an extra model round-trip on every turn and blurs responsibility for the answer.

​
Sub-agents are not a third shape

Any agent may own sub-agents — internal workers it calls like tools. A sub-agent is a capability of its parent: it is never a routing destination, and your users never see it named. Use one when a specialist needs a self-contained job done (summarise these 40 reviews) without spending its own context on it. Sub-agent work happens inside the parent’s turn and shows up in the trace’s participants, so it stays inspectable.

​
How a message reaches an agent

1

The message arrives at the network

It comes with the last few turns for context.
2

The classifier picks one agent

It reads the roster — each agent’s description — plus your routing instructions, and picks one agent.
3

That agent takes the whole turn

The decision is emitted on the stream before the answer starts, as a data-handoff chunk carrying the target, the reason, the confidence and the latency, so the widget can show where the turn went.
The classifier sees a short transcript — the last three stored messages plus the new one — and is told which specialist answered the previous turn, so a follow-up like “and what about Berlin?” stays with the specialist already handling it rather than being judged as a fresh question. When it isn’t sure, it asks. Rather than guessing and answering from the wrong agent, the network can return one short clarifying question in the user’s own language. The question is saved to the thread, so the reply routes correctly with that context. It is capped at two consecutive clarifications — after that the best guess runs. Turn routing off for a request with use_routing: false.

​
Writing the roster

Each agent’s description is a routing instruction, not a bio. It is what the classifier reads. Write what the agent handles, in the vocabulary your users actually use — and, where two agents are adjacent, what it does not handle.
Routing instructions live on the network. Domain definitions, tie-break rules and “always prefer X for Y” go here, alongside the candidate list. This is where you resolve the collisions no single description can settle. Give the network a generalist, and put it first. Roster order is routing order, and the first agent is where a turn lands when classification fails outright. A support-style agent with no API tools but every rich UI component can answer “what can you do”, demonstrate the surface, and absorb the questions no specialist owns. Low-confidence turns are not sent to it: they get a clarifying question, at most twice, and then the classifier’s best guess — so the generalist’s description should claim the general ground explicitly rather than rely on being a catch-all.

​
The four things that must agree

Moving a capability from one agent to another touches four places. Move all four, or routing quietly keeps honouring the old arrangement:
  1. The roster — which agents are attached to the network.
  2. The routing instructions — the ladder and its examples.
  3. The receiving agent’s tools — it must actually hold the tools for what it now owns.
  4. Both agents’ descriptions — grant on one side, revoke on the other.
The common failure is a half-move: routing sends catalogue lookups to an agent with no catalogue tools, while the agent holding those tools sits in the roster with an empty description, reachable only by accident. Every capability move is a two-sided edit. The matching failure inside an agent: instructions that name a capability whose tool isn’t attached. The agent either dead-ends or improvises. After any change, check both directions — every tool named in the prompt is attached, every attached tool is accounted for.

​
Follow-ups

After each answer the network can propose up to three follow-up questions, rendered as chips. Each chip carries the agent that should answer it, chosen from the live roster — so tapping one skips routing entirely. A question no single specialist cleanly owns is dropped rather than shipped untargeted, which makes the chips a useful read on whether your boundaries are clean: if few survive, your agents overlap. Guidance for follow-ups is itself an instructions array, so it supports variables, display rules and your shared prompt blocks.

​
The platform agents

Three agents come with every network and are not part of its roster: the handoff classifier that routes a turn, the follow-up suggester that proposes the chips, and the dashboard agent that builds dashboards with the user — in its own conversation, or on behalf of any roster agent that hands it a build with build_dashboard. Each runs on a platform default; a network can override what it needs under system_agents on PATCH /v1/copilots/{id}:
Per agent: model_slug and model_settings (as on an agent version), memory (for the agents that keep one), instructions — an instructions array like an agent’s own, with variables, display rules and your shared prompt blocks — and enabled: false to switch the dashboard agent off for this network. Absent keys keep the defaults. handoff.instructions and followup.instructions take precedence over the older handoff_prompt and followup_instructions fields. The block is copied by POST /v1/copilots/{id}/deploy with the rest of the configuration.

​
Testing routing

Routing is the part of a network you cannot eyeball. Build a golden set — real user phrasings, each with the agent that should take it — and run each one through POST /v1/copilots/{id}/run. The collected response includes the data-handoff decision, so a short script can compare the chosen agent with the expected one after every roster or instruction change. Include the awkward cases: follow-ups that change subject, messages that name two domains, one-word replies. Experiments target one agent version at a time, so use them to test what each specialist answers; the golden set above tests where the turn goes.

​
Checklist

  • Start with one agent; split only when tool selection degrades.
  • Every agent has a description written for the classifier, with boundaries.
  • Collisions are resolved in the network’s routing instructions, not by lengthening descriptions.
  • There is a generalist, first in the roster, whose description claims the general ground.
  • Every capability move is applied in all four places.
  • A golden set covers your real routing decisions and runs after every change.