3 篇博文 含有标签「tool-design」

在你的技术栈中，每一个设计良好的 HTTP API 都会返回分页结果。没有人会把一百万行数据加载进内存并祈祷一切顺利。然而，你的智能体（agent）所调用的工具却会返回整个列表，而智能体也会尽职尽责地阅读它，因为函数签名写的是 list_orders() -> Order[]，且智能体不像人类用户那样拥有“滚动并加载更多”的协议。

智能体在原本可以跳过的行上浪费了 Token。拥有 50K 记录的长尾客户遇到了中等规模客户从未见过的上下文窗口失败。工具作者无法从追踪（trace）中判断智能体是需要所有这些行，还是仅仅因为无法请求更少的数据。而且，在你评估套件的某个地方，原本会标记这种退化的回归测试从未运行，因为每个测试固件（test fixture）的记录都少于 100 条。

分页不是一种 UI 交互功能。它是一种负载卸载（load-shedding）原语 —— 而在没有分页的情况下使用工具的智能体，正在重新犯下你们公司的 API 设计师们花了十年时间才学会避免的每一个 SELECT * FROM orders 错误。

智能体对话记录中最危险的一句话不是幻觉。而是四个冷静的词：“我没有找到。”智能体听起来在认知上表现出谦逊。听起来像是完成了尽职调查。对于任何下游读者或调用者来说，这听起来完全像是一个事实。然而，这句话并没有提供关于该事物是否存在的信息。它只提供了关于特定工具在使用特定查询、咨询特定索引（而智能体恰好在那个时刻有权访问该索引）时发生了什么的信息。

在这两种解读之间，隐藏着一个随时可能发生的生产事故。支持智能体告诉客户“我们没有你的订单记录”，因为同步延迟导致写入只读副本的时间推迟了 90 秒。编码智能体声明“该模块没有测试”，因为它搜索了一个不包含测试文件夹的目录。合规智能体回答“档案中没有先前的违规记录”，因为审计索引尚未摄取上周的报告。在每种情况下，智能体的输出在语法上都是一种否定，但在认知上，它只是一个被重新表述为断言的“耸肩”。

大多数工程师对待智能体工具的方式与编写 REST 接口或库函数如出一辙：清晰地暴露功能、记录参数、处理错误。这对人类来说是正确的直觉。但对于 AI 智能体（AI Agents）来说，这完全是错误的。

智能体使用的工具是以非确定性的方式被消耗的，它被逐个 Token 解析，并由一个对上周二使用过什么工具没有持久记忆的模型来选择。你编写的工具 Schema 并不是文档——它是运行时提示词（runtime prompt），在推理时被注入到模型的上下文中，塑造着智能体做出的每一个决策。每一个字段名称、每一段描述、每一个返回值的结构都是一个设计决策，具有可衡量的性能影响。这就是智能体-计算机接口（ACI，Agent-Computer Interface），它值得你像对待任何关键的面向用户的界面一样投入工程精力。