Skip to main content
Delegate work to your agent

Multiagent orchestration

Configure a coordinator to delegate work to specialized Agents and observe collaboration through Session Threads.

Multiagent orchestration lets one Agent act as a coordinator that delegates work to other Agents. Each child Agent runs in an independent Session Thread, and the coordinator combines their results into the final response. Use it for complex tasks that can be divided by responsibility, run in parallel, or executed in stages. For one-step work, strictly sequential tasks, or tasks where multiple workers would frequently edit the same files, use a single Agent to keep the workflow simpler.

How it works

Multiagent orchestration is built on the Session Thread model. The Agent selected when you create a Session becomes the coordinator. Based on its system prompt, it selects child Agents from the multiagent.agents roster and delegates tasks to them.
ConceptDescription
CoordinatorThe single coordinating thread in each Session. It breaks down work, selects child Agents, follows up on results, and produces the final response
Child AgentAn Agent in the multiagent.agents roster. It can have its own model, system prompt, tools, MCP servers, and skills
Session ThreadThe execution thread for a coordinator or child Agent, with an ID prefixed by sthr_. Each thread has its own conversation history, Agent snapshot, and status
Agent rosterThe set of Agents available for delegation. Their versions are resolved and saved when the coordinator is created or updated
Resources, contexts, and configurations within a multiagent Session have the following scopes:
ScopeBehavior
Environment and filesystemAll threads in a Session share the same Environment, Sandbox, and filesystem
VaultsBound when the Session is created and available to authorized Agents in that Session
Conversation historyIsolated per Thread. A child Agent does not automatically receive the full context of other threads
Agent configurationEach Thread uses its own Agent version snapshot, including its model, system prompt, tools, MCP servers, and skills
Event streamsThe Session event stream aggregates all threads; Thread endpoints expose the complete event stream for one thread
Parallel child Agents share a filesystem. Define clear file or directory ownership in the coordinator system prompt so that child Agents do not edit the same file concurrently.

What to delegate

Design the roster and coordinator system prompt around task dependencies and responsibility boundaries:
  • Assign independent research, module implementation, or data collection tasks to different Agents so they can run in parallel.
  • Split implementation, testing, and review by responsibility. For example, an implementation Agent can write code while a review Agent reads the code and returns an issue list. Route work that needs a stronger model or specialized tools to the appropriate Agent.
  • Run dependent tasks in stages, such as implementation followed by review. The coordinator uses the review result to decide whether another iteration is needed.
The system prompt should also define each Agent's output format and identify tasks that the coordinator must handle itself.

Configure the coordinator

Configure in the console

  1. In the Cloud Agents console, open Agents and create the Agents that will collaborate.
  2. Create or edit the coordinator. In the Multiagent section, select the Agents available for delegation. The console saves the current version of each selected Agent.
  3. In the coordinator system prompt, define task decomposition, delegation criteria, deliverable formats, and conflict handling.
  4. Save the coordinator and use it to create a Session.
The console selector references other Agents. To add the coordinator itself to the roster, use the API or edit the JSON configuration directly and add {"type":"self"}.

Configure with the API

Set multiagent when you create an Agent, and include agent_toolset_20260401 in tools: 
curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "engineering-coordinator",
    "model": "ultimate",
    "system": "Analyze each task and delegate it to the best Agent. Run independent work in parallel, then check all conclusions and resolve conflicts before responding.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]
      }
    ],
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "agent", "id": "agent_00nc01ht8gcn4w8sb7zv", "version": 3},
        {"type": "agent", "id": "agent_00nc01ht8gcn4w8sb7zw"},
        {"type": "self"}
      ]
    }
  }'
multiagent.agents accepts the following formats:
FormatExampleDescription
Agent object{"type":"agent","id":"agent_00nc01ht8gcn4w8sb7zv","version":2}References another Agent. id is required and version is optional
Self object{"type":"self"}Uses the coordinator's own Agent configuration for a child thread
String shorthand"agent_00nc01ht8gcn4w8sb7zv"Equivalent to {"type":"agent","id":"agent_00nc01ht8gcn4w8sb7zv"}
The platform resolves each Agent entry's display name. See Agent schemas for name sources, name field handling, uniqueness requirements, and other validation rules.

Agent versions and Session snapshots

Versions determine which Agent configuration runs when work is delegated:
  • When you specify version, the coordinator pins that version.
  • When you omit version, the platform resolves the referenced Agent's latest Active version when the coordinator is created or updated, then saves the resolved version in the coordinator version.
  • Updating a child Agent later does not automatically change a saved coordinator. Update and save the coordinator to adopt the new version.
  • After you create a Session, the coordinator and roster are frozen as a Session snapshot. Later Agent updates do not affect running Sessions.
For production, verify child Agent versions before updating the coordinator.

Create and run a Session

