工具使用的工作原理

了解工具使用循环、工具的执行位置，以及何时使用工具而非纯文本。

本页解释工具使用背后的概念：工具的运行位置、agentic 循环的工作原理，以及何时工具使用是正确的方法。有关实践指导，请从教程或实现指南开始。

工具使用契约

工具使用是你的应用程序和模型之间的契约。你指定哪些操作可用以及它们的输入和输出的形状；Claude 决定何时以及如何调用它们。模型本身从不执行任何操作。它发出一个结构化请求，你的代码（或 Anthropic 的服务器）运行操作，结果流回对话中。

这种契约使模型的行为更像你调用的函数，而不是文本生成器。具有经典 API 经验的工程师可以像集成任何其他类型化接口一样集成工具使用：定义 schema，处理回调，返回结果。区别在于另一端的调用者是根据对话选择调用哪个函数的语言模型。

工具的运行位置

工具之间的主要区别在于代码的执行位置。每个工具都属于三个类别之一，该类别决定了你的应用程序的责任。

用户定义的工具（客户端执行）

你编写 schema，你执行代码，你返回结果。这是主要内容：绝大多数工具使用流量是用户定义的工具调用特定于应用程序的逻辑。

当 Claude 决定使用你的工具之一时，API 响应包含一个 tool_use 块，其中包含工具名称和参数的 JSON 对象。你的应用程序提取这些参数，运行操作（数据库查询、HTTP 调用、文件写入，无论工具做什么），并在下一个请求中将输出发送回 tool_result 块。Claude 永远不会看到你的实现；它只看到你提供的 schema 和你返回的结果。

Anthropic-schema 工具（客户端执行）

对于少量常见操作（运行 shell 命令、编辑文件、控制浏览器、管理便签内存），Anthropic 发布工具 schema，你的应用程序处理执行。此类别中的工具是 bash、text_editor、computer 和 memory。

执行模型与用户定义的工具相同：响应包含 tool_use 块，你的代码运行操作，你发送回 tool_result。使用 Anthropic-schema 工具而不是定义自己的等效工具的原因是这些 schema 是经过训练的。Claude 已经在数千个使用这些确切工具签名的成功轨迹上进行了优化，因此它比使用做同样事情的自定义工具更可靠地调用它们，并且更优雅地从错误中恢复。schema 是模型已经期望的接口。

服务器端执行的工具

对于 web_search、web_fetch、code_execution 和 tool_search，Anthropic 运行代码。你在请求中启用工具，服务器处理其他所有事情。你永远不需要为这些工具构造 tool_result 块，因为服务器端循环执行操作并在响应到达你之前将输出反馈给模型。

你收到的响应包含 server_tool_use 块，显示运行了什么以及返回了什么，但当你看到它们时，执行已经完成。你的应用程序的工作是启用工具并读取最终答案，而不是参与执行循环。

Agentic 循环（客户端工具）

客户端执行的工具（包括用户定义和 Anthropic-schema）需要你的应用程序驱动一个循环。模型无法运行你的代码，因此每个工具调用都是一个往返：模型请求，你执行，你报告，模型继续。

规范形状是一个基于 stop_reason 的 while 循环：

1. 发送包含 tools 数组和用户消息的请求。
2. Claude 返回 stop_reason: "tool_use" 和一个或多个 tool_use 块。
3. 执行每个工具。将输出格式化为 tool_result 块。
4. 发送包含原始消息、助手响应和包含 tool_result 块的用户消息的新请求。
5. 当 stop_reason 为 "tool_use" 时，从步骤 2 重复。

实际上这读作：当 stop_reason == "tool_use" 时，执行工具并继续对话。循环在任何其他停止原因时退出（"end_turn"、"max_tokens"、"stop_sequence" 或 "refusal"），这意味着 Claude 已经产生了最终答案或由于你的应用程序应该处理的其他原因停止。

有关构建请求、处理并行工具调用和格式化结果的机制，请参阅处理工具调用。

服务器端循环

服务器端执行的工具在 Anthropic 的基础设施内运行自己的循环。你的应用程序的一个请求可能会在响应返回之前触发多次网络搜索或代码执行。模型搜索、读取结果、决定再次搜索，并迭代直到获得所需内容，所有这些都不需要你的应用程序参与。

这个内部循环有一个迭代限制。如果模型在达到上限时仍在迭代，响应会返回 stop_reason: "pause_turn" 而不是 "end_turn"。暂停的回合意味着工作尚未完成；重新发送对话（包括暂停的响应）以让模型从上次停止的地方继续。有关延续模式，请参阅服务器工具。

何时使用工具（以及何时不使用）

当任务需要模型无法仅从文本完成的事情时，工具使用是合适的：

• 具有副作用的操作。 发送电子邮件、写入文件、更新记录。模型可以描述这些操作，但只有工具才能执行它们。
• 新鲜或外部数据。 当前价格、今天的天气、数据库的内容。训练数据之外或特定于你的系统的任何内容都需要工具来获取。
• 结构化的、保证形状的输出。 当你需要具有特定字段的 JSON 对象而不是恰好包含信息的文本时，工具 schema 会强制执行形状。
• 调用现有系统。 数据库、内部 API、文件系统。工具使用是自然语言请求与满足它们的系统之间的桥梁。

你应该使用工具的迹象：如果你正在编写正则表达式从模型输出中提取决策，该决策应该是一个工具调用。解析自由格式文本以恢复结构化意图表明该结构属于 schema。

工具使用不合适的情况：

• 模型可以仅从训练中回答。摘要、翻译和一般知识问题不需要工具往返。
• 交互是一次性问答，没有副作用。如果没有要执行的内容，工具就无事可做。
• 工具调用延迟会主导简单响应。每个工具调用至少需要一次额外的往返；对于轻量级任务，开销可能超过工作量。

在方法之间选择

后续步骤