Agent 工具设计：让代码承接复杂流程

把后端每个 API 都包装成 Agent 工具，看起来灵活，实际可能把流程编排、调用顺序和业务约束一起交给了模型。作者主张：对面向客户、涉及资金的自动化，优先提供能完成整项任务的「深工具」，让代码接管关键流程。

这个建议值得看，但证据要分开读：工具上下文开销有案例，成功率连乘是推算，工具选择研究也没有直接证明「合并工具更好」。对程序员最有用的，是重新检查模型和代码之间的职责边界。

一个 API 一个工具，为什么会越用越累

作者借用了 John Ousterhout 在《A Philosophy of Software Design》中的「深模块」概念：接口简单，内部隐藏大量功能。对应到 Agent，深工具接收业务意图，在内部完成多个步骤；浅工具只包一层 API，剩下的工作由调用方承担。

问题在于，现在的调用方是一个输出带有不确定性的模型。

假设用户要取消一笔 $29 的订阅。用细粒度工具完成这件事，可能需要连续调用六步。模型除了理解用户，还要记住下一步调用什么、哪些条件必须满足，以及失败后如何处理。

深工具则把这些步骤收进代码，模型只需要选择对应任务并提供参数。它的代价也很明确：用户提出未被建模的任务时，现有工具可能拼不出来。作者因此保留了例外：探索型、研究型 Agent 可能更需要自由组合能力。

工具边界应该围绕任务设计，具体取舍取决于任务是否需要自由组合。

三类成本里，哪些有证据，哪些只是推算

第一类是上下文成本。原文引用 Anthropic 的一个例子：58 个工具的 schema，在对话开始前就占用了约 55K tokens。大量工具描述会占用上下文，但这只是一个案例，不能当成所有工具注册表的固定成本。

第二类是链路错误累积。作者假设每一步成功率为 92%，六步全部成功的概率约为 60.6%。这个数字来自概率连乘，92% 是假设，不是实测结果。实际流程中的错误也可能相互关联，因此它更适合说明长链路的风险，不能直接用来预测生产成功率。

第三类是业务约束进入提示词。例如「总是先调用 X，再调用 Y」，其实是在让模型负责维护调用顺序。模型漏掉一句话，业务规则就可能失效。

作者还引用了一份尚未经过同行评审的 Meta 预印本：动态生成的候选列表平均包含 2.2 个工具，在正确工具被展示的条件下，选择正确率为 93.1%；固定展示五个工具时为 87.1%。

这里测的是候选列表长度，不是整个工具库规模，也没有测试工具合并。作者明确承认：其查到的来源中，没有浅工具与深工具的受控对照实验。这些材料支持减少重叠选项的方向，却不足以证明深工具一定胜出。

哪些事该交给模型，哪些必须写进代码

作者建议这样分工：模型理解请求，选择一个高层工具，并向用户展示操作预览；代码负责授权、加锁、业务约束检查，以及支付操作的幂等性。

幂等性可以理解为：同一请求因为重试执行多次，也不会重复扣款。

这套分工减少了模型需要临场判断的步骤，但代码执行稳定，并不等于业务结果正确。模型仍然可能选错工具、传错邮箱；代码也可能稳定地重复一条错误的按比例计费规则。真实业务规则仍然需要测试，退款前仍然需要明确确认。

作者给出的治理办法很具体：把几乎总是连续执行的工具合并；搜索 system prompt 中的「always call X before Y」，把规则变成工具内部检查，再删除对应提示词；用架构决策记录（ADR）写清边界，新 endpoint 是否应该成为独立工具，先经过评审。

我的判断

我赞成把资金操作和关键业务约束放进代码。调用顺序一旦影响业务正确性，就应该有可执行、可验证的约束。

但「优先深工具」有适用前提：任务相对稳定，团队也能把边界设计清楚。探索需求多、流程经常变化时，过早合并可能让工具接口不断膨胀。原文提到了这个取舍，没有给出维护成本的对照数据，因此这部分仍是架构经验之谈。

还要区分两种做法：减少模型眼前的候选工具，和把多个步骤合并成一个工具。前者可以保留底层组合能力，后者把流程固定在代码里。Meta 的结果涉及前者，不能直接替后者背书。两者可以配合，但解决的问题不同。

能拿来做什么

• 检查现有 Agent 的工具调用记录，找出几乎每次都按固定顺序出现的调用链，再评估是否封装成一个业务工具。
• 如果用 Node 承接 Agent 工具，把授权、锁、业务约束和支付幂等检查放进服务端实现，避免只依赖 system prompt 描述顺序。
• 给退款等操作补齐预览和明确确认，并用真实业务规则验证工具行为，尤其检查模型传入错误参数时会发生什么。
• 在 ADR 中记录工具为什么独立存在、内部负责哪些步骤，让新增 endpoint 成为工具之前先接受边界评审。