Converse を使用してツールを呼び出す API

モデルがツールを使用してメッセージの応答を完了できるようにするには、メッセージと 1 つ以上のツールの定義をモデルに送信します。いずれかのツールがレスポンスの生成に役立つとモデルが判断した場合、ツールを使用してツールの結果をモデルに返すリクエストが返されます。次に、モデルは結果を使用して元のメッセージに対するレスポンスを生成します。

以下の手順は、 変換 でツールを使用する方法を示していますAPI。サンプルコードについては、「変換APIツールの使用例」を参照してください。

ステップ 1: メッセージとツール定義を送信する

メッセージとツールの定義を送信するには、Converse または ConverseStream (ストリーミングレスポンスの場合) オペレーションを使用します。

注記

Meta には、 でツールを使用するプロンプトを作成するための特定の推奨事項があります。Llama 3.1 (以降) モデル。詳細については、「」のJSON「ベースのツール呼び出し」を参照してください。Meta ドキュメント内) を参照してください。

ツールの定義は、 toolConfig (ToolConfiguration) リクエストパラメータを Converseオペレーションに渡すJSONスキーマです。スキーマの詳細については、JSON「スキーマ」を参照してください。以下は、ラジオステーションで最も人気のある曲を再生するツールのスキーマの例です。

{
    "tools": [
        {
            "toolSpec": {
                "name": "top_song",
                "description": "Get the most popular song played on a radio station.",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "properties": {
                            "sign": {
                                "type": "string",
                                "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
                            }
                        },
                        "required": [
                            "sign"
                        ]
                    }
                }
            }
        }
    ]
}

同じリクエストでは、 messages (メッセージ) リクエストパラメータでユーザーメッセージも渡します。

[
    {
        "role": "user",
        "content": [
            {
                "text": "What is the most popular song on WZPZ?"
            }
        ]
    }
]

を使用している場合 Anthropic Claude 3 モデルでは、toolConfigリクエストパラメータで toolChoice (ToolChoice) フィールドを指定することで、ツールの使用を強制できます。ツールの使用を強制することは、開発中にツールをテストするのに役立ちます。次の例は、top_song と呼ばれるツールを強制的に使用する方法を示しています。

{"tool" : {"name" : "top_song"}}

渡すことができる他のパラメータについては、「」を参照してくださいConverse APIオペレーションとの会話を実行する。

ステップ 2: モデルからツールリクエストを取得する

メッセージとツール定義を使用してConverseオペレーションを呼び出すと、モデルはツール定義を使用して、メッセージに応答するためにツールが必要かどうかを判断します。例えば、チャットアプリケーションユーザーが で一番人気のある曲のメッセージを送信した場合WZPZ、モデルはメッセージを top_song ツール定義のスキーマと照合し、ツールがレスポンスの生成に役立つと判断します。

モデルがレスポンスを生成するツールが必要であると判断した場合、モデルはstopReasonレスポンスフィールドを に設定しますtool_use。レスポンスは、モデルが実行したいツール (top_song) と、ツールでクエリしたいラジオステーション (WZPZ) も識別します。リクエストされたツールに関する情報は、モデルが output (ConverseOutput) フィールドで返すメッセージにあります。具体的には、 toolUse (ToolUseBlock) フィールドです。toolUseId フィールドを使用して、後の呼び出しでツールリクエストを識別します。

次の例は、 で説明されているメッセージに合格Converseしたときの からのレスポンスを示していますステップ 1: メッセージとツール定義を送信する。

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "toolUse": {
                        "toolUseId": "tooluse_hbTgdi0CSLq_hM4P8csZJA",
                        "name": "top_song",
                        "input": {
                            "sign": "WZPZ"
                        }
                    }
                }
            ]
        }
    },
    "stopReason": "tool_use"
}

ステップ 3: モデルのツールリクエストを行う

モデルレスポンスの toolUseフィールドから、 nameフィールドを使用してツールの名前を識別します。次に、ツールの実装を呼び出し、 inputフィールドから入力パラメータを渡します。

次に、 toolResult (ToolResultBlock) コンテンツブロックを含むユーザーメッセージを作成します。コンテンツブロックには、ツールからのレスポンスと、前のステップで取得したツールリクエストの ID を含めます。

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "json": {
                            "song": "Elemental Hotel",
                            "artist": "8 Storey Hike"
                        }
                    }
                ]
            }
        }
    ]
}

存在しないラジオステーションのリクエストなど、ツールでエラーが発生した場合は、 toolResultフィールドのモデルにエラー情報を送信できます。エラーを表示するには、 error status フィールドに を指定します。次のエラー例は、ツールがラジオステーションを見つけられない場合の です。

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "text": "Station WZPA not found."
                    }
                ],
                "status": "error"
            }
        }
    ]
}

ステップ 4: モデルレスポンスを取得する

前のステップで作成したユーザーメッセージを への呼び出しに含めることで、モデルとの会話を続行しますConverse。次に、モデルは、メッセージの toolResult フィールドで指定した情報を使用して、元のメッセージ ( で最も人気のある曲は何ですかWZPZ?) に応答するレスポンスを生成します。

{
     "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike."
                }
            ]
        }
    },
    "stopReason": "end_turn"