利用智能体编写高效的工具——借助智能体本身

# 为 AI Agent 编写高效的工具——借助 AI Agent 之力 来源：https://www.anthropic.com/engineering/writing-tools-for-agents 模型上下文协议（MCP）（https://modelcontextprotocol.io/docs/getting-started/intro）能够为 LLM Agent 提供数百种工具，以解决现实世界中的任务。但如何让这些工具发挥最大效用？在这篇文章中，我们将介绍在各种智能体 AI 系统中提升效果的最佳实践。首先，我们将涵盖以下内容： - 构建并测试工具原型 - 创建并运行针对工具的全面评估，使用 Agent 参与 - 与 Claude Code 等 Agent 协作，自动提升工具性能 最后，我们总结了在实践过程中发现的高效工具编写核心原则： - 选择合适的工具来实现（以及不实现哪些） - 通过命名空间划分工具，明确功能边界 - 从工具返回有意义的上下文给 Agent - 优化工具响应的 token 效率 - 对工具描述和规格进行提示工程 这是一张示意图，展示了工程师如何使用 Claude Code 评估智能体工具的效果。构建评估体系可以让你系统地衡量工具性能。你可以利用 Claude Code 针对该评估自动优化工具。 ## 什么是工具？ 在计算领域，确定性系统在相同输入下始终产生相同输出，而**非确定性**系统——如 Agent——即使在相同初始条件下也可能生成不同的响应。 传统上，我们编写软件时是在确定性系统之间建立契约。例如，函数调用 `getWeather("NYC")` 每次调用时都会以完全相同的方式获取纽约市的天气。 工具是一种新型软件，它反映的是确定性系统与非确定性 Agent 之间的契约。当用户问"今天需要带伞吗？"时，Agent 可能会调用天气工具、依靠通用知识回答，甚至先反问地点以澄清问题。偶尔，Agent 也可能产生幻觉，或根本无法理解如何使用工具。 这意味着为 Agent 编写软件需要从根本上重新思考我们的方法：我们不能再像为其他开发者或系统编写函数和 API 那样来编写工具和 [MCP 服务器](https://modelcontextprotocol.io/)，而需要专门为 Agent 设计它们。我们的目标是通过工具让 Agent 能够采用多种成功策略，从而扩大其在广泛任务中的有效覆盖范围。 幸运的是，根据我们的经验，对 Agent 最"符合人体工学"的工具，对人类来说往往也出奇地直观易懂。 ## 如何编写工具 本节介绍如何与 Agent 协作来编写和改进你提供的工具。首先快速搭建工具原型并在本地测试。接着运行全面评估来衡量后续改进。与 Agent 一起，你可以重复评估和改进的过程，直到 Agent 在真实任务上取得出色表现。 ### 构建原型 如果不亲自动手，很难预判哪些工具对 Agent 来说是符合人体工学的，哪些不是。先从快速搭建工具原型开始。 如果你使用 [Claude Code](https://www.anthropic.com/claude-code) 来编写工具（可能一次性完成），最好向 Claude 提供工具所依赖的任何软件库、API 或 SDK 的文档（包括可能的 [MCP SDK](https://modelcontextprotocol.io/docs/sdk)）。LLM 友好的文档通常可以在官方文档网站的扁平 `llms.txt` 文件中找到（例如我们的 [API 文档](https://docs.anthropic.com/llms.txt)）。 将你的工具包装在 [本地 MCP 服务器](https://modelcontextprotocol.io/docs/develop/connect-local-servers) 或 [Desktop 扩展](https://www.anthropic.com/engineering/desktop-extensions)（DXT）中，可以让你在 Claude Code 或 Claude Desktop 应用中连接和测试工具。 要将本地 MCP 服务器连接到 Claude Code，运行 `claude mcp add [args...]`。要将本地 MCP 服务器或 DXT 连接到 Claude Desktop 应用，分别导航至 `Settings > Developer` 或 `Settings > Extensions`。 工具也可以直接传入 [Anthropic API](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview) 调用中进行程序化测试。 亲自测试工具以发现任何粗糙之处。收集用户反馈，建立对工具预期使用场景和提示词的直觉。 ### 运行评估 接下来，你需要通过运行评估来衡量 Claude 使用工具的效果。从生成大量基于真实使用场景的评估任务开始。我们建议与 Agent 协作来分析结果并确定如何改进工具。 在我们的[工具评估 Cookbook](https://platform.claude.com/cookbook/tool-evaluation-tool-evaluation) 中查看这一端到端流程。 *此图衡量了人工编写与 Claude 优化的 Slack MCP 服务器的测试集准确率。* **我们内部 Slack 工具的留出测试集性能** **生成评估任务** 有了早期原型，Claude Code 可以快速探索你的工具并创建数十组提示词和响应配对。提示词应受真实使用场景启发，基于真实的数据源和服务（例如内部知识库和微服务）。我们建议避免过于简单或肤浅的"沙盒"环境，因为它们无法以足够的复杂性来压力测试你的工具。 高质量的评估任务可能需要多次工具调用——可能多达数十次。以下是一些高质量任务的例子： - 下周与 Jane 安排一次会议，讨论我们最新的 Acme Corp 项目。附上我们上次项目规划会议的笔记，并预订一间会议室。 - 客户 ID 9182 报告他们在单次购买尝试中被扣款三次。查找所有相关日志条目，并确定是否有其他客户受到同一问题的影响。 - 客户 Sarah Chen 刚刚提交了取消请求。准备一份挽留方案。确定：（1）他们离开的原因，（2）最有吸引力的挽留方案是什么，以及（3）在提出方案前应注意的任何风险因素。 以下是一些较弱的任务例子： - 下周与 [email protected] 安排会议。 - 在支付日志中搜索 `purchase_complete` 和 `customer_id=9182`。 - 查找客户 ID 45892 的取消请求。 每个评估提示词都应配有一个可验证的响应或结果。你的验证器可以简单到只是对真实答案和采样响应进行精确字符串比较，也可以复杂到让 Claude 来评判响应。避免过于严格的验证器因格式、标点符号或合理的替代表述等无关差异而拒绝正确响应。 对于每组提示词-响应配对，你还可以选择性地指定期望 Agent 在解决问题时调用的工具，以衡量 Agent 是否成功理解了每个工具的用途。然而，由于可能存在多种正确的解决路径，尽量避免过度指定或过度拟合特定策略。 **运行评估** 我们建议通过直接的 LLM API 调用以编程方式运行评估。使用简单的智能体循环（`while` 循环包装交替的 LLM API 调用和工具调用）：每个评估任务一个循环。 每个评估 Agent 应被赋予单一任务提示词和你的工具。在评估 Agent 的系统提示词中，我们建议指示 Agent 不仅输出结构化的响应块（用于验证），还要输出推理和反馈块。指示 Agent 在工具调用和响应块**之前**输出这些内容，可能通过触发思维链（CoT）行为来提高 LLM 的有效智能。 如果你使用 Claude 运行评估，可以开启[交错思考](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#interleaved-thinking)以获得类似的"开箱即用"功能。这将帮助你探究 Agent 为何调用或不调用某些工具，并突出工具描述和规格中有待改进的具体方面。 除了顶层准确率之外，我们还建议收集其他指标，如单个工具调用和任务的总运行时间、工具调用总次数、总 token 消耗量以及工具错误。跟踪工具调用可以帮助揭示 Agent 常用的工作流程，并为工具整合提供机会。 *此图衡量了人工编写与 Claude 优化的 Asana MCP 服务器的测试集准确率。* **我们内部 Asana 工具的留出测试集性能** **分析结果** Agent 是你发现问题的得力伙伴，能提供从矛盾的工具描述到低效的工具实现和令人困惑的工具模式等各方面的反馈。然而，请记住，Agent 在反馈和响应中**省略**的内容往往比它们**包含**的内容更重要。LLM 并不总是[言其所想](https://www.anthropic.com/research/tracing-thoughts-language-model)。 观察 Agent 在哪里受阻或困惑。仔细阅读评估 Agent 的推理和反馈（或 CoT）以发现粗糙之处。审查原始记录（包括工具调用和工具响应），以捕捉 Agent CoT 中未明确描述的行为。要读出言外之意；记住你的评估 Agent 未必知道正确答案和策略。 分析你的工具调用指标。大量冗余的工具调用可能表明需要对分页或 token 限制参数进行适当调整；大量无效参数的工具错误可能表明工具需要更清晰的描述或更好的示例。 当我们推出 Claude 的[网页搜索工具](https://www.anthropic.com/news/web-search)时，我们发现 Claude 会不必要地在工具的 `query` 参数后追加 `2025`，这会偏置搜索结果并降低性能（我们通过改进工具描述将 Claude 引向了正确方向）。 ### 与 Agent 协作 你甚至可以让 Agent 为你分析结果并改进工具。只需将评估 Agent 的记录连接起来粘贴到 Claude Code 中。Claude 擅长分析记录并一次性重构大量工具——例如，确保在做出新更改时，工具实现和描述保持自相一致。 事实上，这篇文章中的大部分建议都来自我们使用 Claude Code 反复优化内部工具实现的过程。我们的评估建立在内部工作空间之上，反映了我们内部工作流程的复杂性，包括真实的项目、文档和消息。我们依赖留出测试集来确保不会对"训练"评估过拟合。这些测试集揭示，即使超出我们使用"专家"工具实现所取得的成果——无论这些工具是由我们的研究人员手动编写还是由 Claude 本身生成——我们仍能提取额外的性能提升。 在下一节中，我们将分享从这一过程中获得的一些经验。 ## 编写高效工具的原则 本节将我们的经验提炼为编写高效工具的几条指导原则。 ### 为 Agent 选择合适的工具 更多的工具并不总是带来更好的结果。我们观察到的一个常见错误是，工具仅仅是对现有软件功能或 API 端点的包装——无论这些工具是否适合 Agent。 这是因为 Agent 与传统软件有不同的"功能可见性"——即它们感知可用工具潜在行动方式的能力不同。 LLM Agent 的"上下文"有限（即它们一次能处理的信息量有限），而计算机内存则廉价且充足。考虑在通讯录中搜索联系人的任务。传统软件程序可以高效地逐个存储和处理联系人列表，逐一检查。然而，如果 LLM Agent 使用一个返回**所有**联系人的工具，然后不得不逐 token 阅读每个联系人，它就在无关信息上浪费了有限的上下文空间（想象通过从上到下阅读每一页来搜索通讯录中的联系人——即暴力搜索）。 对 Agent（和人类）来说更好更自然的方式是先跳到相关页面（也许按字母顺序查找）。我们建议构建少量精心设计的工具，针对特定的高影响力工作流程，与你的评估任务匹配，然后逐步扩展。 在通讯录的例子中，你可能会选择实现 `search_contacts` 或 `message_contact` 工具，而不是 `list_contacts` 工具。 工具可以整合功能，在底层处理可能**多个**离散操作（或 API 调用）。例如，工具可以用相关元数据丰富工具响应，或在单个工具调用中处理经常串联的多步骤任务。以下是一些例子： - 与其实现 `list_users`、`list_events` 和 `create_event` 工具，不如考虑实现一个 `schedule_event` 工具，它可以查找可用时间并安排事件。 - 与其实现 `read_logs` 工具，不如考虑实现一个 `search_logs` 工具，只返回相关日志行及其周围上下文。 - 与其实现 `get_customer_by_id`、`list_transactions` 和 `list_notes` 工具，不如实现一个 `get_customer_context` 工具，一次性汇总客户的所有近期相关信息。 确保你构建的每个工具都有清晰、独特的用途。工具应该让 Agent 能够以与人类相同的方式分解和解决任务，前提是能访问相同的基础资源，同时减少原本会被中间输出消耗的上下文。 过多工具或重叠工具也可能分散 Agent 的注意力，使其无法追求高效策略。对构建（或不构建）哪些工具进行谨慎、有选择的规划确实能带来回报。 ### 为工具设置命名空间 你的 AI Agent 可能会获得访问数十个 MCP 服务器和数百种不同工具的权限——包括其他开发者开发的工具。当工具功能重叠或目的模糊时，Agent 可能会混淆该使用哪些工具。 命名空间（将相关工具分组在共同前缀下）可以帮助划分大量工具之间的边界；MCP 客户端有时会默认这样做。 例如，按服务（如 `asana_search`、`jira_search`）和按资源（如 `asana_projects_search`、`asana_users_search`）对工具进行命名空间划分，可以帮助 Agent 在正确的时间选择正确的工具。 我们发现，选择基于前缀还是后缀的命名空间方案，会对工具使用评估产生非平凡的影响。效果因 LLM 而异，我们鼓励你根据自己的评估来选择命名方案。 Agent 可能会调用错误的工具、用错误的参数调用正确的工具、调用过少的工具，或错误地处理工具响应。通过有选择地实现那些名称反映任务自然细分的工具，你可以同时减少加载到 Agent 上下文中的工具和工具描述数量，并将智能体计算从 Agent 的上下文转移到工具调用本身。这降低了 Agent 整体犯错的风险。