为Agent编写有效工具
原文：Writing effective tools for agents — with agents 发布时间：2025年9月11日
核心观点
Agent 的有效性取决于我们为它们提供的工具质量。本文分享了如何编写高质量工具和评估，以及如何使用 Claude 来优化其自身工具以提升性能。
什么是工具？
在计算中，确定性系统在给定相同输入时总是产生相同输出，而非确定性系统（如 Agent）即使在相同起始条件下也可能产生不同的响应。
传统软件开发建立的是确定性系统之间的契约，而工具是一种新型软件，反映确定性系统和非确定性 Agent 之间的契约。
如何编写工具
1. 构建原型
- 快速搭建工具原型进行本地测试
- 使用 Claude Code 编写工具时，提供相关软件库、API 或 SDK 的文档
- 将工具包装在本地 MCP 服务器或桌面扩展中
- 收集用户反馈，了解预期用例和提示
2. 运行评估
生成评估任务
- 基于真实世界使用场景生成大量评估任务
- 避免过于简化的”沙盒”环境
- 强评估任务可能需要多次工具调用
运行评估
- 使用程序化方式运行评估
- 在系统提示中指导 Agent 输出推理和反馈块
- 收集准确率、运行时、工具调用次数、token 消耗等指标
分析结果
- 观察 Agent 在哪里遇到困难或困惑
- 阅读评估 Agent 的推理和反馈
- 审查原始记录以发现未明确描述的行为
3. 与 Agent 协作优化
使用 Claude Code 自动优化工具性能，通过迭代评估和改进过程提升工具效果。
编写高质量工具的原则
1. 选择合适的工具实现
工具命名空间化
- 使用前缀或后缀命名空间来定义功能边界
- 减少工具数量，提高工具选择的准确性
- 将 Agent 计算从上下文转移到工具调用本身
避免过度实现
- 不要实现所有可能的工具
- 专注于自然任务细分的工具
- 减少 Agent 上下文中的工具描述数量
2. 从工具返回有意义的上下文
优先考虑上下文相关性
- 返回高信号信息而非低级别技术标识符
- 使用自然语言名称而非加密标识符
- 将任意字母数字 UUID 解析为更有语义意义的语言
提供响应格式控制
enum ResponseFormat {
DETAILED = "detailed",
CONCISE = "concise"
}- 允许 Agent 控制工具响应的详细程度
- 在简洁和详细响应之间平衡 token 使用
- 类似 GraphQL 的灵活性
3. 优化工具响应的 token 效率
实现上下文管理
- 分页、范围选择、过滤和截断
- 设置合理的默认参数值
- 限制工具响应到 25,000 tokens
指导 Agent 行为
- 鼓励使用更 token 高效的策略
- 提供清晰、可操作的错误响应
- 避免不透明的错误代码或堆栈跟踪
4. 提示工程工具描述
清晰描述工具
- 像向新员工描述工具一样编写描述
- 明确说明专业查询格式、术语定义、资源关系
- 避免歧义，使用严格的数据模型
参数命名
- 使用明确的参数名称（如
user_id而非user） - 清晰描述输入和输出
- 通过评估测量提示工程的影响
最佳实践总结
- 明确定义 - 工具应该被有意且清晰地定义
- 明智使用上下文 - 谨慎使用 Agent 上下文
- 可组合性 - 工具可以组合成多样化的工作流
- 直观性 - 使 Agent 能够直观地解决真实世界任务
未来展望
随着 Agent 能力的提升，我们需要从可预测的确定性模式重新定位软件开发实践到非确定性模式。通过系统化、评估驱动的方法，我们可以确保工具与 Agent 一起发展。