工具使用

使用 Anthropic Claude 模型，您可以指定模型可以用来回复消息的工具。例如，您可以指定一种工具来获取电台热门歌曲。如果用户发出消息：WZPZ 上的热门歌曲是什么？，模型将判断您指定的工具是否可以帮助回答问题。在响应中，模型将请求您代表其运行该工具。然后，您运行该工具并将工具结果传递给模型，然后模型会生成对原始消息的响应。有关更多信息，请参阅 Anthropic Claude 文档中的工具使用（函数调用）。

您可以在 tools 字段中指定想供模型使用的工具。以下示例展示了一种用于获取电台热门歌曲的工具。

[
    {
        "name": "top_song",
        "description": "Get the most popular song played on a radio station.",
        "input_schema": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
                }
            },
            "required": [
                "sign"
            ]
        }
    }
]

当模型需要工具来生成对消息的响应时，它会在消息 content 字段中返回有关所请求工具的信息以及对该工具的输入。它还会将响应的停止原因设置为 tool_use。

{
    "id": "msg_bdrk_01USsY5m3XRUF4FCppHP8KBx",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 375,
        "output_tokens": 36
    },
    "content": [
        {
            "type": "tool_use",
            "id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "name": "top_song",
            "input": {
                "sign": "WZPZ"
            }
        }
    ],
    "stop_reason": "tool_use"
}

在代码中，您代表工具调用该工具。然后，您在用户消息中将工具结果 (tool_result) 传递给模型。

{
    "role": "user",
    "content": [
        {
            "type": "tool_result",
            "tool_use_id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "content": "Elemental Hotel"
        }
    ]
}

在其响应中，模型使用工具结果为原始消息生成响应。

{
    "id": "msg_bdrk_012AaqvTiKuUSc6WadhUkDLP",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "content": [
        {
            "type": "text",
            "text": "According to the tool, the most popular song played on radio station WZPZ is \"Elemental Hotel\"."
        }
    ],
    "stop_reason": "end_turn"
}

精细工具流

精细工具流是一项适用于 Claude Sonnet 4.5、Claude Haiku 4.5、Claude Sonnet 4 和 Claude Opus 4 的 Anthropic Claude 模型功能。利用精细工具流，Claude 开发人员无需进行缓冲或 JSON 验证，即可流式传输工具使用参数，从而缩短开始接收大型参数的延迟。

要使用此功能，只需向工具使用请求添加标头 fine-grained-tool-streaming-2025-05-14 即可。

以下示例说明如何指定精细工具流标头：

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 1024,
  "anthropic_beta": ["fine-grained-tool-streaming-2025-05-14"],
  "messages": [
    {
      "role": "user",
      "content": "Can you write a long poem and make a file called poem.txt?"
    }
  ],
  "tools": [
    {
      "name": "make_file",
      "description": "Write text to a file",
      "input_schema": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "The filename to write text to"
          },
          "lines_of_text": {
            "type": "array",
            "description": "An array of lines of text to write to the file"
          }
        },
        "required": [
          "filename",
          "lines_of_text"
        ]
      }
    }
  ]
}

在此示例中，利用精细工具流，Claude 可以将一首长诗的各行内容流式传输到工具调用 make_file 中，无需进行缓冲来验证 lines_of_text 参数是否为有效的 JSON。这意味着您可以在参数流到达时查看它，而无需等待整个参数完成缓冲和验证。

借助精细工具流，工具使用块的流式传输启动速度更快，并且通常块会更长且包含的断字更少。此情况是由于分块行为的差异造成的。

例如，不使用精细流的情况下，延迟为 15 秒：

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

使用精细流的情况下，延迟为 3 秒：

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

计算机使用（测试版）

计算机使用是一项 Anthropic Claude 模型功能（测试版），适用于 Claude 3.5 Sonnet v2、Claude Sonnet 4.5、Claude Haiku 4.5、Claude 3.7 Sonnet、Claude Sonnet 4 和 Claude Opus 4。使用计算机使用时，Claude 可以帮助您通过基本的 GUI 操作自动执行任务。

