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

# 托管 Agent

> 通过 coordinator Agent 将子任务并行或串行委派给 child Agent。

Managed Agents 允许一个 Agent 以协调者（coordinator）身份管理和委派任务给其他 Agent，实现多 Agent 协作。协调者 Agent 可以创建子 Agent 线程、发送消息、等待结果，从而将复杂任务分解为多个独立的子任务并行或串行执行。

## 核心概念

Managed Agents 建立在 Session Thread 模型之上。一个 Session 内可以同时存在多个 Thread，每个 Thread 绑定一个独立的 Agent 快照，拥有独立的对话历史和执行上下文。

| 概念             | 说明                                                                                              |
| -------------- | ----------------------------------------------------------------------------------------------- |
| Coordinator    | 协调者线程，每个 Session 有且仅有一个。使用 Session 创建时指定的 Agent，负责编排和分派任务                                       |
| Child thread   | 子线程，由 coordinator 通过工具调用创建。绑定 `multiagent.agents` 花名册中的某个 Agent，独立执行任务并通过 `send_to_parent` 回报结果 |
| Session Thread | 线程实体，ID 前缀为 `sthr_`。包含 `role`（coordinator 或 child）、独立的 Agent 快照和状态                              |
| Mailbox        | 线程间消息队列，CAS 内部管理。消息入队后由调度器按目标线程状态自动分发                                                           |

## 配置 Managed Agent

要启用 managed agents 能力，需要在 Agent 配置中设置 `multiagent` 字段：

```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": "你是一个任务协调者，负责将任务分配给合适的子 Agent。",
    "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` 字段说明

| 字段       | 类型     | 必选 | 说明                        |
| -------- | ------ | -- | ------------------------- |
| `type`   | string | 是  | 必须为 `"coordinator"`       |
| `agents` | array  | 是  | 可委派的 Agent 花名册，1-20 个唯一条目 |

`agents` 数组元素支持三种格式：

| 格式                 | 示例                                                                       | 说明                                         |
| ------------------ | ------------------------------------------------------------------------ | ------------------------------------------ |
| 对象 `type: "agent"` | `{"type": "agent", "id": "agent_xxx", "version": 2, "name": "Reviewer"}` | 引用其他 Agent。`id` 必填，`version` 和 `name` 可选   |
| 对象 `type: "self"`  | `{"type": "self"}`                                                       | 引用 coordinator 自身作为子 Agent                 |
| 字符串简写              | `"agent_xxx"`                                                            | 等价于 `{"type": "agent", "id": "agent_xxx"}` |

<Tip>
  配置 `multiagent` 时，`tools` 中必须包含 `agent_toolset_20260401` 类型的工具配置项。系统会在运行时自动注入 `create_agent`、`send_to_agent`、`list_agents`、`Agent` 四个控制工具。
</Tip>

## Coordinator 控制工具

当 Session 的 Agent 配置了 `multiagent` 且当前线程角色为 coordinator 时，以下工具被自动注入：

### `create_agent`

创建一个新的子 Agent 线程并发送初始任务。调用后立即返回线程 ID，不等待子 Agent 完成。

| 参数           | 类型     | 必选 | 说明                                                     |
| ------------ | ------ | -- | ------------------------------------------------------ |
| `agent_id`   | string | 是  | 花名册中的 Agent ID 或 `"self"`。取值范围由 `multiagent.agents` 决定 |
| `agent_name` | string | 否  | 为子线程指定的显示名称                                            |
| `task`       | string | 是  | 发送给子 Agent 的初始任务描述                                     |

返回示例：`"Created agent thread: sthr_019f..."`

### `Agent`

委派一个聚焦任务给子 Agent 并同步等待其返回结果。这是一个阻塞式工具——coordinator 的 turn 会暂停直到子 Agent 完成（调用 `send_to_parent`）或被中断。

| 参数         | 类型     | 必选 | 说明                        |
| ---------- | ------ | -- | ------------------------- |
| `agent_id` | string | 是  | 花名册中的 Agent ID 或 `"self"` |
| `prompt`   | string | 是  | 委派给子 Agent 的任务提示          |

