为 AI Agent 编写高效工具：Anthropic 工程指南

Anthropic 推出了一套用于构建和优化 AI Agent 工具的全面方法论，将软件开发范式从确定性契约（系统对系统）转向非确定性契约（Agent 对系统）。核心要点是，工具的设计必须专门针对 LLM 的“可负担性”（affordances）——优先考虑上下文效率和语义清晰度，而非传统的 API 灵活性。

以 Agent 为中心的工具化范式

传统的软件构建在确定性契约之上，即特定的输入总是产生相同的输出。相比之下，AI Agent 是非确定性的；它们可能会根据相同的提示词选择调用工具、依赖内部知识或请求澄清。

为了最大限度地提高 Agent 的效能，开发者必须摆脱将工具编写为标准 API 的思维，转而设计能够增加 Agent 成功执行策略的“表面积”的工具。对 Agent 而言具有人体工程学特征的工具通常与直观的人类工作流保持一致。

工具开发的系统化工作流

Anthropic 建议通过原型设计、评估和 Agent 主导的优化这一迭代循环来精细化工具性能。

1. 原型设计与本地测试

开发者应从快速原型开始，利用 Claude Code 等工具生成初始实现。为了提高单次生成的质量，Anthropic 建议为相关的 SDK 或 API 提供对 LLM 友好的文档（例如 llms.txt 文件）。工具可以通过以下方式进行本地测试：

Local MCP Servers: 通过 claude mcp add 连接到 Claude Code。
Desktop Extensions (DXT): 集成到 Claude Desktop 应用中。
Direct API Calls: 使用 Anthropic API 进行程序化测试。

2. 评估驱动的优化

需要进行系统化的测量以避免过拟合并确保现实世界的有效性。这包括：

生成复杂任务： 避免简单的“沙盒”提示词，转而采用多步骤、现实世界的场景（例如，通过分析日志并识别受影响的用户来解决客户账单纠纷）。
可验证的结果： 将提示词与标准答案（ground-truth）配对，或使用基于 LLM 的裁判进行验证。
程序化执行： 在 while-loops 中运行评估 Agent，在 LLM API 调用和工具执行之间交替进行。
交错思维： 在工具调用之前利用“交错思维”或思维链（CoT）块，以诊断 Agent 为何未能使用工具或选择了低效路径。

3. Agent 主导的精细化

Anthropic 发现，Agent 在分析自身的失败记录时非常高效。通过将评估记录反馈给 Claude Code，开发者可以自动重构工具实现和描述，以确保自洽性和性能。

高性能工具的核心原则

策略性工具选择

工具并非越多越好。与传统软件丰富的内存相比，Agent 的上下文窗口是有限的。

避免暴力工具： 与其使用返回所有数据的 list_contacts 工具（迫使 Agent 逐个 token 阅读），不如实现一个 search_contacts 工具。
整合功能： 将多个离散的 API 调用合并为一个单一的高层级工具。例如，与其使用独立的 list_users 和 create_event 工具，不如创建一个 schedule_event 工具，在一个调用中处理可用性和调度问题。

命名空间与边界定义

为了防止 Agent 在访问跨多个 MCP 服务器的数百个工具时产生混淆，开发者应使用命名空间（将相关工具归类在共同的前缀下）。

示例： 使用 asana_projects_search 和 jira_projects_search 有助于 Agent 划定不同服务之间的边界。

优化上下文与信号

工具响应应优先考虑高信号信息，并尽量减少 token 浪费。

语义标识符： 使用自然语言名称或从 0 开始的 ID 来替换晦涩的 UUID，以减少幻觉。
响应格式： 实现一个 response_format 枚举（例如，n CONCISE 与 DETAILED）。简洁的响应可以节省 token，而详细的响应则为下游工具调用提供必要的 ID。
Token 效率： 使用分页、范围选择和截断来管理上下文。Anthropic 将 Claude Code 的工具响应默认设置为 25,000 tokens。

为工具规范编写提示词工程

工具描述在 Agent 的上下文中起到了引导机制的作用。Anthropic 指出，对工具描述进行精确的精细化对于 Claude Sonnet 3.5 在 SWE-bench Verified 评估中达到顶尖性能至关重要。

显式上下文： 描述工具时就像向新员工解释一样，包括小众术语和专门的查询格式。
无歧义的命名： 使用具体的参数名称（例如，user_id 而不是 user）以强制执行严格的数据模型。