載入中

處理工具使用回應

第 24 課7 分鐘

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

工具選擇設定

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

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

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

多部分訊息結構

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

該回應包含兩個部分:

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

理解 ToolUse 部分

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

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

工具的對話流程

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

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

  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):
    # ... existing setup code ...
    
    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 的工具使用請求,並在整個多輪工具互動過程中維持適當的對話流程。