読み込み中

ツール使用レスポンスの処理

レッスン 247 分
読み込み中

Claudeがツールを使用することを決定すると、慎重な処理が必要な特別なレスポンス構造を返します。このレスポンス形式を理解し、適切な会話管理を実装することは、堅牢なツール対応アプリケーションを構築する上で極めて重要です。

ツール選択の設定

レスポンスについて詳しく見る前に、Claudeがツールを使用するタイミングを制御する方法を理解しておく価値があります。toolChoiceパラメータには3つのオプションがあります。

JSONで記述された3つのtoolChoice設定、「auto」「any」「name付きのtool」と、それぞれに対応する下記の動作。

  • auto - Claudeがツールを使用するかどうかを決定します(デフォルトの動作)
  • any - Claudeは必ずツールを使用しますが、どのツールを使うかは選択できます
  • specific tool - 名前で指定した特定のツールをClaudeに強制的に使用させます

3つ目のオプションは、Claudeが特定の関数を確実に呼び出すようにしたいテストの際に特に便利です。

複数パートのメッセージ構造

Claudeがツールを使用したい場合、単なるテキストではなく、複数のコンテンツパートを含むアシスタントメッセージを返します。

アシスタントメッセージのコンテンツリスト:「Text」パートと、date_format %H:%M:%Sでget_current_datetimeを呼び出す「toolUse」パート。

このレスポンスには2つのパートが含まれます。

  • Text パート - 「現在時刻を調べるお手伝いができます。その情報を調べますね」のような人間が読める説明
  • ToolUse パート - どのツールをどの引数で実行するかを伝える構造化データ

ToolUse パートを理解する

ToolUseパートには3つの重要な情報が含まれています。

ツール「get_current_datetime」を指定し、入力date_format「%H:%M:%S」とtoolUseIdを含むToolUseパートの例。

  • toolUseId - ツール結果を返送する際に必要となる一意の識別子
  • name - ClaudeがJSONスキーマから呼び出そうとしている正確なツール名
  • input - Claudeがツール関数に渡したい引数の辞書

ツールを使った会話フロー

ツールの使用は、完全なメッセージ履歴の維持を必要とする特定の会話パターンに従います。

私たちのサーバーはClaudeに履歴全体を送信します:ユーザーの「今何時ですか?」、アシスタントのテキストと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)

また、テキストとパートの完全なリストの両方を返すように、chat関数も更新するとよいでしょう。

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

停止理由(Stop Reason)の確認

Claudeのレスポンスには、トップレベルのstopReasonフィールドも含まれています。この値が"tool_use"に等しい場合、Claudeは単にテキストレスポンスを返すのではなく、ツールを呼び出したいと考えています。これが、ツール情報を抽出して要求された関数を実行すべきだという合図になります。上記のchat()ヘルパーはまだこのフィールドを公開していないため、現時点では、返されたパートのリストにtoolUseキーを持つエントリがあるかどうかを確認することでツール使用を検出できます。後のレッスンで、chat()がstopReasonを直接返すように拡張します。

これらのパターンを整えておけば、Claudeのツール使用リクエストを処理し、マルチターンのツールインタラクション全体で適切な会話フローを維持する準備が整います。