> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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"}`                         |

<Tip>
  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.
</Tip>

## 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

<Steps>
  <Step title="Create session">
    Client creates a Session referencing an Agent with `multiagent` configured.
  </Step>

  <Step title="Start turn">
    Client sends a `user.message` event. CAS automatically creates a coordinator thread (`role: coordinator`).
  </Step>

  <Step title="Coordinator delegates">
    The model calls `create_agent` or `Agent` tool. CAS creates a child thread and enqueues the task message to the mailbox.
  </Step>

  <Step title="Child executes">
    The CAS scheduler dispatches the mailbox message to the child thread. CAW loads the child's Agent snapshot and executes independently.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Coordinator continues">
    The coordinator receives the child's report, synthesizes results, and continues processing or initiates new delegations.
  </Step>

  <Step title="Session idle">
    When all running threads have stopped, the Session transitions to `idle` status.
  </Step>
</Steps>

## 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](/cloud-agents/api/sessions/list-thread-events) and [Thread Event Stream](/cloud-agents/api/sessions/stream-thread-events) 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

<CardGroup cols={2}>
  <Card title="Configure multiagent" icon="user-gear" href="/cloud-agents/api/agents/create">
    Set the `multiagent` field on Agent creation.
  </Card>

  <Card title="Agent schemas" icon="code" href="/cloud-agents/api/agents/schemas#multiagent">
    `multiagent` and agent entry field reference.
  </Card>

  <Card title="List session threads" icon="list" href="/cloud-agents/api/sessions/list-threads">
    View all threads in a Session.
  </Card>

  <Card title="Session Thread object" icon="layer-group" href="/cloud-agents/api/sessions/schemas#session-thread-object">
    Thread object fields and lifecycle.
  </Card>
</CardGroup>