工具运行器 (SDK)

工具运行器处理代理循环、错误包装和类型安全，所以你不必手动处理。仅当你需要人工审批、自定义日志记录或条件执行时，才使用手动循环。在 Python、TypeScript 和 Ruby SDK 中可用。

工具运行器为使用 Claude 执行工具提供了开箱即用的解决方案。工具运行器自动处理工具调用、工具结果和对话管理，而不是手动处理它们：

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

对大多数工具使用实现，使用工具运行器。

基本用法

使用 SDK 助手定义工具，然后使用工具运行器执行它们。

工具函数必须返回内容块或内容块数组，包括文本、图像或文档块。这允许工具返回丰富的多模态响应。返回的字符串将被转换为文本内容块。如果你想向 Claude 返回结构化 JSON 对象，请在返回之前将其编码为 JSON 字符串。数字、布尔值或其他非字符串原始值也必须转换为字符串。

遍历工具运行器

工具运行器是一个可迭代对象，从 Claude 生成消息。这通常被称为"工具调用循环"。每次迭代，运行器检查 Claude 是否请求了工具使用。如果是，它调用工具并自动将结果发送回 Claude，然后生成来自 Claude 的下一条消息以继续你的循环。

你可以在任何迭代处使用 break 语句结束循环。运行器将循环直到 Claude 返回不包含工具使用的消息。

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

高级用法

在循环中，你可以完全自定义工具运行器对消息 API 的下一个请求。运行器自动将工具结果附加到消息历史记录，所以你不需要手动管理它们。你可以选择检查工具结果以进行日志记录或调试，并在下一个 API 调用之前修改请求参数。

调试工具执行

当工具抛出异常时，工具运行器捕获它并将错误作为工具结果返回给 Claude，其中 is_error: true。默认情况下，仅包含异常消息，不包含完整堆栈跟踪。

要查看完整堆栈跟踪和调试信息，请设置 ANTHROPIC_LOG 环境变量：

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

启用后，SDK 记录完整的异常详细信息（在 Python 中使用 logging 模块，在 TypeScript 中使用控制台，或在 Ruby 中使用记录器），包括工具失败时的完整堆栈跟踪。

拦截工具错误

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

使用工具响应方法拦截工具结果并在将其发送给 Claude 之前检查错误：

修改工具结果

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

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

流式传输

启用流式传输以在事件到达时接收它们。每次迭代都会生成一个流对象，你可以迭代以获取事件。

后续步骤

• 有关工具调用循环的手动控制，请参阅处理工具调用。
• 有关并发运行多个工具，请参阅并行工具使用。
• 有关完整的工具使用工作流，请参阅定义工具。