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 支援三個工具選擇參數，以控制何時和使用哪些工具。在工具組態中指定 toolChoice 參數：

  • 自動 （預設）：模型會決定是否需要任何工具，並視需要呼叫多個工具。提供最大的彈性。

  • 任何：確保在回應開始時呼叫至少一個可用工具，模型會選取最適當的工具。當您有多個知識庫或工具，並想要保證使用一個知識庫或工具時很有用。

  • 工具：強制在回應開始時只呼叫特定具名工具一次。例如，如果您指定知識庫工具，無論模型是否認為需要該工具，模型都會在回應之前進行查詢。

工具選項範例

Auto (自動) (預設)

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