工具使用

使用 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"
}

精細工具串流

精細工具串流是一種 Anthropic Claude 模型功能，可用於 Claude Sonnet 4.5、Claude Haiku 4.5、Claude Sonnet 4 和 Claude Opus 4。透過精細工具串流，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'

電腦使用 (Beta 版)

電腦使用是 Claude 3.5 Sonnet v2、Claude Sonnet 4.5、Claude Haiku 4.5、Claude 3.7 Sonnet、Claude Sonnet 4 和 Claude Opus 4 提供的 Anthropic Claude 模型功能 (Beta 版)。在使用電腦時，Claude 可協助您透過基本的 GUI 動作自動化任務。

電腦使用 API 提供數個預先定義的電腦使用工具供您使用。然後，您可以使用請求建立提示，例如「傳送電子郵件給 Ben，其中包含上次會議的筆記」和螢幕擷取畫面 (必要時)。回應包含 JSON 格式的 tool_use 動作清單 (例如 scroll_down、left_button_press、螢幕擷取畫面)。程式碼會執行電腦動作，並向 Claude 提供顯示輸出的螢幕擷取畫面 (當要求時)。

自 Claude 3.5 v2 發行以來，工具參數已更新為接受多型工具類型；已新增 tool.type 屬性來區分它們。type 是選用的；如果忽略，則假設工具是自訂工具 (先前支援的唯一工具類型)。若要存取電腦使用，您必須使用 anthropic_beta 參數搭配對應的列舉，其值取決於使用的模型版本。如需詳細資訊，請參閱下表。

只有使用此參數和列舉提出的請求才能使用電腦使用工具。其可以指定如下："anthropic_beta": ["computer-use-2025-01-24"]。

如需詳細資訊，請參閱 Anthropic 文件中的電腦使用 (Beta 版)。

以下是範例回應，假設請求包含具有 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 的工具。

自動工具呼叫清除 (Beta 版)

自動工具呼叫清除是 Anthropic Claude 模型功能 （測試版）。使用此功能時，Claude 可以在接近字符限制時自動清除舊工具使用結果，以便在多迴轉工具使用案例中實現更有效率的內容管理。若要使用工具使用清除，您需要將 context-management-2025-06-27 新增至 anthropic_beta 請求參數上的 Beta 標頭清單。您還需要指定 的使用clear_tool_uses_20250919，並從下列組態選項中選擇。

這些是 clear_tool_uses_20250919 內容管理策略的可用控制項。全部皆為選用或具有預設值：

記憶體工具 (Beta 版)

Claude Sonnet 4.5 包含新的記憶體工具，可為客戶提供跨對話管理記憶體的方法。透過此功能，客戶可以透過提供本機目錄的存取權，允許 Claude 擷取內容視窗外的資訊。這將作為 Beta 版功能提供。若要使用此功能，您必須使用 context-management-2025-06-27 Beta 版標頭。

工具定義：

{
  "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 模型會自動包含啟用工具使用的特殊系統提示。下表列出每個模型所需的工具使用字符數量。此資料表會排除先前所述的其他字符。請注意，此表格假設至少提供一個工具。如果未提供任何工具，則無工具選擇會使用 0 個額外的系統提示字符。

工具搜尋工具 (Beta 版）

工具搜尋工具允許 使用數百或甚至數千種工具Claude，而無需預先將其所有定義載入內容視窗。您可以用 標記所有工具，並僅透過工具搜尋機制Claude尋找和載入所需的工具defer_loading: true，而不是立即宣告所有工具。

若要存取此功能，您必須使用 Beta 版標頭 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區塊的工具來實作自訂工具搜尋工具 （例如，使用內嵌或語意搜尋）。這可讓複雜的工具探索機制超越 regex 比對。

使用自訂 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"
}

工具使用範例 (Beta 版）

Claude Opus 4.5 支援使用者在工具定義中提供的範例，以提高 Claude的工具使用效能。您可以提供完整函數呼叫的範例，格式與實際 LLM 輸出完全相同，而不需要翻譯成其他格式。若要使用此功能，您必須傳遞 Beta 版標頭 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"
}