计算机使用 API 提供了多种预定义的计算机使用工具以供您使用。然后，您可以根据您的请求创建提示，例如“向 Ben 发送一封包含我上次会议笔记的电子邮件”和屏幕截图（如果需要）。响应包含 JSON 格式的 tool_use 操作列表（例如，scroll_down、left_button_press、screenshot）。您的代码运行计算机操作并向 Claude 提供显示输出的屏幕截图（如果需要）。

自 Claude 3.5 v2 发布以来，tools 参数已更新，可支持接收多态工具类型；同时新增了一个 tool.type 属性以用于区分这些工具类型。type 是可选参数；如果省略此参数，则默认该工具为自定义工具（自定义工具是此前唯一受支持的工具类型）。要访问计算机使用，必须将 anthropic_beta 参数与相应的枚举结合使用，其值取决于所使用的模型版本。有关更多信息，请参阅下表。

只有使用此参数和枚举发出的请求才能使用计算机使用工具。可以按如下方式指定此参数："anthropic_beta": ["computer-use-2025-01-24"]。

有关更多信息，请参阅 Anthropic 文档中的计算机使用（测试版）。

以下是一个示例响应，它假定请求包含带有 Firefox 图标的桌面屏幕截图。

{
    "id": "msg_123",
    "type": "message",
    "role": "assistant",
    "model": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "content": [
        {
            "type": "text",
            "text": "I see the Firefox icon. Let me click on it and then navigate to a weather website."
        },
        {
            "type": "tool_use",
            "id": "toolu_123",
            "name": "computer",
            "input": {
                "action": "mouse_move",
                "coordinate": [
                    708,
                    736
                ]
            }
        },
        {
            "type": "tool_use",
            "id": "toolu_234",
            "name": "computer",
            "input": {
                "action": "left_click"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 3391,
        "output_tokens": 132
    }
}

Anthropic 定义的工具

Anthropic 提供了一组工具，使某些 Claude 模型能够高效地使用计算机。指定 Anthropic 定义的工具时，description 和 tool_schema 字段不是必填字段，也不允许填写。Anthropic 定义的工具由 Anthropic 定义，但您必须明确评估该工具的结果，并将 tool_results 返回到 Claude。与任何工具一样，模型不会自动执行该工具。Anthropic 定义的每种工具都拥有针对特定模型优化的版本，这些模型包括 Claude 3.5 Sonnet（新版）和 Claude 3.7 Sonnet：

{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_based_edit_tool" 
}

{ 
    "type": "computer_20250124", 
    "name": "computer" 
}

{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_editor"
}

{ 
    "type": "bash_20250124", 
    "name": "bash" 
}

{ 
    "type": "text_editor_20241022", 
    "name": "str_replace_editor"
}

{ 
    "type": "bash_20241022", 
    "name": "bash"
}

{ 
    "type": "computer_20241022", 
    "name": "computer"
}

type 字段用于标识工具及其参数，以便进行验证，name 字段是向模型展示的工具名称。

如果要提示模型使用其中某个工具，可通过 name 字段明确指定该工具。name 字段在工具列表中必须是唯一的；在同一次 API 调用中，您定义的工具不能与 Anthropic 定义的工具具有相同的 name。

自动工具调用清理（测试版）

自动清除工具调用是 Anthropic Claude 模型的一项功能（测试版）。借助此功能，Claude 可以在您接近令牌限制时自动清除旧工具使用结果，从而在多回合刀具使用场景中实现更有效的上下文管理。要使用工具使用清理功能，您需要在 anthropic_beta 请求参数的测试版标头列表中添加 context-management-2025-06-27。您还需要指定以下配置选项的用法clear_tool_uses_20250919并从中进行选择。

以下是 clear_tool_uses_20250919 上下文管理策略的可用控制项。所有控制项均为可选配置，或具有默认值：

记忆工具（测试版）

Claude Sonnet 4.5 新增了一款记忆工具，可让用户跨对话管理记忆。借助该功能，用户可通过向 Claude 授予对本地目录的访问权限，让其检索上下文窗口之外的信息。该功能将以测试版形式提供。要使用该功能，您必须使用 context-management-2025-06-27 测试版标头。

工具定义：

{
  "type": "memory_20250818",
  "name": "memory"
}

示例请求：

{
    "max_tokens": 2048,
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["context-management-2025-06-27"],
    "tools": [{
        "type": "memory_20250818",
        "name": "memory"
    }],
    "messages": [
        {
            "role": "user",
            "content": [{"type": "text", "text": "Remember that my favorite color is blue and I work at Amazon?"}]
        }
    ]
}

示例响应：

{
    "id": "msg_vrtx_014mQ5ficCRB6PEa5k5sKqHd",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4-20250514",
    "content": [
        {
            "type": "text",
            "text": "I'll start by checking your memory directory and then record this important information about you."
        },
        {
            "type": "tool_use",
            "id": "toolu_vrtx_01EU1UrCDigyPMRntr3VYvUB",
            "name": "memory",
            "input": {
                "command": "view",
                "path": "/memories"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 1403,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "output_tokens": 87
    },
    "context_management": {
        "applied_edits": []
    }
}

工具使用的成本注意事项

工具使用请求的定价基于以下因素：

工具的定价与所有其他 Claude API 请求的定价标准一致，但每次请求会产生额外词元。工具使用产生的额外词元来自以下各项：

当您使用工具时，Anthropic 模型会自动包含一个支持工具使用的专用系统提示。下表列出了每个模型所需的工具使用词元的数量。此表不包括前文所述的额外词元。请注意，此表假设提供了至少一种工具。如果未提供任何工具，且工具选择设为“无”，则不会产生额外的系统提示词元。

工具搜索工具（测试版）

Tool Search Tool Claude 允许使用数百甚至数千种工具，而无需预先将其所有定义加载到上下文窗口中。与其立即声明所有工具，不如使用工具搜索机制标记它们defer_loading: true，然后仅Claude查找和加载所需的工具。

要访问此功能，您必须使用测试版标题tool-search-tool-2025-10-19。请注意，此功能目前只能通过InvokeModel和使用InvokeModelWithResponseStream APIs。

工具定义：

{
    "type": "tool_search_tool_regex",
    "name": "tool_search_tool_regex"
}

请求示例：

{
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": [
        "tool-search-tool-2025-10-19"
    ],
    "max_tokens": 4096,
    "tools": [{
            "type": "tool_search_tool_regex",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            },
            "defer_loading": true
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string"
                    },
                    "file_types": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": ["query"]
            },
            "defer_loading": true
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What's the weather in Seattle?"
    }]
}

