# ツール設定
<a name="sonic-tool-configuration"></a>

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

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

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

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

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

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

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

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

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

![](http://docs.aws.amazon.com/ja_jp/nova/latest/nova2-userguide/images/How-tool-use-works_5.png)


## ツールの定義
<a name="sonic-tool-defining"></a>

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

以下は、ツール定義のコンポーネントと説明です。
+ 名前: ツールの一意の識別子 (snake\_case を使用します)
+ 説明: ツールの動作を明確に説明し、AI がツールを使用するタイミングを決定するのに役立ちます
+ InputSchema: ツールが受け入れるパラメータを定義する JSON スキーマ
+ プロパティ: タイプと説明を含む個々のパラメータ
+ 必須: 指定する必要があるパラメータ名の配列

### ツール定義の例
<a name="w2aac25c13c23c15b9b1"></a>

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

```
{
  "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 でのツールの設定
<a name="w2aac25c13c23c15b9b3"></a>

ツール設定は、音声およびテキスト出力設定とともに `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": {}
                }
            }
        }
    }
}
```

## ツール選択パラメータ
<a name="sonic-tool-choice-parameters"></a>

Nova 2 Sonic は、使用するツールとタイミングを制御するための 3 つのツール選択パラメータをサポートしています。ツール設定で toolChoice パラメータを指定します。
+ 自動 (デフォルト): モデルはツールが必要かどうかを決定し、必要に応じて複数のツールを呼び出すことができます。最大限の柔軟性を提供します。
+ 任意 – モデルは最適なツールを選択しながら、利用可能なツールの少なくとも 1 つがレスポンスの開始時に確実に呼び出されるようにします。複数のナレッジベースまたはツールがあり、そのナレッジベースまたはツールのどちらかが確実に使用されるようにする場合に便利です。
+ ツール: 特定の名前付きツールが、レスポンスの開始時に 1 回だけ強制的に呼び出されるようにします。例えば、ナレッジベースツールを指定すると、モデルはツールが必要と考えるかどうかにかかわらず、応答する前にこのナレッジベースをクエリします。

**ツール選択の例**

自動 (デフォルト)

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

いずれか:

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

特定のツール:

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

## ツール使用イベントの受信と処理
<a name="sonic-tool-receiving"></a>

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

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

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

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

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

1. ロール: ツール使用イベントの場合、「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 イベントを受信する

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

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

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

ToolResult イベントの例

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

## ベストプラクティス
<a name="sonic-tool-best-practices"></a>
+ 明確な説明: Nova 2 Sonic が各ツールを使用するタイミングを理解するのに役立つ詳細なツールの説明を記述します。
+ パラメータの検証: エラーを防ぐために、実行前に必ずツールパラメータを検証してください。可能な限り、オープンエンド文字列ではなく、構造化データ型 (列挙型、数値、ブール値など) の適切な JSON スキーマを使用してツールパラメータを定義します。
+ エラー処理: ツールが失敗すると、toolResult イベントに意味のあるエラーメッセージを返します。
+ 非同期実行: 非同期ツール呼び出しを活用して会話フローを維持します。
+ ツールの命名: わかりやすいアクション指向の名前 (get\_ weather、search\_database、send\_email など) を使用します。