Managed Agents

Use a coordinator Agent to delegate subtasks to child Agents in parallel or sequence.

Managed Agents lets an Agent act as a coordinator to manage and delegate tasks to other Agents, enabling multi-agent collaboration. The coordinator Agent can create child agent threads, send messages, and await results, breaking complex tasks into multiple independent subtasks for parallel or sequential execution.

Core concepts

Managed Agents is built on the Session Thread model. A single Session can contain multiple threads, each bound to an independent Agent snapshot with its own conversation history and execution context.

Concept	Description
Coordinator	The coordinator thread; each Session has exactly one. Uses the Agent specified at Session creation time, responsible for orchestration and task delegation
Child thread	A child thread created by the coordinator via tool calls. Bound to an Agent from the multiagent.agents roster, executes tasks independently and reports results via send_to_parent
Session Thread	The thread entity, with ID prefix sthr_. Contains role (coordinator or child), an independent Agent snapshot, and status
Mailbox	Inter-thread message queue managed internally by CAS. Messages are enqueued and automatically dispatched by the scheduler based on target thread status

Configure managed agents

To enable managed agents, set the multiagent field in the Agent configuration:

curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "task-coordinator",
    "model": "ultimate",
    "system": "You are a task coordinator responsible for delegating tasks to sub-agents.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "agent", "id": "agent_019f000000000000000000000000001a", "name": "Research Agent"},
        {"type": "agent", "id": "agent_019f000000000000000000000000002b"},
        {"type": "self"}
      ]
    }
  }'

multiagent field reference

Field	Type	Required	Description
type	string	Yes	Must be "coordinator"
agents	array	Yes	Agent roster for delegation, 1-20 unique entries

agents array elements support three formats:

Format	Example	Description
Object type: "agent"	{"type": "agent", "id": "agent_xxx", "version": 2, "name": "Reviewer"}	Reference another Agent. id is required; version and name are optional
Object type: "self"	{"type": "self"}	Reference the coordinator itself as a child Agent
String shorthand	"agent_xxx"	Equivalent to {"type": "agent", "id": "agent_xxx"}

When configuring multiagent, tools must include an agent_toolset_20260401 entry. The system automatically injects create_agent, send_to_agent, list_agents, and Agent control tools at runtime.

Coordinator control tools

When the Session’s Agent has multiagent configured and the current thread role is coordinator, the following tools are automatically injected:

create_agent

Create a new child Agent thread and send an initial task. Returns immediately with the thread ID without waiting for the child Agent to complete.

Parameter	Type	Required	Description
agent_id	string	Yes	An Agent ID from the roster, or "self". Values are determined by multiagent.agents
agent_name	string	No	Display name for the child thread
task	string	Yes	Initial task description sent to the child Agent

Return example: "Created agent thread: sthr_019f..."

Agent

Delegate a focused task to a child Agent and synchronously wait for its result. This is a blocking tool — the coordinator’s turn pauses until the child Agent completes (calls send_to_parent) or is interrupted.

Parameter	Type	Required	Description
agent_id	string	Yes	An Agent ID from the roster, or "self"
prompt	string	Yes	Task prompt delegated to the child Agent

send_to_agent

Send a follow-up message to an existing child thread.

Parameter	Type	Required	Description
thread_id	string	Yes	Target child thread ID (sthr_ prefix)
message	string	Yes	Message content to send

Return example: "Message queued for agent thread: sthr_019f..."

list_agents

List all child threads in the current Session along with their statuses, pending message counts, and the available Agent roster. No parameters required.

Child control tools

When the thread role is child, the system automatically injects one tool:

send_to_parent

Send a result, status update, or question to the coordinator. The child thread transitions to idle status after this call.

Parameter	Type	Required	Description
message	string	Yes	Message to send to the coordinator

Session thread lifecycle

1. Create session

   Client creates a Session referencing an Agent with multiagent configured.

2. Start turn

   Client sends a user.message event. CAS automatically creates a coordinator thread (role: coordinator).

3. Coordinator delegates

   The model calls create_agent or Agent tool. CAS creates a child thread and enqueues the task message to the mailbox.

4. Child executes

   The CAS scheduler dispatches the mailbox message to the child thread. CAW loads the child’s Agent snapshot and executes independently.

5. Child reports result

   Child calls send_to_parent. The message is routed back to the coordinator via the mailbox. The child thread transitions to idle.

6. Coordinator continues

   The coordinator receives the child’s report, synthesizes results, and continues processing or initiates new delegations.

7. Session idle

   When all running threads have stopped, the Session transitions to idle status.

Thread events

In managed agents scenarios, the following new event types appear in the event stream:

Event type	Description
session.thread_created	A new child thread was created
session.thread_status_running	A thread started executing
session.thread_status_idle	A thread completed or paused
session.thread_status_terminated	A thread was archived/terminated
agent.thread_message_sent	Inter-thread message sent (coordinator → child or follow-up)
agent.thread_message_received	Inter-thread message received (child → coordinator)

All events include a session_thread_id field identifying the thread. You can use the List Thread Events and Thread Event Stream endpoints to filter events by thread.

Limits

Item	Limit
Max child agents per Agent configuration	20 unique entries
Max concurrent threads per Session	25 (including coordinator)
Session idle condition	All threads must stop running

Next steps

Configure multiagent

Set the multiagent field on Agent creation.

Agent schemas

multiagent and agent entry field reference.

List session threads

View all threads in a Session.

Session Thread object

Thread object fields and lifecycle.