舊版工具使用
此工具使用格式已過時
我們強烈建議您儘快切換到我們改進的工具使用結構,它更可靠,並能實現更高質量的性能,特別是對於更複雜的工具使用任務。
此工具使用格式未針對 Claude 3 進行優化,可能會導致比我們更新的工具使用格式更差的性能。
舊版工具使用的工作原理
使用舊版工具使用時,函數是在提示本身中定義的。當您向 Claude 提供它可以使用的工具和函數的描述時,Claude 能夠智能地決定何時以及如何使用這些工具來幫助回答問題和完成任務。
例如,假設您在提示中為 Claude 提供了一個名為 get_weather(location)
的函數,該函數可檢索給定位置的當前天氣。如果用戶隨後詢問”倫敦現在的天氣如何?“,Claude 將認識到它可以使用您提供的 get_weather
函數來查找答案。
在幕後,這是一個多步驟的過程:
- 函數定義和用戶問題都在單個提示中傳遞給 Claude
- Claude 不僅需要工具及其描述才能成功決定是否使用工具,而且可能還需要伴隨的示例,說明在哪些情況下應該使用此類工具,具體取決於用例和工具的複雜性。
- Claude 評估用戶的問題,並決定要調用哪些函數以及使用哪些參數
- Claude 構造格式正確的函數調用
- 函數調用通過客戶端代碼使用清晰的
stop_sequence
進行攔截,實際函數在客戶端執行 - 函數結果傳回給 Claude
- Claude 使用函數結果來制定對用戶的最終響應
這種技術允許 Claude 利用外部知識和能力,同時仍然保持對話界面。
定義函數
通過向 Claude 提供包裹在 XML 標籤中的函數描述來定義函數。描述應包括:
- 函數名稱
- 函數功能的純文本說明
- 預期的參數、它們的類型和描述
- 返回值和類型
- 可能引發的任何異常
以下是函數定義的示例:
<tool_description>
<tool_name>get_weather</tool_name>
<description>
檢索指定位置的當前天氣。
返回一個包含兩個字段的字典:
- temperature:float,當前溫度(華氏度)
- conditions:string,當前天氣狀況的簡要描述
如果找不到提供的位置,則引發 ValueError。
</description>
<parameters>
<parameter>
<name>location</name>
<type>string</type>
<description>城市和州,例如 San Francisco, CA</description>
</parameter>
</parameters>
</tool_description>
編寫良好的函數描述的一些提示:
- 要清晰簡潔,但要提供足夠的細節,以便 Claude 理解何時應該使用該函數
- 指定參數和返回值的類型
- 提及可能引發的任何相關異常
- 使用純文本描述,而不是代碼語法
舊版工具使用格式
為了讓 Claude 調用函數,它必須輸出非常特定格式的 XML 塊。格式如下所示:
<function_calls>
<invoke>
<tool_name>function_name</tool_name>
<parameters>
<param1>value1</param1>
<param2>value2</param2>
</parameters>
</invoke>
</function_calls>
如果 Claude 同時調用多個函數,<function_calls>
塊可以包含多個 <invoke>
塊。每個 <invoke>
包含被調用函數的名稱和傳入的參數。
您應該將
</function_calls>
作為stop_sequence
傳遞到您的 API 調用中,以確保 Claude 在調用函數後停止生成文本。
在 <function_calls>
塊之後,並假設您有適當的停止序列,Claude 將停止生成並等待函數結果在 <function_results>
塊中傳回,如下所示:
<function_results>
<result>
<tool_name>function_name</tool_name>
<stdout>
function result goes here
</stdout>
</result>
</function_results>
函數結果應放在 <stdout>
標籤內。如果函數引發異常,應返回如下內容:
<function_results>
<error>
error message goes here
</error>
</function_results>
完整的函數結果應作為繼續之前對話的消息傳回給 Claude。收到函數結果後,Claude 將繼續生成以將結果合併到其響應中。
舊版工具使用提示示例
以下是一個完整的提示示例,它為 Claude 提供了兩個函數和一個需要使用它們的問題:
Content | |
---|---|
System | 在此環境中,您可以訪問一組可用於回答用戶問題的工具。 您可以像這樣調用它們: <function_calls> <invoke> <tool_name>$TOOL_NAME</tool_name> <parameters> <$PARAMETER_NAME>$PARAMETER_VALUE</$PARAMETER_NAME> … </parameters> </invoke> </function_calls> 以下是可用的工具: <tools> <tool_description> <tool_name>get_current_stock_price </tool_name><description>獲取公司的當前股價。返回 float:當前股價。 引發 ValueError:如果輸入的股票代碼無效/未知。</description> <parameters> <parameter> <name>symbol</name> <type>string</type> <description>要獲取價格的公司的股票代碼。</description> </parameter> </parameters> </tool_description> <tool_description> <tool_name>get_ticker_symbol</tool_name> <description>通過公司名稱搜索獲取其股票代碼。返回 str:公司股票的股票代碼。如果未找到匹配的股票代碼,則引發 TickerNotFound。 </description> <parameters> <parameter> <name>company_name</name> <type>string</type> <description>公司名稱。</description> </parameter> </parameters> </tool_description></tools> |
User | General Motors 目前的股價是多少? |
以下是 Claude 的響應方式:
Content | |
---|---|
Assistant | <scratchpad> 要回答這個問題,我需要: 1. 使用 get_ticker_symbol() 函數獲取 General Motors 的股票代碼。 2. 使用返回的股票代碼通過 get_current_stock_price() 函數獲取當前股價。</scratchpad> <function_calls> <invoke> <tool_name>get_ticker_symbol</tool_name> <parameters> <company_name>General Motors</company_name> </parameters> </invoke> </function_calls> |
Claude 首先調用 get_ticker_symbol
來檢索 General Motors 的股票代碼。我們可以通過 </function calls>
停止序列識別出 Claude 想要調用函數。我們從相關 XML 標籤之間提取相關數據,並代表 Claude 運行函數。然後我們將結果在 <function_results>
標籤中傳回給 Claude。
Content | |
---|---|
User | <function_results> <result> <tool_name>get_ticker_symbol</tool_name> <stdout> GM </stdout> </result> </function_results> |
現在它知道了股票代碼,Claude 隨後將決定它必須調用 get_current_stock_price
並獲取當前價格。
Content | |
---|---|
Assistant | <function_calls> <invoke> <tool_name>get_current_stock_price</tool_name> <parameters> <symbol>GM</symbol> </parameters> </invoke> </function_calls> |
我們也將這些結果傳回。
Content | |
---|---|
User | <function_results> <result> <tool_name>get_current_stock_price</tool_name> <stdout> 38.50 </stdout> </result> </function_results> |
通過這整個對話鏈為 Claude 提供它需要的所有細節,Claude 將能夠向用戶提供答案作為其最終輸出。
Content |
---|
<answer> General Motors 目前的股價為 $38.50。 </answer> |
舊版工具使用常見問題
在給定的交互中,我可以向 Claude 傳遞多少個工具?
您可以定義任意數量的工具和函數供 Claude 使用,儘管我們目前建議對於這種舊版工具使用結構,您不要超過 3-5 個,具體取決於您的用例和相關函數的複雜性。
Claude 是否有任何它知道的內置工具?
沒有。您希望 Claude 使用的任何工具,您都必須在工具使用提示中自行定義。Claude 沒有預定義的最佳工作的函數和定義列表。
新的工具使用格式何時會出現在 Vertex AI 或 Amazon Bedrock 上?
在不久的將來!