响应示例

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I'll search for the appropriate tools to help with this task."
        },
        {
            "type": "server_tool_use",
            "id": "srvtoolu_01ABC123",
            "name": "tool_search_tool_regex",
            "input": {
                "pattern": "weather"
            }
        },
        {
            "type": "tool_search_tool_result",
            "tool_use_id": "srvtoolu_01ABC123",
            "content": {
                "type": "tool_search_tool_search_result",
                "tool_references": [{
                    "type": "tool_reference",
                    "tool_name": "get_weather"
                }]
            }
        },
        {
            "type": "text",
            "text": "Now I can check the weather."
        },
        {
            "type": "tool_use",
            "id": "toolu_01XYZ789",
            "name": "get_weather",
            "input": {
                "location": "Seattle",
                "unit": "fahrenheit"
            }
        }
    ],
    "stop_reason": "tool_use"
}

直播示例

# Event 1: content_block_start(with complete server_tool_use block) {
    "type": "content_block_start",
    "index": 0,
    "content_block": {
        "type": "server_tool_use",
        "id": "srvtoolu_01ABC123",
        "name": "tool_search_tool_regex"
    }
}

# Event 2: content_block_delta(input JSON streamed) {
    "type": "content_block_delta",
    "index": 0,
    "delta": {
        "type": "input_json_delta",
        "partial_json": "{\"regex\": \".*weather.*\"}"
    }
}

# Event 3: content_block_stop(tool_use complete) {
    "type": "content_block_stop",
    "index": 0
}

# Event 4: content_block_start(COMPLETE result in single chunk) {
    "type": "content_block_start",
    "index": 1,
    "content_block": {
        "type": "tool_search_tool_result",
        "tool_use_id": "srvtoolu_01ABC123",
        "content": {
            "type": "tool_search_tool_search_result",
            "tool_references": [{
                "type": "tool_reference",
                "tool_name": "get_weather"
            }]
        }
    }
}

# Event 5: content_block_stop(result complete) {
    "type": "content_block_stop",
    "index": 1
}

自定义工具搜索工具

