使用 Claude 進行工具使用

「Tool use」（工具使用）讓 Claude 能夠呼叫您定義的或 Anthropic 提供的函式。Claude 會根據使用者的請求和工具的描述來決定何時呼叫工具。然後它會回傳一個結構化的呼叫，由您的應用程式執行（用戶端工具）或由 Anthropic 執行（伺服器工具）。

以下是使用伺服器工具的最小範例，即 Web 搜尋工具，由 Anthropic 為您執行：

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

Claude 在 Anthropic 的基礎設施上執行搜尋，並在同一個回應中回傳附有引用的結果。若要讓 Claude 呼叫您定義的函式，請傳入一個帶有 input_schema 的工具，然後在 Claude 回傳 tool_use 區塊時執行該呼叫。工具使用的運作方式展示了完整的往返流程。深入了解定義工具和處理工具呼叫。



工具使用的運作方式

工具的主要差異在於程式碼執行的位置。用戶端工具（包括使用者定義的工具和具有 Anthropic 定義結構描述的工具，例如 bash 和 text_editor）在您的應用程式中執行。Claude 會以 stop_reason: "tool_use" 和一個或多個 tool_use 區塊回應。您的程式碼執行該操作並回傳 tool_result。伺服器工具（例如 web_search、web_fetch、code_execution 和 tool_search）在 Anthropic 的基礎設施上執行：您可以直接看到結果而無需處理執行，除非 Claude 在同一組平行工具呼叫中同時呼叫該工具和您的某個用戶端工具（請參閱停止原因和後備方案）。

以下是用戶端工具的完整往返流程。第一個請求定義了一個 get_weather 工具，Claude 透過呼叫它來回答問題：回應帶有一個 tool_use 區塊，您的程式碼執行查詢，然後第二個請求在 tool_result 區塊中將結果傳回，讓 Claude 可以回覆答案。

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude 會以 tool_use 區塊回覆，指明工具名稱及其引數。
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    # 要求每回合最多只呼叫一次工具。
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# 執行工具，然後將結果放在 tool_result 區塊中回傳。
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude 會使用該結果來回答原始問題。
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

處理工具呼叫詳細涵蓋了每個步驟，包括結果格式化和錯誤信號；平行工具使用涵蓋了一次呼叫多個工具的回應。若要省去自己撰寫這個往返流程，請使用 Tool Runner：SDK 會執行您的工具並自動將結果傳回。

有關完整的概念模型，包括代理迴圈以及何時選擇每種方法，請參閱工具使用的運作方式。

若要連接到 Model Context Protocol（MCP）伺服器，請參閱 MCP 連接器。若要建構您自己的 MCP 用戶端，請參閱 Model Context Protocol 的建構 MCP 用戶端指南。



Claude 何時使用工具

使用預設的 tool_choice 值 {"type": "auto"} 時，Claude 會在每個回合決定是呼叫工具還是直接回應。當請求對應到該工具所描述的能力，且答案尚未存在於上下文中時，它會呼叫工具。對於穩定的知識、創意任務和對話回合，它會直接回應。

這個界線可以透過您的系統提示來引導。如果 Claude 沒有在您預期的時候呼叫工具，一個輕量的指示，例如 "Use the tools to investigate before responding."，可以增加工具使用。更強的形式，例如 "Always call a tool first before responding."，會進一步推動。相反地，"Use your judgment about whether to call a tool or respond directly." 會讓觸發行為保持保守。

若要強制要求工具呼叫而不是依賴提示，請設定 tool_choice。

每個伺服器工具的頁面都更詳細地描述了其自身的觸發界線。



選擇工具

有關 type 字串、版本和 beta 標頭，請參閱工具參考。



您自己的工具

對於您定義的工具，您撰寫結構描述，並由您的應用程式執行每個呼叫。



Anthropic 結構描述的用戶端工具

Anthropic 發布結構描述並以此訓練 Claude。您的應用程式仍然執行每個呼叫並回傳 tool_result。



伺服器工具

伺服器工具在 Anthropic 的基礎設施上執行，您的應用程式中不需要處理程式碼。請參閱伺服器工具以了解它們共有的機制。



定價

工具使用請求的計費基於：

1. 傳送給模型的輸入 token 總數（包括 tools 參數中的內容）
2. 生成的輸出 token 數量
3. 對於伺服器端工具，還有額外的基於使用量的計費（例如，網路搜尋按每次執行的搜尋收費）

客戶端工具的計費方式與任何其他 Claude API 請求相同，而伺服器端工具可能會根據其特定使用情況產生額外費用。

工具使用產生的額外 token 來自：

• API 請求中的 tools 參數（工具名稱、描述和結構描述）
• API 請求和回應中的 tool_use 內容區塊
• API 請求中的 tool_result 內容區塊

當您使用 tools 時，API 也會自動為模型包含一個特殊的系統提示以啟用工具使用。每個模型所需的工具使用 token 數量列於下方（不包括上述的額外 token）。請注意，該表格假設至少提供了 1 個工具。如果未提供任何 tools，則工具選擇為 none 時使用 0 個額外的系統提示 token。

這些 token 數量會加到您的正常輸入和輸出 token 中，以計算請求的總成本。

請參閱模型概覽表格以了解目前各模型的價格。

當您傳送工具使用提示時，與任何其他 API 請求一樣，回應會在回報的 usage 指標中包含輸入和輸出 token 數量。

某些伺服器工具會在 token 之外增加基於使用量的費用：請參閱 Web 搜尋工具和程式碼執行工具以了解其費率。



後續步驟