本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 工具組態
<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/zh_tw/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 支援三個工具選擇參數，以控制何時和使用哪些工具。在工具組態中指定 toolChoice 參數：
+ 自動 （預設）：模型會決定是否需要任何工具，並視需要呼叫多個工具。提供最大的彈性。
+ 任何：確保在回應開始時呼叫至少一個可用工具，模型會選取最適當的工具。當您有多個知識庫或工具，並想要保證使用一個知識庫或工具時很有用。
+ 工具：強制在回應開始時只呼叫特定具名工具一次。例如，如果您指定知識庫工具，無論模型是否認為需要該工具，模型都會在回應之前進行查詢。

**工具選項範例**

Auto (自動) (預設)

```
"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. 接收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)。