您可以通过定义返回tool_reference块的工具来实现自定义工具搜索工具（例如，使用嵌入式）。自定义工具必须有，defer_loading: false而其他工具则应有defer_loading: true。当你定义自己的工具搜索工具时，它应该返回一个工具结果，其中包含指向你Claude要使用的工具的tool_reference内容块。

预期的客户定义的工具搜索工具结果响应格式：

{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC123",
    "content": [{
            "type": "tool_reference",
            "tool_name": "get_weather"
        },
        {
            "type": "tool_reference",
            "tool_name": "weather_forecast"
        }
    ]
}

tool_name必须与请求中定义的工具相匹配defer_loading: true。然后，Claude 将可以访问这些工具的完整架构。

自定义搜索工具-详细示例

您可以通过定义返回tool_reference块的工具来实现自定义工具搜索工具（例如，使用嵌入或语义搜索）。除了正则表达式匹配之外，这还支持复杂的工具发现机制。

请求带有自定义 TST 的示例：

{
    "model": "claude-sonnet-4-5-20250929",
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["tool-search-tool-2025-10-19"],
    "max_tokens": 4096,
    "tools": [{
            "name": "semantic_tool_search",
            "description": "Search for available tools using semantic similarity. Returns the most relevant tools for the given query.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Natural language description of what kind of tool is needed"
                    },
                    "top_k": {
                        "type": "integer",
                        "description": "Number of tools to return (default: 5)"
                    }
                },
                "required": ["query"]
            },
            "defer_loading": false
        },
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            },
            "defer_loading": true
        },
        {
            "name": "search_flights",
            "description": "Search for available flights between locations",
            "input_schema": {
                "type": "object",
                "properties": {
                    "origin": {
                        "type": "string"
                    },
                    "destination": {
                        "type": "string"
                    },
                    "date": {
                        "type": "string"
                    }
                },
                "required": ["origin", "destination", "date"]
            },
            "defer_loading": true
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What's the weather forecast in Seattle for the next 3 days?"
    }]
}

Claude的响应（调用自定义 TST）：

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I'll search for the appropriate tools to help with weather information."
        },
        {
            "type": "tool_use",
            "id": "toolu_01ABC123",
            "name": "semantic_tool_search",
            "input": {
                "query": "weather forecast multiple days",
                "top_k": 3
            }
        }
    ],
    "stop_reason": "tool_use"
}

客户提供的工具结果

在工具库上执行语义搜索后，客户会返回匹配的工具引用：

{
    "role": "user",
    "content": [{
        "type": "tool_search_tool_result",
        "tool_use_id": "toolu_01ABC123",
        "content": {
            "type": "tool_search_tool_search_result",
            "tool_references": [{
                "type": "tool_reference",
                "tool_name": "get_weather"
            }]
        }
    }]
}

Claude的后续行动（使用发现的工具）

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I found the forecast tool. Let me get the weather forecast for Seattle."
        },
        {
            "type": "tool_use",
            "id": "toolu_01DEF456",
            "name": "get_weather",
            "input": {
                "location": "Seattle, WA"
            }
        }
    ],
    "stop_reason": "tool_use"
}

工具使用示例（测试版）

Claude Opus4.5 在工具定义中支持用户提供的示例，以提高Claude工具使用性能。您可以提供完整函数调用的示例，其格式与实际 LLM 输出完全相同，无需转换为另一种格式。要使用此功能，您必须通过测试版标题tool-examples-2025-10-29。

工具定义示例：

{
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit"
            }
        },
        "required": ["location"]
    },
    "input_examples": [{
            "location": "San Francisco, CA",
            "unit": "fahrenheit"
        },
        {
            "location": "Tokyo, Japan",
            "unit": "celsius"
        },
        {
            "location": "New York, NY"
        }
    ]
}

错误示例：

// Invalid: Example doesn't match schema (missing required field)
{
    "type": "invalid_request_error",
    "message": "Tool 'get_weather' input_examples[0] is invalid: Missing required property 'location'"
}

// Invalid: Example has wrong type for field
{
    "type": "invalid_request_error",
    "message": "Tool 'search_products' input_examples[1] is invalid: Property 'filters.price_range.min' must be a number, got string"
}

// Invalid: input_examples on server-side tool
{
    "type": "invalid_request_error",
    "message": "input_examples is not supported for server-side tool"
}