### `send_to_agent`

向已存在的子线程发送后续消息。

| 参数          | 类型     | 必选 | 说明                   |
| ----------- | ------ | -- | -------------------- |
| `thread_id` | string | 是  | 目标子线程 ID（`sthr_` 前缀） |
| `message`   | string | 是  | 发送的消息内容              |

返回示例：`"Message queued for agent thread: sthr_019f..."`

### `list_agents`

列出当前 Session 中所有子线程的状态、待处理消息数以及可用的 Agent 花名册。无需参数。

## Child 控制工具

当线程角色为 child 时，系统自动注入一个工具：

### `send_to_parent`

向 coordinator 发送结果、状态更新或提问。调用后子线程会变为 `idle` 状态。

| 参数        | 类型     | 必选 | 说明                  |
| --------- | ------ | -- | ------------------- |
| `message` | string | 是  | 发送给 coordinator 的消息 |

## Session Thread 生命周期

<Steps>
  <Step title="创建 Session">
    客户端创建 Session 并引用配置了 `multiagent` 的 Agent。
  </Step>

  <Step title="启动 Turn">
    客户端发送 `user.message` 事件，CAS 自动创建 coordinator 线程（`role: coordinator`）。
  </Step>

  <Step title="Coordinator 委派任务">
    模型调用 `create_agent` 或 `Agent` 工具，CAS 创建 child 线程，将任务消息入队到 mailbox。
  </Step>

  <Step title="Child 执行">
    CAS 调度器将 mailbox 消息分发给 child 线程，CAW 加载 child 的 Agent 快照独立执行。
  </Step>

  <Step title="Child 回报结果">
    Child 调用 `send_to_parent`，消息通过 mailbox 发回 coordinator。Child 线程变为 `idle`。
  </Step>

  <Step title="Coordinator 继续">
    Coordinator 收到 child 的回报，综合结果继续处理或发起新的委派。
  </Step>

  <Step title="Session 空闲">
    当所有运行中的线程都已停止，Session 整体回到 `idle` 状态。
  </Step>
</Steps>

## 线程事件

在 managed agents 场景下，事件流中会出现以下新事件类型：

| 事件类型                               | 说明                                 |
| ---------------------------------- | ---------------------------------- |
| `session.thread_created`           | 创建了新的子线程                           |
| `session.thread_status_running`    | 线程开始执行                             |
| `session.thread_status_idle`       | 线程执行完成或暂停                          |
| `session.thread_status_terminated` | 线程被归档/终止                           |
| `agent.thread_message_sent`        | 线程间发送消息（coordinator → child 或后续消息） |
| `agent.thread_message_received`    | 线程间接收消息（child → coordinator）       |

所有事件都包含 `session_thread_id` 字段标识所属线程。可以通过 [列出线程事件](/zh/cloud-agents/api/sessions/list-thread-events) 和 [线程事件流](/zh/cloud-agents/api/sessions/stream-thread-events) 接口按线程维度筛选事件。

## 限制

| 项目                       | 限制                  |
| ------------------------ | ------------------- |
| 每个 Agent 最多配置的子 Agent 数量 | 20 个唯一条目            |
| 每个 Session 最多并发线程数       | 25 个（含 coordinator） |
| Session 空闲条件             | 所有线程必须停止运行          |

## 下一步

<CardGroup cols={2}>
  <Card title="配置 multiagent" icon="user-gear" href="/zh/cloud-agents/api/agents/create">
    在创建 Agent 时设置 `multiagent` 字段。
  </Card>

  <Card title="Agent 数据结构" icon="code" href="/zh/cloud-agents/api/agents/schemas#multiagent">
    `multiagent` 与 agent entry 字段参考。
  </Card>

  <Card title="列出 Session Threads" icon="list" href="/zh/cloud-agents/api/sessions/list-threads">
    查看 Session 中的所有线程。
  </Card>

  <Card title="Session Thread 对象" icon="layer-group" href="/zh/cloud-agents/api/sessions/schemas#session-thread-对象">
    Session Thread 对象字段与生命周期。
  </Card>
</CardGroup>