# 定义与管理子 Agent

划分专职职责，关联子任务消息，理解声明式委派与运行时控制的区别。

## 什么时候拆分 Agent

当一个任务包含可独立完成的职责时，可以定义子 Agent。例如主 Agent 整理审查结论，reviewer 只检查代码中的缺陷。分工应有清楚的输入、可用工具和输出要求；简单的一次问答不需要建立多个角色。

`agent.Definition` 描述子 Agent，执行循环仍在运行时。Bridge 不在 Go 宿主里自行调度模型循环。

## 注册一个审查成员

```go
options = options.WithAgentDefinition("reviewer", agent.Definition{
    Description: "检查代码中的可复现缺陷，并给出文件位置。",
    Prompt: "只审查，不修改文件。每项结论包含触发条件、文件位置和影响。没有证据时说明尚未确认。",
    Tools: []string{"Read", "Glob", "Grep"},
}).WithAllowedTools("Agent", "Read", "Glob", "Grep")
```

在任务中明确要求使用 reviewer，并给出检查范围。允许 Agent 工具不意味着你已经批准子 Agent 的所有业务动作；子成员工具和运行时权限仍需按实际策略配置。

Description 帮助主 Agent 判断何时委派，Prompt 约束该成员的职责，Tools 选择它需要的工具。Model 可指定成员模型，但必须是运行时可用的标识，不应在文档或业务代码里假设每个账号都拥有同一个模型。

## 收集委派结果

流式消息中的 `ParentToolUseID` 用来关联父工具调用。保留这个关联，界面才能把子成员的过程放回对应任务。不要把所有子 Agent 文本直接拼进主 Agent 的回答，也不要只根据成员名称归类并发任务。

后台任务还可能产生 TaskStarted、TaskProgress、TaskNotification 等消息。它们用于状态跟踪；当前用户回合的 result 与所有后台任务都已结束不是同一件事。宿主应分别记录回合状态和任务状态。

## 停止与后续消息

`session.Control().StopTask(ctx, taskID)` 停止指定后台任务。taskID 必须来自运行时返回的任务身份，不是显示名称。检查能力与调用错误后，再更新界面。

`SendTaskMessage` 可给后台子任务排队后续消息，当前属于 nxs 能力。发送成功表示消息被控制入口接受，不应直接展示成“子任务已完成修改”。完成情况仍从后续事件确认。

## 原生子任务控制扩展

`ControlSubagent` 是 nxs 的扩展入口，需要 `CapabilitySubagentControl`，对应 `subagent_control_v1`。它在活跃父会话的 MCP 调用身份内使用。普通宿主请求不能伪造一个身份，在任意时刻调用它来绕过父任务边界。

先用声明式 Definition 完成接入。只有产品确实需要管理子任务生命周期时，再按[公开运行时契约](https://github.com/nexus-research-lab/nexus-agent-sdk-bridge/blob/main/docs/runtime-contract.md#subagent-control)接入控制扩展。Claude Code 不提供这个 Nexus 扩展。

## 验证分工是否有效

用一个小型只读任务验证：主 Agent 是否实际委派、成员是否只读取约定范围、返回结果是否带证据、取消是否能结束相关任务。再检查权限拒绝或成员失败时，主 Agent 是否如实报告未完成部分。

工具数量和成员数量增加后，模型上下文与执行时间也会变化。成本记录见[用量与预算](/docs/sdk-usage)，消息归属见[消息流](/docs/sdk-streaming)。