深度剖析 / 工具与能力设计

工具与能力设计

设计智能体真正能用的工具——粒度、Schema、错误消息、恢复与反模式。

  1. 设计智能体能用好的工具
    工具就是智能体的全部 API:为一个只读描述、且会自信犯错的模型而设计,而非为一个读过源码的工程师。
  2. 工具粒度与组合
    粗工具隐藏决策、集中爆炸半径,细工具放大来回、撑大列表——而工具爆炸如今是约 24 个百分点的选择准确率实测损失。
  3. 模式、契约与默认值
    模式就是指令集:让非法状态无法表示、让安全相关字段必填,并让最少说明的路径成为最少伤害的路径。
  4. 把错误消息当作提示
    工具错误是一段即时提示词:点出原因、回显坏值、开出修正后的调用、说清可重试还是终态——否则就养出一个失控重试循环。
  5. 工具文档与可发现性
    Claude Code 默认把 MCP 工具定义延后加载,而那个必须匹配到你工具的检索步骤只会读前 4,096 个字符——尽管一个被延后的描述最多可以写到 16,384 个字符。所以这份描述其实是两份文档、两类读者:先放领域名词和与最近邻工具的边界,再放可照抄的调用范例,并把 alwaysLoad 当成真正要紧的那个决定。
  6. 工具设计反模式
    拖垮多数智能体的四个——厨房水槽工具、字符串化参数、静默失败、泄漏的抽象——每个一分钟可认出,每个都有追踪指纹和机械修法。
  7. 工具调用厂商对照矩阵(2026)
    OpenAI(Chat Completions 与 Responses API、parallel_tool_calls、带 Lark/regex 的自定义工具)vs Anthropic(编程式工具调用、Tool Search Tool、Tool Use Examples)vs Gemini(OpenAPI 子集、tool_choice: any、多模态函数响应)。
  8. 进阶工具编排
    Anthropic 的 Tool Search Tool(减少 85% 令牌);Programmatic Tool Calling(Claude 在沙箱中写 Python 调工具,只有最终结果进入上下文);Tool Use Examples。
  9. 结构化输出 vs 工具调用
    两种约束模型的方式——底层是同一份受限解码,人体工程学不同。Anthropic 的原生结构化输出于 2026 年 GA;各自何时用。
  10. 各厂商的 JSON Schema 子集
    各厂商实际能强制到什么——Anthropic 不支持 minLength/maxLength/minimum/maximum;Gemini 只吃 OpenAPI 子集;OpenAI 的 strict 模式要求 additionalProperties:false 且全为 required。
  11. 流式工具调用实操
    逐厂商的增量拼接、OpenAI GPT-4.1-nano 的重复调用 bug、Gemini 可聚合的 arguments、Anthropic 带并行调用的流式。
  12. 代码即动作
    让模型写代码去调工具,靠着把中间数据挡在上下文之外,使一条被公开报告的工作流从 150,000 token 降到 2,000——而它花掉的是动作日志,因为策略执行、审批闸门与审计全都以工具调用为钥匙,而一段程序从不吐出工具调用。
  13. 塑形工具返回值
    一份工具定义值几百个 token、每轮只付一次;一次未塑形的返回值可以值四万个 token,且之后每一轮都被重发——它同时还是窗口里最大的一块不可信文本。做投影、先排序再截断、分页、递回句柄;给所有工具一个统一信封和一个由框架强制的上限。
  14. 技能、子智能体、MCP 还是钩子:该用哪个
    必须每次发生的用钩子,要触达系统用 MCP,传授做法用技能,嘈杂的活交给子智能体,每轮都需要的写进指令文件;插件只负责打包分发。决定性的轴是谁来扣扳机,而不是上下文成本。
  15. 工具注解是提示,不是闸门
    MCP 的四个提示默认值是刻意悲观的——readOnlyHint 为假、destructiveHint 为真、idempotentHint 为假、openWorldHint 为真——而规范说:除非服务端可信,否则按不可信对待。两者并起来,那个一个注解都不发的老实服务端每次调用都吃一个确认弹窗,而那个断言 readOnlyHint 的则一声不响地跑掉,于是界面在奖励断言。请把风险等级建在客户端、以(端点、包摘要、工具名)为键、在安装时钉死,并把提示降级为一次预填加一个漂移告警——重试策略里也一样,那里一个错的 idempotentHint 会把消息发两遍。