Multiagent orchestration

Multiagent orchestration lets one agent coordinate with others to complete complex work. Agents can act in parallel with their own isolated context, which helps improve output quality and can also improve time to completion.

Not sure a multiagent setup fits your problem? See when to use multiagent systems (and when not to).



How it works

All agents share the same sandbox, filesystem, and vault credentials, but each agent runs in its own session thread, a context-isolated event stream with its own conversation history. The coordinator reports activity in the primary thread (which is the same as the session-level event stream); additional threads are spawned at runtime when the coordinator delegates work.

Threads are persistent: the coordinator can send a follow-up to an agent it called earlier, and that agent retains everything from its previous turns.

Each agent uses its own configuration: model, system prompt, tools, MCP servers, and skills. Session-level agent configuration overrides are the exception; they apply to the coordinator and its self copies. Tools, MCP servers, and context are not shared.



What to delegate

Multiagent coordination is best suited for complex tasks that either require work across a variety of surfaces, or where multiple well-scoped tasks contribute to an overall goal.

Patterns that work well:

• Parallelization: Fan out independent subtasks simultaneously (searching multiple sources, analyzing separate files) and have the coordinator synthesize the results.
• Specialization: Route to agents with domain-focused system prompts and tools, such as a security agent or a documentation agent, rather than loading a single agent with every capability.
• Escalation: Consult a more capable agent or model for a subset of complex subtasks.



Configure the coordinator

When defining your agent, set multiagent to declare the roster of agents the coordinator can delegate to:

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-5
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID
    - type: agent
      id: $TEST_WRITER_AGENT_ID
YAML

multiagent.agents can accept any of the following:

• {"type": "agent", "id": agent.id} references a previously created agent by ID. If no version is specified, the reference is pinned to the latest version of that agent at the time the coordinator is created.
• {"type": "agent", "id": agent.id, "version": agent.version} pins a specific agent version.
• {"type": "self"} allows the coordinator to spawn copies of itself. If the session was created with agent configuration overrides, those overrides also apply to these copies; roster entries referenced by ID are unaffected.
• {"type": "advisor", "model": "<model id>"} gives the session's primary thread an advisor it can consult mid-turn. At most one advisor entry per roster. See Give the session an advisor.

The coordinator's configuration, including its multiagent.agents roster, is snapshotted when the coordinator is created or updated. Referenced agents stay pinned to the versions resolved at that time and do not automatically pick up later updates to their definitions. To delegate to a newer version of a referenced agent, update the coordinator so its roster references that version.

The coordinator can only delegate to one level of agents; referencing an agent that has its own multiagent.agents roster fails the create or update request with a validation error. A maximum of 20 unique agents can be listed in multiagent.agents, but the coordinator can call multiple copies of each agent.

When agents pin an inference geography (model.inference_geo in the