工具运行器（SDK）

"Tool runner"（工具运行器）会为您处理智能体循环、错误封装和类型安全，因此您无需手动处理这些工作。当您需要人工审批、自定义日志记录或条件执行时，请改用手动循环。

工具运行器无需您手动处理工具调用、工具结果和对话管理，而是自动完成以下操作：

• 在 Claude 调用工具时运行工具
• 处理请求/响应周期
• 管理对话状态
• 提供类型安全和验证



基本用法

使用 SDK 辅助函数定义工具，然后使用工具运行器来运行它们。

根据 SDK 的工具签名，工具会以字符串或内容块（文本、图像或文档块）的形式返回其结果，因此工具可以返回多模态结果。返回的字符串会成为单个文本内容块。要返回结构化数据（例如 JSON 对象或数字），请先将其编码为字符串。



迭代工具运行器

工具运行器是一个可迭代对象，会逐个产出来自 Claude 的消息。在每次迭代中，运行器会检查 Claude 是否请求了工具使用。如果是，它会运行该工具并自动将结果发送回 Claude，然后产出来自 Claude 的下一条消息以继续您的循环。

您可以在任何迭代中使用 break 语句结束循环。运行器会一直循环，直到 Claude 返回不包含工具使用的消息，或者达到您设置的 max_iterations（如果已设置）。

如果您不需要中间消息，可以直接获取最终消息：



高级用法

在循环内部，您可以读取每条响应消息，并在下一次 API 调用之前修改运行器的状态。每次迭代遵循以下生命周期：

1. 运行器使用其当前状态向 Messages API 发送请求。
2. 运行器将响应消息产出到您的循环体。
3. 您的循环体运行。您可以读取消息并选择性地修改运行器的状态。
4. 当您的循环体返回时，运行器会检查您是否修改了其消息历史记录。
   • 如果您未修改消息历史记录： 运行器会将助手消息追加到其状态中。如果消息包含工具调用，运行器会运行它们并追加结果。如果没有工具调用，循环退出。
   • 如果您修改了消息历史记录： 运行器会跳过其自动追加步骤，并原样使用您的状态。请参阅接管消息历史记录。



接管消息历史记录

默认情况下，运行器会为您管理对话状态：在每个回合之后，它会将助手消息和所有工具结果追加到自己的消息历史记录中。当您想要重试某个回合（丢弃响应并重新发送）、注入后续消息或自行构建工具结果时，可以接管消息历史记录。

您可以通过在循环体内部修改运行器的消息来接管。具体方法取决于所使用的 SDK。请参阅下面各语言的选项卡。

当您在某次迭代中接管时，运行器不会追加该回合的助手消息或工具结果。您需要负责保持对话的有效性：自行追加助手消息和工具结果（如果您希望该回合生效）、有条件地修改状态以便在没有工具调用时循环仍能退出，并传递 max_iterations 来限制循环次数。所有七个 SDK 都支持 max_iterations。



自动上下文管理

对于长时间运行的智能体任务，Python、TypeScript 和 Ruby 工具运行器支持自动压缩，当令牌使用量超过阈值时会生成摘要，使对话能够超越上下文窗口限制继续进行。这三个 SDK 都已弃用此客户端选项，转而使用服务器端上下文编辑，后者在所有 SDK 中均可用。Go、Java、C# 和 PHP 工具运行器不包含客户端压缩功能。



调试工具执行

当工具抛出异常时，工具运行器会捕获该异常，并将错误作为带有 is_error: true 的工具结果返回给 Claude。工具结果携带的是异常的消息（在 Python 中是其类型和消息），而不是完整的堆栈跟踪。

SDK 记录的日志内容因语言而异。每当工具引发未处理的异常时，Python SDK 会通过标准 logging 模块记录完整的异常（包括其堆栈跟踪）。Python、TypeScript 和 Java SDK 会读取 ANTHROPIC_LOG 环境变量以开启 SDK 的日志记录，其中包括请求和响应详情：

# 以 info 级别记录日志
export ANTHROPIC_LOG=info

# 以 debug 级别记录日志以获得更详细的输出
export ANTHROPIC_LOG=debug

Go、Ruby、C# 和 PHP SDK 不会读取 ANTHROPIC_LOG。除 Python 外，没有 SDK 会记录失败的工具：要查看工具失败的原因，请在工具函数内部捕获并记录异常，然后再返回或重新抛出它。



拦截工具错误

默认情况下，工具错误会被传回给 Claude，然后 Claude 可以做出适当的响应。但是，您可能希望检测错误并以不同方式处理它们，例如提前停止执行或实现自定义错误处理。

在 Python 和 TypeScript SDK 中，使用工具响应方法（Python 中的 generate_tool_call_response()，TypeScript 中的 generateToolResponse()）来拦截工具结果，并在它们被发送给 Claude 之前检查错误。其他 SDK 不公开该钩子。它们的选项卡描述了最接近的替代方案：



修改工具结果

您可以在工具结果被发送回 Claude 之前修改它们。这对于添加元数据（例如 cache_control 以在工具结果上启用提示缓存）或转换工具输出非常有用。

在 Python 和 TypeScript SDK 中，使用工具响应方法获取工具结果，然后在运行器继续之前修改它。是显式追加修改后的结果还是就地修改它，取决于所使用的 SDK。请参阅每个选项卡中的代码注释。



流式传输

启用流式传输以增量处理每个回合的响应。每次迭代会产出一个流对象，您可以迭代该对象以获取事件。



后续步骤