用 Agent 编写有效的 Agent 工具
- 原文标题：Writing effective tools for agents — with agents
- 原文链接：https://www.anthropic.com/engineering/writing-tools-for-agents
- 发布时间：2025-09-11
- 来源：Anthropic Engineering
- 主题：工具设计、Agent 自举、tool ergonomics
本文是中文精读笔记，不是原文全文翻译。
这篇文章解决什么问题
给人用的 API 不一定适合给模型用。Agent 工具需要让模型容易判断何时调用、如何填参数、如何理解结果。文章讨论如何设计有效工具，并用 Agent 辅助编写这些工具。
核心内容
- 工具应该暴露任务语义，而不是底层实现细节。
- 参数要少而明确，返回值要可解释、可继续行动。
- 错误信息要告诉模型下一步该怎么修，而不是只抛异常。
- Agent 可以参与工具生成和迭代，但仍需要人类审查边界和安全。
深度精读
这篇文章最实用的观点是：Agent 工具不是普通 API。普通 API 面向程序员，程序员能读文档、理解上下文、调试错误；Agent 工具面向模型，模型依赖名称、描述、参数和返回值来判断下一步。工具设计得不好，模型就会频繁选错、填错、读不懂结果。
一个有效工具通常有几个特征：名称表达任务意图，参数数量少且语义清楚，描述说明何时使用和何时不要使用，返回结果结构化且包含下一步线索，错误信息可恢复。比如“search_documents”要比“query”更清楚，“limit”要说明默认值和上限，错误要告诉模型是参数错、权限错还是没有结果。
用 Agent 写工具的价值在于加速迭代。你可以让 Agent 根据失败轨迹提出新工具或改进 schema，但最终仍需要工程师检查安全边界、权限和返回数据。工具是 Agent 的手，手越长，护栏越要清楚。
学习时重点看什么
- 工具名称、描述、参数和返回值都是模型的操作界面。
- 错误信息要可恢复，而不是只告诉模型失败。
- 让 Agent 参与工具设计可以提速，但不能跳过人类安全审查。
工程启发
- 工具设计要从模型的“可用性”出发，而不是从工程师熟悉的 API 形态出发。
- 好工具能减少上下文和推理成本。
- 工具越强，权限、审计和失败处理越不能省。
和本站章节的关系
面试追问
- 什么样的 API 不适合作为 Agent 工具？
- 工具返回值应该怎样帮助模型继续行动？
- 如何用 Agent 辅助设计工具但避免安全漏洞？