Create a Session with the coordinator that has multiagent configured: 
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "id": "agent_00nc01ht8gcn4w8sb7zx",
      "version": 4
    },
    "environment_id": "env_00l99wwqo8ydc81s4djg",
    "vault_ids": ["vault_00j9owzm7vfnkgckud6o"],
    "title": "Analyze and review the login module"
  }'
Send a task message to the Session. The coordinator uses its system prompt to decide whether and how to delegate: 
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [
          {"type": "text", "text": "Analyze the login module implementation and security risks, then recommend fixes."}
        ]
      }
    ]
  }'
Configuring a roster does not force delegation. The coordinator still decides based on its judgment and system prompt. State the delegation criteria explicitly instead of only listing child Agents. See Create Session and Send Session Events.

Connect MCP servers and Vaults

MCP servers, tools, and skills are Agent-scoped. Vaults are bound when you create a Session:
  • Only an Agent configured with the relevant MCP server or toolset can call that capability.
  • All threads share the Vaults bound to the Session, but each Agent remains subject to its own tool configuration and permission policy.
  • Credential URLs in a Vault must match the MCP server URLs in the Agent configuration.
  • A coordinator usually needs only orchestration and aggregation capabilities. Grant high-privilege credentials only to Agents that need them.
See Tools, Vaults, and Permission policies.

Observe threads and events

Use the Session event stream to observe the overall collaboration: 
curl -N "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"
The following thread events appear during multiagent orchestration:
Event typeDescription
session.thread_createdA child thread was created
session.thread_status_runningA thread started executing
session.thread_status_rescheduledA thread task was retried and rescheduled
session.thread_status_idleA thread completed its current work or is waiting for follow-up
session.thread_status_terminatedA thread was archived or terminated
agent.thread_message_sentThe coordinator sent a task or follow-up to a child thread
agent.thread_message_receivedThe coordinator received a message from a child thread
Related events include session_thread_id so you can identify the originating thread. List the threads in a Session: 
curl "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/threads" \
  -H "Authorization: Bearer $QODER_PAT"
To inspect the complete execution of one child Agent, connect to its Thread event stream: 
curl -N "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/threads/sthr_xxx/stream" \
  -H "Authorization: Bearer $QODER_PAT"
Use the Session event stream for cross-thread progress and the coordinator's final result. Use a Thread event stream to debug an individual child Agent. See List Session Threads, List Thread Events, and Stream Thread Events.

Interrupt one thread

Send a user.interrupt event to the Session with session_thread_id to interrupt only the target Thread. Omitting session_thread_id requests interruption of the work currently in progress across the Session. Interrupting a Thread does not archive it. 
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.interrupt",
        "session_thread_id": "sthr_xxx"
      }
    ]
  }'

Tool permissions and interactions

Each Thread uses the tool configuration and permission policy in its own Agent snapshot. A tool call that requires confirmation emits agent.tool_use; reply with user.tool_confirmation and provide tool_use_id and result. A Custom Tool call emits agent.custom_tool_use; after your client executes it, reply with user.custom_tool_result and provide custom_tool_use_id. When actions are pending, the event stream emits session.status_idle with stop_reason.type set to requires_action. stop_reason.event_ids lists the event IDs that need responses. The session_thread_id on the related Agent events identifies the requesting Thread. The following example allows a tool call that requires confirmation: 
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
        "result": "allow"
      }
    ]
  }'
Do not include session_thread_id in a tool response. The platform uses tool_use_id or custom_tool_use_id to route the response to the originating Thread. If stop_reason.event_ids contains multiple IDs, respond to each one; the current turn remains paused while any action is unresolved. A requires_action idle state means the Session is waiting for input, not that it has completed. Before archiving a child thread, make sure it has no pending tool interaction. See Send Session Events.

Limits

ItemBehavior or limit
Roster sizeEach coordinator can configure 1-20 distinct Agent entries
Session ThreadsUp to 25 unarchived Threads per Session, including the coordinator. Archive completed child Threads before creating more
Delegation depthOnly the coordinator can create child threads. Child Agents cannot create another layer of child threads
Session idle stateA Session becomes idle only after all Threads stop running
Agent referencesMissing, archived, or inaccessible Agents and versions cause configuration to fail
Toolsetagent_toolset_20260401 is required when multiagent is configured

Troubleshooting

The coordinator does not delegate

  1. Confirm that the current coordinator version has a non-empty multiagent.agents roster. See Agent schemas for configuration rules.
  2. Confirm that the system prompt states the delegation criteria and each Agent's responsibility.

A Session does not use an updated Agent configuration

A Session freezes the coordinator and child Agent version snapshots when it is created. After updating a child Agent, update and save the coordinator, then create a new Session. Existing Sessions do not adopt the new configuration.

Creating or updating the coordinator returns 400

Common causes include an invalid Agent or version reference, or a multiagent configuration that fails validation. Use the API error message to locate the corresponding field. See Agent schemas for the complete rules.
First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference