Managed Agents

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

Create session

Client creates a Session referencing an Agent with multiagent configured.

Start turn

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

Coordinator delegates

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

Child executes

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

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.

Coordinator continues

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

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.

​Core concepts

​Configure managed agents

​multiagent field reference

​Coordinator control tools

​create_agent

​Agent

​send_to_agent

​list_agents

​Child control tools

​send_to_parent

​Session thread lifecycle

​Thread events

​Limits

​Next steps

Configure multiagent

Agent schemas

List session threads

Session Thread object

Core concepts

Configure managed agents

`multiagent` field reference

Coordinator control tools

`create_agent`

`Agent`

`send_to_agent`

`list_agents`

Child control tools

`send_to_parent`

Session thread lifecycle

Thread events

Limits

Next steps