View a markdown version of this page

ツール設定 - Amazon Nova
ツールの定義ツール選択パラメータツール使用イベントの受信と処理ベストプラクティス

ツール設定

Amazon Nova 2 Sonic は、ツールの使用 (関数呼び出しとも呼ばれます) をサポートしています。これにより、モデルは会話中に、API コール、データベースクエリ、カスタムコード関数などの外部情報またはアクションをリクエストできます。これにより、音声アシスタントはユーザーリクエストに基づいてアクションを実行し、情報を取得し、外部サービスと統合できます。

Nova 2 Sonic は非同期ツール呼び出し機能を備えており、ツールがバックグラウンドで実行されている間も AI が自然に会話を続けることができるため、よりスムーズで応答性の高いユーザーエクスペリエンスを実現できます。

ツールの使用方法に関する簡単な手順を以下に示します。

  1. ツールの定義: promptStart イベントで、利用可能なツールをそのパラメータと共に指定する

  2. ユーザーが話す: ユーザーがツールを必要とするリクエストを行う (「シアトルの天気は?」など)

  3. ツール呼び出し: Nova 2 Sonic は必要性を認識し、toolUse イベントを送信します

  4. ツールの実行: アプリケーションがツールを実行し、結果を返します

  5. レスポンスの生成: Nova 2 Sonic は結果を音声レスポンスに組み込みます

次の図は、ツール使用の仕組みを示しています。

ツールの定義

ツールは、その目的、パラメータ、予想される入力を記述する JSON スキーマを使用して定義されます。

以下は、ツール定義のコンポーネントと説明です。

  • 名前: ツールの一意の識別子 (snake_case を使用します)

  • 説明: ツールの動作を明確に説明し、AI がツールを使用するタイミングを決定するのに役立ちます

  • InputSchema: ツールが受け入れるパラメータを定義する JSON スキーマ

  • プロパティ: タイプと説明を含む個々のパラメータ

  • 必須: 指定する必要があるパラメータ名の配列

簡単な気象ツールの定義を次に示します

{
  "toolSpec": {
    "name": "get_weather",
    "description": "Get current weather information for a specific location",
    "inputSchema": {
      "json": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name or zip code"
          },
          "units": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "Temperature units"
          }
        },
        "required": ["location"]
      }
    }
  }
}

ツール設定は、音声およびテキスト出力設定とともに promptStart イベントで Nova 2 Sonic に渡されます。

{
    "event": {
        "promptStart": {
            "promptName": "<prompt-id>",
            "textOutputConfiguration": {
                "mediaType": "text/plain"
            },
            "audioOutputConfiguration": {
                "mediaType": "audio/lpcm",
                "sampleRateHertz": 16000,
                "sampleSizeBits": 16,
                "channelCount": 1,
                "voiceId": "matthew",
                "encoding": "base64",
                "audioType": "SPEECH"
            },
            "toolUseOutputConfiguration": {
                "mediaType": "application/json"
            },
            "toolConfiguration": {
                "tools": [
                    {
                        "toolSpec": {
                            "name": "get_weather",
                            "description": "Get current weather information for a specific location",
                            "inputSchema": {
                                "json": {
                                    "type": "object",
                                    "properties": {
                                        "location": {
                                            "type": "string",
                                            "description": "City name or zip code"
                                        },
                                        "units": {
                                            "type": "string",
                                            "enum": ["celsius", "fahrenheit"],
                                            "description": "Temperature units"
                                        }
                                    },
                                    "required": ["location"]
                                }
                            }
                        }
                    }
                ],
                "toolChoice": {
                    "auto": {}
                }
            }
        }
    }
}

ツール選択パラメータ

Nova 2 Sonic は、使用するツールとタイミングを制御するための 3 つのツール選択パラメータをサポートしています。ツール設定で toolChoice パラメータを指定します。

  • 自動 (デフォルト): モデルはツールが必要かどうかを決定し、必要に応じて複数のツールを呼び出すことができます。最大限の柔軟性を提供します。

  • 任意 – モデルは最適なツールを選択しながら、利用可能なツールの少なくとも 1 つがレスポンスの開始時に確実に呼び出されるようにします。複数のナレッジベースまたはツールがあり、そのナレッジベースまたはツールのどちらかが確実に使用されるようにする場合に便利です。

  • ツール: 特定の名前付きツールが、レスポンスの開始時に 1 回だけ強制的に呼び出されるようにします。例えば、ナレッジベースツールを指定すると、モデルはツールが必要と考えるかどうかにかかわらず、応答する前にこのナレッジベースをクエリします。

ツール選択の例

自動 (デフォルト)

"toolChoice": { 
    "auto": {} 
}

いずれか:

"toolChoice": {
    "any": {}
}

特定のツール:

"toolChoice": {
    "tool": {
        "name": "get_weather"
    }
}

ツール使用イベントの受信と処理

Amazon Nova 2 Sonic は、ツールが必要であると判断した場合、以下を含む toolUse イベントを送信します。

  1. toolUseID: このツール呼び出しの一意の識別子

  2. ToolName: 実行するツール名

  3. コンテンツ: ユーザーのリクエストから抽出されたパラメータを含む JSON 文字列

  4. SessionID: 現在のセッション識別子

  5. ロール: ツール使用イベントの場合、「TOOL」に設定されます

ツール使用イベントの例

{
    "event": {
        "toolUse": {
            "completionId": "<completion-id>",
            "content": "{\"location\": \"Seattle\", \"units\": \"fahrenheit\"}",
            "contentId": "<content-id>",
            "promptName": "<prompt-id>",
            "role": "TOOL",
            "sessionId": "<session-id>",
            "toolName": "get_weather",
            "toolUseId": "<tool-use-id>"
        }
    }
}

処理ステップ

  1. Nova 2 Sonic から toolUse イベントを受信する

  2. イベントからツール名とパラメータを抽出する

  3. ツールロジックを実行する (API コール、データベースクエリなど)

  4. toolResult イベントを使用して結果を返す

ToolResult イベントの例

{
    "event": {
        "toolResult": {
            "promptName": "<prompt-id>",
            "contentName": "<content-id>",
            "content": "{\"temperature\": 72, \"condition\": \"sunny\", \"humidity\": 45}"
        }
    }
}

ベストプラクティス

  • 明確な説明: Nova 2 Sonic が各ツールを使用するタイミングを理解するのに役立つ詳細なツールの説明を記述します。

  • パラメータの検証: エラーを防ぐために、実行前に必ずツールパラメータを検証してください。可能な限り、オープンエンド文字列ではなく、構造化データ型 (列挙型、数値、ブール値など) の適切な JSON スキーマを使用してツールパラメータを定義します。

  • エラー処理: ツールが失敗すると、toolResult イベントに意味のあるエラーメッセージを返します。

  • 非同期実行: 非同期ツール呼び出しを活用して会話フローを維持します。

  • ツールの命名: わかりやすいアクション指向の名前 (get_ weather、search_database、send_email など) を使用します。