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

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

以下のステップは、Converse API を使ったツールの使用方法を示しています。サンプルコードについては、「Converse API ツールの使用例」を参照してください。

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

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

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

{
    "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 (Message) リクエストパラメータにユーザーメッセージも渡します。

[
    {
        "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 フィールドは、後の呼び出しでツールリクエストを識別するために使用します。

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

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "toolUse": {
                        "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                        "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 フィールドでモデルにエラー情報を送信することができます。エラーを表示するには、status フィールドに error を指定します。次の例は、ツールがラジオステーションを見つけられない場合のエラーです。

{
    "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"