工具使用(函數呼叫)
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 可以使用的工具。
電腦使用(測試版)功能是一個例外 - 它引入了由 Anthropic 提供但由您(用戶)實現的工具。
如何實現工具使用
選擇模型
通常,對於複雜的工具和模糊的查詢,使用 Claude 3.5 Sonnet 或 Claude 3 Opus;它們能更好地處理多個工具並在需要時尋求澄清。
對於簡單的工具,使用 Claude 3.5 Haiku 或 Claude 3 Haiku,但請注意它們可能會推斷缺失的參數。
指定工具
工具在 API 請求的頂層 tools
參數中指定。每個工具定義包括:
參數 | 描述 |
---|---|
name | 工具的名稱。必須符合正則表達式 ^[a-zA-Z0-9_-]{1,64}$ 。 |
description | 詳細的純文本描述,說明工具的功能、何時應使用以及其行為方式。 |
input_schema | 一個 JSON Schema 物件,定義工具的預期參數。 |
工具使用系統提示
當您使用 tools
參數呼叫 Anthropic API 時,我們會從工具定義、工具配置和任何用戶指定的系統提示構建一個特殊的系統提示。構建的提示旨在指導模型使用指定的工具並提供工具正常運作所需的必要上下文:
工具定義的最佳實踐
要在使用工具時獲得最佳性能,請遵循以下準則:
- 提供極其詳細的描述。 這是影響工具性能最重要的因素。您的描述應該解釋工具的每個細節,包括:
- 工具的功能
- 何時應該使用(以及何時不應該使用)
- 每個參數的含義及其如何影響工具的行為
- 任何重要的注意事項或限制,例如如果工具名稱不清楚,工具不會返回什麼信息。您能為 Claude 提供的關於工具的上下文越多,它就越能更好地決定何時以及如何使用它們。每個工具描述至少應該有 3-4 個句子,如果工具複雜,則需要更多。
- 優先考慮描述而不是示例。 雖然您可以在工具的描述或附帶的提示中包含如何使用工具的示例,但這不如對工具的目的和參數有清晰和全面的解釋重要。只有在您完全充實了描述之後才添加示例。
良好的描述清楚地解釋了工具的功能、何時使用、返回什麼數據以及 ticker
參數的含義。糟糕的描述太過簡短,讓 Claude 對工具的行為和用法產生許多疑問。
控制 Claude 的輸出
強制使用工具
在某些情況下,您可能希望 Claude 使用特定工具來回答用戶的問題,即使 Claude 認為不使用工具也能提供答案。您可以通過在 tool_choice
字段中指定工具來實現這一點:
在使用 tool_choice 參數時,我們有三種可能的選項:
auto
允許 Claude 決定是否呼叫任何提供的工具。這是預設值。any
告訴 Claude 它必須使用提供的工具之一,但不強制使用特定工具。tool
允許我們強制 Claude 始終使用特定工具。
此圖說明了每個選項的工作方式:
請注意,當您將 tool_choice
設置為 any
或 tool
時,我們會預填助手訊息以強制使用工具。這意味著即使明確要求,模型也不會在 tool_use
內容區塊之前發出鏈式思考 text
內容區塊。
我們的測試表明,這不應該降低性能。如果您想在請求模型使用特定工具的同時保持鏈式思考(特別是使用 Opus),您可以將 tool_choice
設置為 {"type": "auto"}
(預設值),並在 user
訊息中添加明確的指示。例如:倫敦的天氣如何?在您的回應中使用 get_weather 工具。
JSON 輸出
工具不一定需要是客戶端函數 — 只要您希望模型返回遵循提供的架構的 JSON 輸出,就可以使用工具。例如,您可以使用具有特定架構的 record_summary
工具。請參閱工具使用示例以獲取完整的工作示例。
思維鏈
在使用工具時,Claude 通常會顯示其「思維鏈」,即它用來分解問題並決定使用哪些工具的逐步推理。如果 tool_choice
設置為 auto
(這是預設值,請參閱強制使用工具),Claude 3 Opus 模型會這樣做,而 Sonnet 和 Haiku 可以通過提示來實現這一點。
例如,對於提示「舊金山現在的天氣如何,那裡現在是幾點?」,Claude 可能會回應:
這個思維鏈讓我們了解 Claude 的推理過程,並可以幫助您調試意外行為。
對於 Claude 3 Sonnet 模型,思維鏈在預設情況下較少出現,但您可以通過在用戶訊息或系統提示中添加類似「在回答之前,請在標籤中逐步解釋您的推理。」的內容來提示 Claude 顯示其推理。
重要的是要注意,雖然 <thinking>
標籤是 Claude 用來表示其思維鏈的常見約定,但確切的格式(例如這個 XML 標籤的名稱)可能會隨時間而改變。您的代碼應該將思維鏈視為任何其他助手生成的文本,而不應依賴 <thinking>
標籤的存在或特定格式。
禁用並行工具使用
預設情況下,Claude 可能會使用多個工具來回答用戶查詢。您可以通過在 tool_choice
字段中設置 disable_parallel_tool_use=true
來禁用此行為。
- 當
tool_choice
類型為auto
時,這確保 Claude 最多使用一個工具 - 當
tool_choice
類型為any
或tool
時,這確保 Claude 恰好使用一個工具
處理工具使用和工具結果內容區塊
當 Claude 決定使用您提供的工具之一時,它會返回一個 stop_reason
為 tool_use
的回應,以及 API 回應中的一個或多個 tool_use
內容區塊,包括:
id
:此特定工具使用區塊的唯一標識符。這將用於稍後匹配工具結果。name
:正在使用的工具的名稱。input
:包含傳遞給工具的輸入的物件,符合工具的input_schema
。
當您收到工具使用回應時,您應該:
- 從
tool_use
區塊中提取name
、id
和input
。 - 在您的代碼庫中運行與該工具名稱對應的實際工具,傳入工具
input
。 - [可選] 通過發送一個
role
為user
的新訊息繼續對話,並包含一個包含以下信息的tool_result
類型的content
區塊:tool_use_id
:這是結果對應的工具使用請求的id
。content
:工具的結果,可以是字串(例如"content": "15 度"
)或嵌套內容區塊的列表(例如"content": [{"type": "text", "text": "15 度"}]
)。這些內容區塊可以使用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 (Oct) | auto any , tool | 346 令牌 313 令牌 |
Claude 3 Opus | auto any , tool | 530 令牌 281 令牌 |
Claude 3 Sonnet | auto any , tool | 159 令牌 235 令牌 |
Claude 3 Haiku | auto any , tool | 264 令牌 340 令牌 |
Claude 3.5 Sonnet (June) | auto any , tool | 294 令牌 261 令牌 |
這些令牌數量會加到您的正常輸入和輸出令牌中,以計算請求的總成本。請參閱我們的模型概覽表以了解當前每個模型的價格。
當您發送工具使用提示時,就像任何其他 API 請求一樣,回應將輸出輸入和輸出令牌數量作為報告的 usage
指標的一部分。
下一步
探索我們存儲庫中現成可實現的工具使用代碼示例:
Was this page helpful?