# 工具配置
<a name="sonic-tool-configuration"></a>

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

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

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

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

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

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

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

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

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

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


## 定义工具
<a name="sonic-tool-defining"></a>

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

以下为工具定义的组成部分及说明：
+ Name：工具的唯一标识符（使用 snake\_case）
+ Description：清晰说明该工具的功能，辅助人工智能判断调用时机
+ InputSchema：定义该工具接受的参数的 JSON 架构
+ Properties：带有类型和描述的单个参数
+ Required：必须提供的参数名称数组

### 工具定义示例
<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（默认）：模型决定是否需要任何工具，并且可以根据需要调用多个工具。提供最大灵活性。
+ Any：确保在回复开始时至少调用一个可用工具，并由模型自主选择最合适的工具。如果有多个知识库或工具，并且想要保证使用其中一个，此功能非常有用。
+ Tool：强制仅在响应开始时调用一次指定名称的工具。例如，若您指定了知识库工具，则无论模型是否认为需要该工具，模型都将在做出回复之前查询该知识库。

**工具选择示例**

自动（默认）

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

Any：

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

特定工具：

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

## 接收并处理工具使用事件
<a name="sonic-tool-receiving"></a>

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

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

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

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

1. SessionID：当前会话标识符

1. 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 事件

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）。