Task 工具把工作委派给子代理。正确使用它意味着理解三个必填输入、协调者收到的响应格式、以及一个出人意料地常见的 bug——协调者无视子代理的结果。
三个必填输入参数
description — 一个 3-5 词的简短摘要，标识这个任务。“review auth security”、“search academic papers”、“run tests”。这是给日志和监控用的，不是给子代理的。几十个委派的日志里，简洁的描述让你一眼看出委派了什么。不要写一段话。不要复制 prompt。不要留空或写泛泛的”task”。
prompt — 详细的任务指令，包含子代理需要的所有上下文。这里放你筛选过的上下文（参见 K1.2.2）、具体要求和期望的输出格式。Prompt 是子代理的主要输入。
subagent_type — 匹配 agents 配置字典中某个 agent 的字符串键。如果你配了 agents={"code-reviewer": AgentDefinition(...)}，那 subagent_type="code-reviewer"。
三个都是必填的。省略任何一个会触发校验错误——SDK 不会从上下文推断缺失参数，也不会自动选择 agent。
动态 subagent_type 选择
subagent_type 是一个普通的字符串参数，协调者模型可以在运行时动态设置。一个拥有 ["academic-researcher", "web-researcher", "financial-analyst"] 的研究协调者可以检查每个查询，选择最合适的专家——学术查询路由到 academic-researcher，金融查询路由到 financial-analyst。
这不是在开发时硬编码的。模型读 agent description 然后为每个任务选最佳匹配，就像它通过 description 选择工具一样。专业 agent 在领域任务上优于通用 agent。
Task tool 响应格式
Task 工具返回四个字段：
{
"result": "Customer has a $50 credit from return #RET-456",
"usage": {"prompt_tokens": 1200, "completion_tokens": 450},
"total_cost_usd": 0.003,
"duration_ms": 8000
}result — 子代理的输出文本。这是协调者应该纳入自己推理和响应的内容。
usage — 这次委派的 token 计数。对 prompt 优化有用。
total_cost_usd — 这次委派的美元成本。对成本监控至关重要。
duration_ms — 执行时间。对性能监控和超时调优至关重要。
被忽略的结果 bug
协调者委派了一个账单调查。Task 工具返回 result: "Customer has a $50 credit"。协调者回复：“I was unable to find any billing credits.” 为什么？
协调者的 prompt 里没有关于如何处理 Task 工具响应的指令。没有把 result 字段纳入推理的引导，协调者默认用了自己的（不知情的）答案。修复：在协调者的 prompt 里加关于读取和使用 Task 工具结果的显式指令。
响应元数据的运营价值
非 result 字段不只是给账单报表用的：
-
total_cost_usd按委派、按 subagent_type 聚合 → 识别哪种 agent 类型花费最多。某系统发现 API 成本涨了 3 倍但请求量只涨了 1.5 倍——图片提取器每次 $0.05，比其他 agent 贵 25 倍。 -
duration_ms按委派 → 识别性能瓶颈。一个平均 25,000ms 的图片提取器消耗了 30 秒 SLA 预算的 84%。PDF 和文本提取器加起来只有 4,500ms。 -
usagetoken 计数 → 引导 prompt 优化。一个每次调用用 8,000 prompt token 的 agent 可能上下文注入过于冗长。
四个字段都要用：result 做决策，duration_ms 调超时，total_cost_usd 报预算告警，usage 优化 prompt。
一句话总结： Task 工具接收 description（3-5 词摘要）、prompt（详细指令）和 subagent_type（可动态选择的 agent 键）——返回 result、usage、cost 和 duration 元数据，协调者必须被显式提示来使用它们。