View a markdown version of this page

工具配置 - Amazon Nova
定义工具工具选择参数接收并处理工具使用事件最佳实践

工具配置

Amazon Nova 2 Sonic 支持工具使用（亦称函数调用），模型可在对话过程中请求外部信息或执行操作，例如调用 API、查询数据库或运行自定义代码函数。这让语音助手能够根据用户指令执行操作、获取信息并对接外部服务。

Nova 2 Sonic 采用异步工具调用机制，人工智能可在工具于后台运行的同时继续自然对话，带来更流畅、更灵敏的使用体验。

以下为使用工具的简化流程：

  1. 定义工具：在 promptStart 事件中，指定可用工具及其参数

  2. 用户发话：用户提出需要调用工具的请求（例如“西雅图天气如何？”）

  3. 工具调用：Nova 2 Sonic 识别需求并发送 toolUse 事件

  4. 执行工具：应用程序执行对应工具并返回结果

  5. 回复生成：Nova 2 Sonic 将结果整合进语音回复中

下图展示了工具使用的工作流程：

定义工具

工具通过 JSON 架构定义，用于描述其用途、参数及预期输入。

以下为工具定义的组成部分及说明：

  • Name：工具的唯一标识符（使用 snake_case）

  • Description：清晰说明该工具的功能，辅助人工智能判断调用时机

  • InputSchema：定义该工具接受的参数的 JSON 架构

  • Properties：带有类型和描述的单个参数

  • Required：必须提供的参数名称数组

以下为简易天气工具定义示例

{
  "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（默认）：模型决定是否需要任何工具，并且可以根据需要调用多个工具。提供最大灵活性。

  • Any：确保在回复开始时至少调用一个可用工具，并由模型自主选择最合适的工具。如果有多个知识库或工具，并且想要保证使用其中一个，此功能非常有用。

  • Tool：强制仅在响应开始时调用一次指定名称的工具。例如，若您指定了知识库工具，则无论模型是否认为需要该工具，模型都将在做出回复之前查询该知识库。

工具选择示例

自动（默认）

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

Any：

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

特定工具：

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

接收并处理工具使用事件

当 Amazon Nova 2 Sonic 判断需要使用工具时，会发送一个 toolUse 事件，包含以下内容：

  1. toolUseID：本次工具调用的唯一标识符

  2. ToolName：待执行的工具名称

  3. Content：JSON 字符串，包含从用户请求中提取的参数

  4. SessionID：当前会话标识符

  5. Role：工具使用事件固定设为 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）。