Skip to main content
Delegate work to your agent

Multiagent orchestration

Configure a coordinator to delegate to child Agents or consult an Advisor, and observe execution 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. You can also configure an Advisor to give the main Agent an independent perspective at important steps. 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 list 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 list. It can have its own model, system prompt, tools, MCP servers, and skills
AdvisorA model the main thread can consult for advice. It cannot execute tools or take over the task. Each consultation uses a temporary Thread
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 listConfigured in multiagent.agents to specify which child Agents the coordinator can call. It can also include an Advisor
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 exposes main-thread and cross-thread collaboration events, not the union of all child events. Thread endpoints expose one thread's events
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 list 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 list, use the API or edit the JSON configuration directly and add {"type":"self"}.

Configure with the API

To delegate to ordinary child Agents, set multiagent and include agent_toolset_20260401 in tools. An Advisor-only list does not require this toolset: 
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", "version": "latest"},
        {"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
Advisor object{"type":"advisor","model":"ultimate"}Configures a model the main thread can consult. At most one per list; see Configure an Advisor
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

The example shows three choices:
  • "latest": new Sessions adopt the child's latest version.
  • Integer: use a tested version for rollback and reproducibility.
  • self: create a child thread with the current Session's coordinator configuration.
For example, a parent Agent references a child Agent with "version": "latest" in multiagent.agents. After the child is updated from v2 to v3, new Sessions created with that parent use child Agent v3. Sessions created before the update, including their subsequent child threads, continue to use child Agent v2. Omitting version in the API pins the child Agent’s latest version when saving the coordinator. New Sessions keep using that version even after the child is updated. See child Agent version rules.

Configure an Advisor

An Advisor gives the main Agent advice on tasks such as design reviews and complex problem analysis. The main Agent decides when to consult it and whether to use its advice. You can specify consultation criteria in the system prompt. In the console, create or edit an Agent, select Add Advisor in Multiagent, and choose a model. You can also configure it through the API: 
curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend-engineer",
    "model": "auto",
    "system": "Analyze backend designs. Consult the Advisor before data migrations or irreversible changes, then incorporate its advice into your response.",
    "multiagent": {
      "type": "coordinator",
      "agents": [{"type": "advisor", "model": "ultimate"}]
    }
  }'
Each Agent can have one Advisor alongside ordinary child Agents, without adding it to enabled_tools. Choose a model from List Models; see Agent schemas for configuration fields.

Consultation lifecycle

The Advisor uses the main Agent's current conversation context to provide advice without executing tools. The main Agent continues after receiving the result. It can consult the same Advisor more than once; the console shows a separate record for each consultation.

Events and failures

If a consultation fails, the main Agent continues with the task. Error details are available in the Advisor's event history. See Advisor events to retrieve results and status through the API.

Interrupt or remove an Advisor

You can interrupt a consultation or update the Agent to remove its Advisor; configuration changes apply only to new Sessions.

Cost and context

The Advisor uses the current conversation context, and each consultation adds model cost and waiting time.

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 list 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 it requests interruption of the work currently in progress across the Session. Ordinary child Threads are not archived by interruption. Advisor Threads are archived after completion, failure, or interruption, but their history remains available. 
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 sizeUp to 20 distinct ordinary Agent entries plus one Advisor. The list cannot be empty
Session ThreadsUp to 25 unarchived ordinary Threads per Session, including the coordinator. Advisor Threads do not count toward this limit
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 for a list with ordinary Agent or self entries, but not for an Advisor-only list

Troubleshooting

The coordinator does not delegate

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

Why does a new Session still use an older child Agent version?

If a child reference in multiagent.agents specifies a numeric version or omits version (the default), the coordinator saves a fixed version. Updating the child Agent does not change that reference, so new Sessions still use the older version. Set the child Agent’s version in multiagent.agents to "latest", save, and create a new Session.

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