工具使用

使用 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。

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

Claude Sonnet 4.5 支持一项新的测试版功能，当您接近词元上限时，该功能会自动清除旧的工具使用结果，从而在多回合工具使用场景中实现更高效的上下文管理。要使用工具使用清理功能，您需要在 anthropic_beta 请求参数的测试版标头列表中添加 context-management-2025-06-27。此外，您还需要指定使用 clear_tool_uses_20250919 并从下列配置选项中进行选择。

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

在将 Claude Sonnet 4.5 与自动工具调用清理功能结合使用时，响应将包含其他上下文管理信息：

{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    ...
    "usage": {...},
    "context_management": {
        "applied_edits": [
            {
                "type": "clear_tool_uses_20250919",
                "cleared_tool_uses": 8,  # Number of tool use/result pairs that were cleared
                "cleared_input_tokens": 50000  # Total number of input tokens removed from the prompt
            }
        ]
    }
}

记忆工具（测试版）

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