AgentDefinition 有两个必填字段和几个可选但关键的字段。靠谱的做法：显式配置所有东西——model、tools、maxTurns、mcpServers。依赖继承的默认值会产出太贵、权限太大或不受约束的 agent。
必填字段
description — 告诉协调者什么时候委派给这个 agent。这是选择机制。协调者读 description 来决定路由，不读 prompt。
- 好的：“处理付款争议、发票问题和订阅变更。用于任何关于费用、付款或账单历史的查询。不用于退款处理。”
- 差的：“处理客户咨询” / “一个有帮助的助手”——模糊、雷同的 description 导致交叉路由
某系统的 billing 和 shipping agent 都描述为通用的”客户帮助”。协调者把账单问题路由到物流，反之亦然——因为 description 没有提供区分度。修复：写具体的 description，包含用例、输入类型和”不用于”边界。
prompt — 告诉 agent 怎么行为。系统指令、行为规则、输出格式。协调者不读 prompt 来做委派——prompt 是给子代理执行用的，不是给协调者选择用的。
可选但关键：tools
tools 字段是可用工具的白名单。省略时，子代理从父级继承所有工具——包括它可能不需要的 Bash、Write 和 Edit。
某团队的数据提取 agent（没指定 tools 字段）开始执行 Bash 命令来安装 Python 包。根因：它继承了协调者的完整工具集包括 Bash。修复：tools=["Read", "Glob"]——只给提取需要的。
白名单 > 黑名单
TypeScript SDK 提供了 disallowedTools（黑名单）。但白名单更安全：未来 SDK 新增工具时，黑名单不会自动屏蔽它们——它们默认可用。白名单只允许显式列出的工具，不管以后加了什么。
model 字段：匹配能力到任务
子代理默认继承协调者的模型。model 字段按 agent 覆盖。
某 CI 系统对所有代码审查都用 Opus。80% 是简单的 lint 检查，Haiku 完全胜任；20% 是复杂的安全/架构审查，需要 Opus。修复：拆成两个 agent——lint-checker 用 model="haiku"，deep-reviewer 用 model="opus"。通过 description 路由。
这不只是成本优化——也是速度。Haiku 响应比 Opus 快，简单审查完成更快。
maxTurns：按 agent 限制执行
maxTurns 限制推理-行动循环。按预期复杂度逐 agent 设置：
- 搜索 agent：3-5 轮
- 安全审计：20 轮
- 简单查询：2 轮
不要靠 prompt 限制轮次（“在 10 步内完成”）——那是概率性的。maxTurns 是确定性的安全网，和 stop_reason 互补。
mcpServers：按 agent 分配 MCP server
AgentDefinition 的 mcpServers 字段给每个子代理分配特定的 MCP server。一个有 5 个 agent 和 4 个 MCP server 的研究系统：
- 搜索 agent →
[web-search] - 学术 agent →
[academic-db] - 金融 agent →
[financial-data] - 事实核查 agent →
[news-api] - 综合 agent →
[]（不用外部源，基于其他 agent 的发现工作）
把所有 MCP server 共享给所有 agent 违反最小权限原则。金融 agent 访问 academic-db 或事实核查器修改金融数据都是不必要的风险。按 agent 分配 mcpServers 提供确定性的权限范围。
完整配置模式
一个需要三重约束的安全审计 agent：
- 深度推理 →
model="opus" - 只读 →
tools=["Read", "Grep", "Glob"] - 有界执行 →
maxTurns=20
三个都必须显式设置。省略 model 可能继承到更便宜的模型。省略 tools 可能继承到 Bash。省略 maxTurns 在大代码库上可能无界执行。模式是：显式配置一切，什么都不继承。
一句话总结： 设置 description（具体，带”不用于”边界）、prompt（角色指令）、tools（白名单，不继承）、model（匹配任务复杂度）、maxTurns（逐 agent 限制）和 mcpServers（范围化访问）——显式配置一切，默认不继承。