工具运行器 (SDK)

Tool Runner（SDK）

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

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

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

工具运行器目前处于测试版，可在 Python、TypeScript 和 Ruby SDK 中使用。

使用压缩进行自动上下文管理

工具运行器支持自动压缩，当令牌使用量超过阈值时生成摘要。这允许长时间运行的代理任务继续超越上下文窗口限制。

基本用法

使用 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；请参阅每个选项卡中的代码注释。

向工具结果添加 cache_control 特别有用，当工具返回大量数据（如文档搜索结果）时，你想为后续 API 调用缓存这些数据。有关缓存策略的更多详细信息，请参阅提示缓存。

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