工具使用(函數呼叫)
Claude 能夠與外部客戶端工具和函數互動,讓您可以為 Claude 配備自己的自定義工具來執行更廣泛的任務。
以下是使用 Messages API 向 Claude 提供工具的示例:
工具使用的工作原理
通過以下步驟將外部工具與 Claude 整合:
向 Claude 提供工具和用戶提示
- 在 API 請求中定義具有名稱、描述和輸入模式的工具。
- 包含可能需要這些工具的用戶提示,例如”舊金山的天氣如何?”
Claude 決定使用工具
- Claude 評估是否有任何工具可以幫助回答用戶的查詢。
- 如果是,Claude 構建一個格式正確的工具使用請求。
- API 響應的
stop_reason
為tool_use
,表示 Claude 的意圖。
提取工具輸入、運行代碼並返回結果
- 在您的端,從 Claude 的請求中提取工具名稱和輸入。
- 在客戶端執行實際的工具代碼。
- 繼續對話,發送一條包含
tool_result
內容塊的新user
消息。
Claude 使用工具結果制定回應
- Claude 分析工具結果,為原始用戶提示製作最終回應。
注意:步驟 3 和 4 是可選的。對於某些工作流程,Claude 的工具使用請求(步驟 2)可能就是您所需要的全部,無需將結果發送回 Claude。
所有工具都由用戶提供
需要注意的是,Claude 沒有訪問任何內置的服務器端工具。所有工具都必須由您(用戶)在每個 API 請求中明確提供。這使您可以完全控制和靈活地決定 Claude 可以使用的工具。
如何實現工具使用
選擇模型
通常,對於複雜的工具和模糊的查詢,使用 Claude 3 Opus;它能更好地處理多個工具,並在需要時尋求澄清。
對於簡單的工具使用 Haiku,但請注意它可能會推斷缺失的參數。
指定工具
工具在 API 請求的頂層 tools
參數中指定。每個工具定義包括:
參數 | 描述 |
---|---|
name | 工具的名稱。必須匹配正則表達式 ^[a-zA-Z0-9_-]{1,64}$ 。 |
description | 詳細的純文本描述,說明工具的功能、何時應該使用以及其行為方式。 |
input_schema | 一個 JSON Schema 對象,定義工具的預期參數。 |
工具定義的最佳實踐
要在使用工具時獲得 Claude 的最佳性能,請遵循以下指南:
- 提供極其詳細的描述。 這是影響工具性能的最重要因素。您的描述應該解釋工具的每個細節,包括:
- 工具的功能
- 何時應該使用(以及何時不應該使用)
- 每個參數的含義及其如何影響工具的行為
- 任何重要的注意事項或限制,例如如果工具名稱不清楚,該工具不返回哪些信息。您能為 Claude 提供的關於工具的上下文越多,它就越能更好地決定何時以及如何使用它們。每個工具描述至少應該有 3-4 句話,如果工具複雜,則需要更多。
- 優先考慮描述而非示例。 雖然您可以在工具的描述或附帶的提示中包含如何使用工具的示例,但這不如對工具的目的和參數有清晰全面的解釋重要。只有在充分闡述描述後才添加示例。
良好的描述清楚地解釋了工具的功能、何時使用、返回什麼數據以及 ticker
參數的含義。糟糕的描述過於簡短,讓 Claude 對工具的行為和用法產生了許多疑問。
控制 Claude 的輸出
強制使用工具
在某些情況下,您可能希望 Claude 使用特定的工具來回答用戶的問題,即使 Claude 認為它可以在不使用工具的情況下提供答案。您可以通過在 tool_choice
字段中指定工具來實現這一點,如下所示:
tool_choice = {"type": "tool", "name": "get_weather"}
在使用 tool_choice 參數時,我們有三種可能的選項:
auto
允許 Claude 決定是否調用任何提供的工具。這是默認值。any
告訴 Claude 它必須使用提供的工具之一,但不強制使用特定工具。tool
允許我們強制 Claude 始終使用特定工具。
這張圖說明了每個選項的工作原理:
請注意,當您將 tool_choice
設置為 any
或 tool
時,我們會預填助手消息以強制使用工具。這意味著即使明確要求,模型也不會在 tool_use
內容塊之前發出鏈式思考的 text
內容塊。
我們的測試表明,這不應該降低性能。如果您希望保持鏈式思考(特別是使用 Opus)的同時仍要求模型使用特定工具,您可以將 tool_choice
設置為 {"type": "auto"}
(默認值),並在 user
消息中添加明確的指示。例如:What's the weather like in London? Use the get_weather tool in your response.
JSON 輸出
工具不一定需要是客戶端函數 — 只要您希望模型返回遵循提供的模式的 JSON 輸出,就可以使用工具。例如,您可以使用具有特定模式的 record_summary
工具。請參閱工具使用示例以獲取完整的工作示例。
思維鏈
在使用工具時,Claude 通常會展示其”思維鏈”,即用於分解問題和決定使用哪些工具的逐步推理。如果 tool_choice
設置為 auto
(這是默認值,請參閱強制使用工具),Claude 3 Opus 模型會這樣做,而 Sonnet 和 Haiku 可以被提示這樣做。
例如,給定提示 “What’s the weather like in San Francisco right now, and what time is it there?“,Claude 可能會回應:
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": {"location": "San Francisco, CA"}
}
]
}
這種思維鏈讓我們洞察 Claude 的推理過程,可以幫助您調試意外行為。
對於 Claude 3 Sonnet 模型,默認情況下思維鏈不太常見,但您可以通過在用戶消息或系統提示中添加類似 "Before answering, explain your reasoning step-by-step in tags."
的內容來提示 Claude 展示其推理過程。
重要的是要注意,雖然 <thinking>
標籤是 Claude 用來表示其思維鏈的常見約定,但確切的格式(例如這個 XML 標籤的名稱)可能會隨時間而改變。您的代碼應該將思維鏈視為任何其他助手生成的文本,而不應依賴 <thinking>
標籤的存在或特定格式。
處理工具使用和工具結果內容塊
當 Claude 決定使用您提供的工具之一時,它會返回一個 stop_reason
為 tool_use
的響應,並在 API 響應中包含一個或多個 tool_use
內容塊,其中包括:
id
: 這個特定工具使用塊的唯一標識符。這將用於稍後匹配工具結果。name
: 正在使用的工具的名稱。input
: 一個包含傳遞給工具的輸入的對象,符合工具的input_schema
。
當您收到工具使用響應時,您應該:
- 從
tool_use
塊中提取name
、id
和input
。 - 在您的代碼庫中運行與該工具名稱對應的實際工具,傳入工具
input
。 - [可選] 通過發送一條新的
role
為user
的消息繼續對話,並包含一個content
塊,其中包含tool_result
類型和以下信息:tool_use_id
: 這是結果對應的工具使用請求的id
。content
: 工具的結果,可以是字符串(例如"content": "15 degrees"
)或嵌套內容塊的列表(例如"content": [{"type": "text", "text": "15 degrees"}]
)。這些內容塊可以使用text
或image
類型。is_error
(可選): 如果工具執行導致錯誤,則設置為true
。
在收到工具結果後,Claude 將使用該信息繼續生成對原始用戶提示的回應。
與其他 API 的區別
與將工具使用分開或使用特殊角色如 tool
或 function
的 API 不同,Anthropic 的 API 將工具直接整合到 user
和 assistant
消息結構中。
消息包含 text
、image
、tool_use
和 tool_result
塊的數組。user
消息包括客戶端內容和 tool_result
,而 assistant
消息包含 AI 生成的內容和 tool_use
。
錯誤排除
在使用 Claude 的工具時,可能會出現幾種不同類型的錯誤:
工具使用示例
以下是一些代碼示例,展示了各種工具使用模式和技巧。為了簡潔起見,這些工具都是簡單的工具,工具描述也比理想情況下短,以確保最佳性能。
定價
工具使用請求的定價與任何其他 Claude API 請求相同,基於發送給模型的總輸入令牌數(包括 tools
參數中的令牌)和生成的輸出令牌數。
工具使用帶來的額外令牌來自:
- API 請求中的
tools
參數(工具名稱、描述和模式) - API 請求和響應中的
tool_use
內容塊 - API 請求中的
tool_result
內容塊
當您使用 tools
時,我們還會自動為模型包含一個特殊的系統提示,以啟用工具使用。每個模型所需的工具使用令牌數量如下所列(不包括上面列出的額外令牌):
模型 | 工具選擇 | 工具使用系統提示令牌數 |
---|---|---|
Claude 3.5 Sonnet | auto any , tool | 294 個令牌 261 個令牌 |
Claude 3 Opus | auto any , tool | 530 個令牌 281 個令牌 |
Claude 3 Sonnet | auto any , tool | 159 個令牌 235 個令牌 |
Claude 3 Haiku | auto any , tool | 264 個令牌 340 個令牌 |
這些令牌數會加到您的正常輸入和輸出令牌中,以計算請求的總成本。請參考我們的模型概覽表以獲取當前每個模型的價格。
當您發送工具使用提示時,就像任何其他 API 請求一樣,響應將輸出輸入和輸出令牌數作為報告的 usage
指標的一部分。
下一步
探索我們的工具使用代碼示例存儲庫,這些示例可以直接實施: