配置一个多 agent 系统意味着搞定四件事：协调者的委派能力（allowedTools 里有 Task）、每个子代理的能力（tools 字段）、每个子代理的身份（description + prompt）、以及成本/安全旋钮（model、maxTurns）。漏掉任何一个都会导致静默失败、错误路由或失控的成本。
协调者必须在 allowedTools 里有 Task
Task 工具是派生子代理的机制。如果 "Task" 不在协调者的 allowedTools 里，它尝试委派时会收到 "Tool 'Task' is not available" 错误——不管 prompt 写得多好。再厉害的 prompt 工程也救不了一个缺失的工具。
典型协调者：allowedTools=["Task", "Read", "Grep"]。Task 用于委派，Read 和 Grep 用于自己的探索工作。
子代理工具：显式白名单，不是继承
每个子代理在 AgentDefinition 中的 tools 字段精确定义了它能用哪些工具。省略这个字段会导致子代理继承所有可用工具——包括它可能不需要的 Bash、Write 和 Edit。这是多 agent 系统中最常见的安全反模式。
某团队的代码审查 agent（没指定 tools 字段）不小心执行了 Bash 命令并修改了源文件。修复：tools=["Read", "Grep", "Glob"]——只读。这个 agent 在物理上无法调用列表外的工具。
逐 agent 的安全边界
不同 agent 需要匹配角色的不同工具集：
- 代码审查：
[Read, Grep, Glob]— 只读，不能修改任何东西 - 测试运行：
[Read, Grep, Bash]— 能跑测试但不能写代码 - 部署 agent：
[Read, Bash, Write]— 能跑部署脚本和写配置，加上 PreToolUse hook 来验证部署目标和阻止源文件修改
这是纵深防御：即使 agent 的 prompt 写得不好，它在结构上也无法越过工具边界。
Tools + hooks 实现细粒度控制
有时候 tools 字段本身不够。部署 agent 需要 Bash 来跑部署脚本，但不能修改 .js、.ts 或 .py 源文件。tools 字段没法在 Bash 内部执行文件类型限制。
方案：在 tools 里给 agent Bash（能力），加一个 PreToolUse hook 在 Bash 上检查命令是否修改源文件，有就拒绝（执行）。这在工具级访问上叠加 hook 级执行，实现单独任一机制都达不到的细粒度安全。
description vs prompt：不同的受众
description — 告诉协调者什么时候用这个 agent。协调者读 description 来选择哪个子代理适合当前任务。“处理付款争议、发票问题和订阅变更。用于任何关于费用、付款或账单历史的查询。不用于退款处理——用 Refund agent。”
prompt — 告诉 agent 怎么行为。系统指令、行为规则、输出格式。协调者不会读子代理的 prompt 来做选择——它用的是 description。
description 质量驱动选择准确度
一个 4 agent 客服系统用模糊 description 的生产数据：
- Billing（“Handles billing”）：72% 正确选择
- Shipping（“Handles shipping”）：68%
- Account（“Handles accounts”）：65%
- Refund（“Handles refunds”）：60%
修复：扩展每个 description，加入具体用例、输入类型和边界条件——包括带重定向的”不用于”声明。一个 description 写得好的 Haiku agent 比一个 description 模糊的 Opus agent 表现更好，因为选择准确度取决于 description，不是模型。
model 字段：逐 agent 成本优化
子代理默认继承协调者的模型。AgentDefinition 中的 model 字段可以按 agent 覆盖：
| Agent | 任务复杂度 | 模型 | 节省 |
|---|---|---|---|
| Search | 简单关键词查询 | Haiku | ~80% |
| Analysis | 深度论文分析 | Opus | （合理） |
| Synthesis | 中等难度合并 | Sonnet | ~50% |
一个全 Opus 子代理每月花 $3,000 的研究系统，通过匹配模型到任务复杂度可以显著降低成本。没有兼容性问题——每个子代理独立运行，协调者通过 Task 工具通信，不管子代理用什么模型。
maxTurns：逐 agent 轮次限制
maxTurns 限制子代理能执行多少个推理-行动循环。按任务复杂度逐 agent 设置：
- 搜索 agent：3 轮（简单查询，1-2 次工具调用）
- 分析 agent：15 轮（深度工作，多次文件读取）
- 简单查询：2 轮
统一限制（比如所有 agent 都设 5）可能过早终止复杂分析，同时对简单查询又过于宽松。maxTurns 和 stop_reason 互补：stop_reason 处理正常终止，maxTurns 提供对无限循环的安全网。
一句话总结： 协调者需要 allowedTools 里有 Task；子代理需要显式 tools（不继承）、具体 description（不模糊）、按 agent 选模型降成本、按 agent 设 maxTurns 保安全——需要细粒度执行时在 tools 上叠加 hooks。