Agent 学习笔记 05：工具不是函数加个装饰器：如何设计可靠的 Agent 工具

真正让 Agent 变得不稳定的，往往不是模型换了一种说法，而是工具接口没有把输入、权限和失败方式讲清楚。工具本质上是模型与真实系统之间的一份契约：模型负责提出调用意图，应用负责决定这次调用能否发生。

一个好工具先要“容易被正确选择”

工具名、描述和参数 schema 都会参与模型判断。search 这种名字太宽泛，search_product_docs 就清楚得多；描述里不仅要写“能做什么”，还要写适用范围和不适用场景。参数也应尽量使用枚举、范围、必填字段和示例，减少模型自由发挥。

{
  "name": "search_product_docs",
  "arguments": {"query": "退款时限", "product": "企业版", "top_k": 5}
}

这份结构不是为了好看，而是为了让参数校验、日志记录和回归测试都能自动化。

搜索加计算器 Agent 的真实链路

一个“搜索后计算”的任务至少包含两种不同风险：搜索结果可能不可靠，计算表达式可能不安全。可靠链路应该是：

问题拆解 -> 搜索可信来源 -> 提取数值与单位 -> 受限计算器运算 -> 校验量纲 -> 组织答案

搜索工具最好返回标题、URL、摘要、抓取时间和来源类型；计算器只接受表达式语法树或经过白名单解析的操作，绝不能把模型输出直接交给 eval。

返回值也必须有契约

工具只返回一段自然语言，会让 Agent 很难区分“没有结果”“权限不足”和“服务异常”。我更倾向于统一返回 status、data、error_code、retryable 和 request_id。这样模型可以根据状态继续询问，程序也能做重试、告警和审计。写入类工具还应带幂等键，避免超时重试造成重复发信、重复扣款或重复建单。

按副作用分级

查询类工具可以在权限通过后自动执行；创建草稿、生成变更方案适合先预览；发送邮件、删除数据、付款和部署则应要求明确确认。工具层需要把身份、资源范围和动作风险一起判断，不能只因为模型生成了合法参数就放行。

这章给我的启发

工具不是“函数加个装饰器”，而是一道产品与安全边界。描述越清楚、schema 越严格、失败语义越稳定，模型的灵活性就越容易转化成可靠能力。