載入中
載入中

當 Claude 決定使用工具時,它會返回一個特殊的回應結構,需要謹慎處理。理解這種回應格式並實作適當的對話管理,對於建構強健的工具啟用應用程式至關重要。

工具選擇設定

在深入探討回應之前,值得先了解如何控制 Claude 使用工具的時機。toolChoice 參數提供您三種選項:

三個以 JSON 形式撰寫的 toolChoice 設定,「auto」、「any」和帶有名稱的「tool」,並搭配下方列出的行為。

  • auto - Claude 自行決定是否使用工具(預設行為)
  • any - Claude 必須使用工具,但可以選擇使用哪一個
  • specific tool - 強制 Claude 依名稱使用特定工具

第三個選項在您想確保 Claude 呼叫特定函式時進行測試特別有用。

多部分訊息結構

當 Claude 想要使用工具時,它會返回一個包含多個內容部分的助理訊息,而不只是純文字:

助理訊息內容清單:一個「Text」部分和一個呼叫 get_current_datetime(date_format 為 %H:%M:%S)的「toolUse」部分。

此回應包含兩個部分:

  • 文字部分 - 人類可讀的說明,例如「我可以幫您查看目前的時間。讓我為您找出這項資訊」
  • ToolUse 部分 - 告訴您要執行哪個工具以及使用什麼參數的結構化資料

理解 ToolUse 部分

ToolUse 部分包含三項關鍵資訊:

範例 ToolUse 部分,指定工具名稱為「get_current_datetime」,輸入 date_format 為「%H:%M:%S」,另外還有一個 toolUseId。

  • toolUseId - 一個唯一識別碼,您在傳回工具結果時會需要用到
  • name - 來自您 JSON schema 的確切工具名稱,這是 Claude 想要呼叫的工具
  • input - Claude 想要傳遞給您工具函式的參數字典

使用工具的對話流程

工具使用遵循一種特定的對話模式,需要維護完整的訊息歷史記錄:

我們的伺服器將整個歷史記錄傳送給 Claude:使用者「What time is it?」、助理的文字與 ToolUse 部分、使用者的 ToolResult 部分。

當您收到工具使用請求時,您需要:

  1. 從 ToolUse 部分擷取工具資訊
  2. 執行您實際的工具函式
  3. 連同完整的對話歷史記錄一起傳回一則 ToolResult 訊息
  4. 在您的下一個請求中包含原始使用者訊息以及助理的工具使用訊息

更新輔助函式

為了正確處理多部分訊息,您需要更新您的訊息處理函式。以下說明如何讓您的函式足夠靈活,以同時處理簡單文字和複雜的多部分內容:

python
def add_user_message(messages, content):
    if isinstance(content, str):
        user_message = {"role": "user", "content": [{"text": content}]}
    else:
        user_message = {"role": "user", "content": content}
    messages.append(user_message)

def add_assistant_message(messages, content):
    if isinstance(content, str):
        assistant_message = {"role": "assistant", "content": [{"text": content}]}
    else:
        assistant_message = {"role": "assistant", "content": content}
    messages.append(assistant_message)

您也會想要更新您的聊天函式,讓它同時返回文字和完整的部分清單:

python
def chat(messages, system=None, temperature=1.0, stop_sequences=[], tools=None):
    # ……現有的設定程式碼……
    
    response = client.converse(**params)
    
    text = response["output"]["message"]["content"][0]["text"]
    parts = response["output"]["message"]["content"]
    
    return text, parts

檢查停止原因

Claude 的回應也包含一個頂層的 stopReason 欄位。當它等於 "tool_use" 時,表示 Claude 想要呼叫工具,而不僅僅是提供文字回應——這就是您應該擷取工具資訊並執行所請求函式的訊號。上方的 chat() 輔助函式目前還沒有公開此欄位,因此目前您可以透過檢查返回的部分清單中是否有包含 toolUse 鍵的項目,來偵測工具使用情況。您將在稍後的課程中擴充 chat(),使其直接返回 stopReason。

有了這些模式之後,您就已準備好處理 Claude 的工具使用請求,並在多輪工具互動過程中維持適當的對話流程。