使用工具（函数调用）

工具可将模型与 API、数据库及代码执行环境等外部功能相连，从而拓展 Amazon Nova 的能力。通过使用工具，Amazon Nova 能够访问实时信息、进行计算并与外部系统交互。

了解工具使用工作流程

在 Amazon Nova 中使用工具涉及三个关键阶段：

用户查询与工具定义

通过提供描述各工具功能与输入要求的 JSON 架构来定义工具。工具配置必须包括有关何时以及如何使用每种工具的详细描述。

工具选择

用户发送消息时，Amazon Nova 将对消息进行分析，确定是否需要使用工具。这种自动工具选择会检查上下文并决定要调用的工具（如有）。如果 Amazon Nova 确定了合适的工具，就会返回工具名称和必填参数。

您负责根据模型的请求执行该工具。这意味着需要编写代码来调用工具功能并处理模型提供的输入参数。

返回结果

工具执行完毕后，以 JSON 或文本 + 图像组合的结构化格式，将结果回传给 Amazon Nova。Amazon Nova 可以将工具输出整合到对最终回复中。如果在执行过程中出现错误，请在工具回复中注明这一点，以便 Amazon Nova 可以进行相应调整。

创建工具

通过工具配置定义工具，该配置包含工具数组，以及可选的工具选择参数。每种工具规范必须包括：

名称：工具的清晰标识符
描述：工具功能的简要说明
输入架构：定义必填参数与选填参数的 JSON 架构

例工具配置示例


tool_config = {
    "tools": [
        {
            "toolSpec": {
                "name": "calculator",
                "description": "A calculator tool that can execute a math equation",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "properties": {
                            "equation": {
                                "type": "string",
                                "description": "The full equation to evaluate"
                            }
                        },
                        "required": ["equation"]
                    }
                }
            }
        }
    ]
}

工具定义最佳实践

确保名称与描述明确传达工具的确切功能；避免使用语义过于相似的工具
在描述中包含关键差异化因素，帮助模型区分相似的工具
为获得最佳性能，将 JSON 架构限制为两层嵌套
使用架构类型（例如 enum、int、float）来限制输入，而不是用纯文本描述结构
使用 JSON 架构表示法标注必填参数与选填参数（例如 "required": ["param1", "param2"]）
提交前使用标准验证器验证 JSON 架构
将长字符串参数置于架构末尾，避免嵌套

带约束解码的结构化输出

Amazon Nova 模型利用约束解码来确保生成的输出具有较高可靠性。此技术使用语法在每个生成步骤限制可能的词元，防止密钥无效，并根据您定义的架构强制使用正确的数据类型。

例结构化输出示例


tool_config = {
    "tools": [
        {
            "toolSpec": {
                "name": "ProductAnalysis",
                "description": "Analyze product information from text.",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "Product name"
                            },
                            "rating": {
                                "maximum": 5,
                                "description": "Customer rating 1-5",
                                "type": ["number", "null"],
                                "minimum": 1
                            },
                            "features": {
                                "description": "Key product features",
                                "type": "array",
                                "items": {"type": "string"}
                            },
                            "category": {
                                "type": "string",
                                "description": "Product category"
                            },
                            "price": {
                                "type": "number",
                                "description": "Price in USD"
                            }
                        },
                        "required": ["name", "category", "price", "features"]
                    }
                }
            }
        }
    ],
    "toolChoice": {
        "tool": {"name": "ProductAnalysis"}
    }
}

工具选择选项

Amazon Nova 支持三个工具选择参数：

Tool: 指定工具将被调用一次，适用于结构化输出使用案例
Any: 至少调用所提供工具中的某一个，适用于 API 选择场景
Auto: 由模型决定是否调用工具以及调用工具的数量（默认行为）

调用工具

Amazon Nova 决定调用工具时，会将工具使用块作为助手消息的一部分返回，且 stopReason 设置为 tool_use。工具块包含工具的名称及其输入。

注意

在单个 Python 会话中依次运行以下代码段：调用工具 → 处理工具调用 → 返回工具执行结果。如需再次运行示例，请重启 Python 会话。

例调用工具


import boto3
import json

# Create Bedrock client
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

# Complex calculation that benefits from precise computation
messages = [{
    "role": "user",
    "content": [{
        "text": "Calculate the compound interest on $10,000 invested at 4.75% annual rate for 7 years, compounded quarterly. Use the formula A = P(1 + r/n)^(nt) where P=10000, r=0.0475, n=4, t=7"
    }]
}]

# Define tool configuration with calculator
tool_config = {
    "tools": [{
        "toolSpec": {
            "name": "calculator",
            "description": "Perform mathematical calculations",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "expression": {
                            "type": "string",
                            "description": "Mathematical expression to evaluate"
                        }
                    },
                    "required": ["expression"]
                }
            }
        }
    }]
}

# Invoke Model
response = bedrock.converse(
    modelId="us.amazon.nova-2-lite-v1:0",
    messages=messages,
    toolConfig=tool_config
)

