# Amazon Nova 的“工具使用”（函数调用）
<a name="tool-use"></a>

**注意**  
本文档适用于 Amazon Nova 版本 1。有关在 Amazon Nova 2 中使用工具的信息，请访问[使用工具（函数调用）](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-tools.html)。

工具是向 Amazon Nova 提供外部功能（例如 API 调用或代码函数）的一种方式。本节将介绍在使用 Amazon Nova 模型时如何定义工具并与之集成。

“工具使用”涉及三个简要步骤：
+ **用户查询** – 可以提供描述每个工具的功能和输入要求的 JSON 架构，来定义 Amazon Nova 可以使用的工具。
+ **工具选择** – 用户发送消息时，Amazon Nova 将对消息进行分析，确定是否需要使用工具来生成回复。这称为 `Auto` 工具选择。有关更多信息，请参阅[选择工具](https://docs.aws.amazon.com/nova/latest/userguide/tool-choice.html)。如果 Amazon Nova 确定了合适的工具，就会“调用该工具”并返回工具名称和要使用的参数。

  身份开发人员，您负责根据模型的请求执行该工具。这意味着你需要编写代码来调用工具功能并处理模型提供的输入参数。
**注意**  
像所有 LLM 回复一样，Amazon Nova 可能产生工具调用的幻觉。身份开发人员，您有责任验证该工具是否存在、输入的格式是否正确以及相应的权限是否已到位。
+ **返回结果** – 执行该工具后，您必须以结构化格式将结果发送回 Amazon Nova。有效格式包括 JSON 和图文组合。这让 Amazon Nova 可以将工具输出整合到对用户的最终回复中。

  如果在工具执行过程中出现任何错误，您可以在工具对 Amazon Nova 的回复中指出这一点，让 Amazon Nova 可以相应地调整其回复。

请考虑一个简单的计算器工具示例：

------
#### [ User query ]

工具调用工作流程的第一步是用户向 Amazon Nova 查询数学方程式（即 10 乘以 5）的结果。该查询作为提示与代表计算器的工具规格一起发送给 Amazon Nova。

```
user_query = "10*5"

messages = [{
    "role": "user",
    "content": [{"text": user_query}]
}]

tool_config = {
    "tools": [
        {
            "toolSpec": {
                "name": "calculator", # Name of the tool
                "description": "A calculator tool that can execute a math equation", # Concise description of the tool
                "inputSchema": {
                    "json": { 
                        "type": "object",
                        "properties": {
                            "equation": { # The name of the parameter
                                "type": "string", # parameter type: string/int/etc
                                "description": "The full equation to evaluate" # Helpful description of the parameter
                            }
                        },
                        "required": [ # List of all required parameters
                            "equation"
                        ]
                    }
                }
            }
        }
    ]
}
```

------
#### [ Tool selection ]

Amazon Nova 使用该工具的上下文以及用户提示来确定要使用的必要工具和所需配置。此项作为 API 回复的一部分返回。

```
{
    "toolUse": {
        "toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ", 
        "name": "calculator", 
        "input": {
            "equation": "10*5"
         }
    }
}
```

应用程序负责执行该工具并存储结果。

```
def calculator(equation: str):
    return eval(equation)
    
tool_result = calculator("10*5")
```

------
#### [ Return results ]

要将该工具的结果返回给 Amazon Nova，需在新的 API 请求中包含工具结果。请注意，“工具使用”编号与 Amazon Nova 在先前回复中返回的编号一致。

```
{ 
    "toolResult": {
        "toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
        "content": [
            {
                "json": {
                    "result": "50"
                }
            }
        ],
        "status": "success"
    }
}
```
+ Amazon Nova 将使用消息的完整上下文，包括初始用户查询、“工具使用”和工具结果来确定对用户的最终回复。在这种情况下，Amazon Nova 将回复用户“10 乘以 5 等于 50”。

------

Amazon Nova 允许在 Invoke API 和 Converse API 中同时使用工具。不过，为了获得全面的功能，建议使用 [Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use-inference-call.html)，我们也会在下文中使用这个 API 来举例说明。

**Topics**
+ [定义工具](tool-use-definition.md)
+ [调用工具](tool-use-invocation.md)
+ [选择工具](tool-choice.md)
+ [返回工具结果](tool-use-results.md)
+ [使用内置工具](tool-built-in.md)
+ [报告错误](tool-use-error.md)
+ [其他参考资料](#tool-use-resources)

## 其他参考资料
<a name="tool-use-resources"></a>

1. [使用工具完成模型回复](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)

1. [使用 Amazon Nova 构建人工智能代理](agents.md)

1. [文本理解提示最佳实践](prompting-text-understanding.md)

1. [工具调用故障排除](prompting-tool-troubleshooting.md)