# Extract tool use from response
tool = next(
    block["toolUse"]
    for block in response["output"]["message"]["content"]
    if "toolUse" in block
)

print(f"Tool: {tool['name']}")
print(f"Expression: {tool['input']['expression']}")

处理工具调用

从消息中提取工具名称与参数，然后调用该工具：


def calculate(expression):
    """Evaluate mathematical expression"""
    print(f"Calculating: {expression}")
    P = 10000
    r = 0.0475
    n = 4
    t = 7
    result = P * (1 + r/n) ** (n*t)
    return result

stop_reason = response["stopReason"]

if stop_reason == "tool_use":
    if tool["name"] == "calculator":
        result = calculate(tool["input"]["expression"])

返回工具执行结果

使用 ToolResultBlock 架构返回工具执行结果：


messages.append(response["output"]["message"])

# Add the tool result
messages.append({
    "role": "user",
    "content": [{
        "toolResult": {
            "toolUseId": tool['toolUseId'],
            "content": [{"json": {"result": result}}],
            "status": "success"
        }
    }]
})

# Send the tool result to the model
response = bedrock.converse(
    modelId="us.amazon.nova-2-lite-v1:0",
    messages=messages,
    toolConfig=tool_config
)

# Extract and display final response
final_text = next(
    block["text"]
    for block in response["output"]["message"]["content"]
    if "text" in block
)

print(f"\nFinal Response:\n{final_text}")

错误处理

将错误信息回传到 Amazon Nova，以便对请求进行修改并重试：


tool_result_message = {
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": tool["toolUseId"],
                "content": [{"text": "A validation exception occurred on field: sample.field"}],
                "status": "error"
            }
        }
    ]
}

安全注意事项

在调用工具之前，请确认工具是否存在
确保输入的格式正确
在执行工具之前，请确认是否有适当的权限
基于会话详情进行处理，禁止 Amazon Nova 在工具调用中注入用户信息
注意：LLM 可能会虚构工具调用，务必在执行前进行校验

内置系统工具

Amazon Nova 2.0 模型包含完全托管的内置工具，无需自定义实现。通过 Converse API 中的简易开关即可启用这些工具。

代码解释器

通过代码解释器，Nova 可以在隔离的沙盒环境中安全地执行 Python 代码。此工具专为数学计算、逻辑运算和迭代算法而设计。

注意

代码解释器在 IAD、PDX 和 NRT AWS 区域中可用。为确保请求路由至支持的区域，请使用全局 CRIS。使用 Bedrock API 密钥时，需要手动将 InvokeTool 权限添加到策略定义。默认 Bedrock 角色不允许 InvokeTool 操作。

通过指定 systemTool 参数启用代码解释器：


import boto3
import json

bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

tool_config = {
    "tools": [{
        "systemTool": {
            "name": "nova_code_interpreter"
        }
    }]
}

response = bedrock.converse(
    modelId="us.amazon.nova-2-lite-v1:0",
    messages=[{
        "role": "user",
        "content": [{
            "text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82"
        }]
    }],
    toolConfig=tool_config,
    inferenceConfig={"maxTokens": 10000, "temperature": 0}
)

# Pretty print the response
for block in response["output"]["message"]["content"]:
    if "toolUse" in block:
        print("=== Tool Use ===")
        print(f"Tool: {block['toolUse']['name']}")
        print(f"Code:\n{block['toolUse']['input']['snippet']}\n")
    
    elif "toolResult" in block:
        print("=== Tool Result ===")
        result = block['toolResult']['content'][0]['json']
        print(f"Output: {result['stdOut']}")
        if result['stdErr']:
            print(f"Error: {result['stdErr']}")
        print(f"Exit Code: {result['exitCode']}\n")
    
    elif "text" in block:
        print("=== Final Answer ===")
        print(block["text"])

该解释器在沙盒中运行代码，并以标准架构的形式返回结果：


{
    "stdOut": "String",
    "stdErr": "String",
    "exitCode": "int",
    "isError": "boolean"
}

Web Grounding

通过 Web Grounding 功能，Amazon Nova 能够访问互联网中的实时信息，从而提供最新的回复并减少幻觉。通过指定 nova_grounding 系统工具来启用：


tool_config = {
    "tools": [{
        "systemTool": {"name": "nova_grounding"}
    }]
}

有关 Web Grounding 的详细信息，请参阅 Web Grounding。

模型上下文协议（MCP）

模型上下文协议（MCP）是一种开放标准，支持在数据来源和人工智能驱动的工具之间建立安全的双向连接。可运行 MCP 服务器，让 Amazon Nova 自动通过客户端网桥发现其工具，而不必为每个 API 或服务编写自定义适配器。

连接后，Amazon Nova 会像其他任何外部集成一样对待 MCP 工具：决定何时调用、发送所需的参数以及将结果纳入其回复中。通过内置的 MCPClient，搭配 Amazon Nova 与 Strands 使用可简化操作，该客户端能自动管理发现、连接与结果映射。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

扩展思考

构建人工智能代理