Uso de herramientas (llamada a funciones)
Las herramientas amplían las capacidades de Amazon Nova al conectar el modelo a funciones externas, como API, bases de datos y entornos de ejecución de código. El uso de herramientas permite a Amazon Nova acceder a información en tiempo real, hacer cálculos e interactuar con sistemas externos.
Descripción del flujo de trabajo del uso de herramientas
El uso de herramientas con Amazon Nova implica tres fases clave:
- Consulta del usuario y definición de la herramienta
-
Para definir las herramientas, proporcione esquemas JSON que describan la funcionalidad y los requisitos de entrada de cada herramienta. La configuración de la herramienta debe incluir detalles explícitos sobre cuándo y cómo se debe utilizar cada herramienta.
- Selección de herramientas
-
Cuando un usuario envía un mensaje, Amazon Nova lo analiza para determinar si necesita una herramienta. Esta elección automática de herramientas examina el contexto y decide qué herramienta (si hay alguna) se debe invocar. Si Amazon Nova identifica una herramienta adecuada, devolverá su nombre y los parámetros necesarios.
Usted es responsable de ejecutar la herramienta en función de la solicitud del modelo. Esto significa que escribirá el código que invoca la funcionalidad de la herramienta y procesa los parámetros de entrada proporcionados por el modelo.
- Devolución de resultados
-
Después de ejecutar la herramienta, envíe los resultados a Amazon Nova en un formato estructurado mediante JSON o una combinación de texto e imágenes. Amazon Nova incorpora la salida de la herramienta en la respuesta final. Si se producen errores durante la ejecución, indíquelo en la respuesta de la herramienta para permitir que Amazon Nova lo ajuste en consecuencia.
Creación de una herramienta
Defina las herramientas mediante una configuración de herramientas que incluya una matriz de herramientas y, opcionalmente, un parámetro de elección de herramientas. Cada especificación de herramienta debe incluir lo siguiente:
-
Nombre: identificador único para la herramienta
-
Descripción: explicación concisa de la funcionalidad de la herramienta
-
Esquema de entrada: esquema JSON que defina los parámetros obligatorios y opcionales
ejemplo Ejemplo de configuración de herramientas
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"] } } } } ] }
Prácticas recomendadas para definiciones de herramientas
-
Asegúrese de que el nombre y la descripción coincidan de forma explícita con la funcionalidad exacta de la herramienta y evite las herramientas que sean demasiado similares semánticamente.
-
Incluya los diferenciadores clave en la descripción para ayudar al modelo a distinguir entre herramientas similares.
-
Limite los esquemas JSON a dos capas de anidación para obtener el mejor rendimiento.
-
Restrinja las entradas mediante tipos de esquema (por ejemplo, enum, int, float) en lugar de describir la estructura en texto sin formato.
-
Indique los parámetros obligatorios y opcionales mediante la notación de esquema JSON (por ejemplo, "required": ["param1", "param2"]).
-
Valide el esquema JSON con un validador estándar antes de enviarlo.
-
Coloque los argumentos de cadena larga al final del esquema y evite anidarlos.
Salida estructurada con decodificación restringida
Los modelos de Amazon Nova aprovechan la decodificación restringida para garantizar una alta fiabilidad en las salidas generadas. Esta técnica utiliza la gramática para restringir los posibles tokens en cada paso de generación, lo que evita que las claves no sean válidas y aplica los tipos de datos correctos en función del esquema definido.
ejemplo Ejemplo de salida estructurada
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"} } }
Opciones de elección de herramientas
Amazon Nova admite tres parámetros de elección de herramientas:
- Herramienta
-
Se llamará una vez a la herramienta, lo que es ideal para casos de uso de salidas estructuradas
- Cualquiera
-
Se llamará a una de las herramientas proporcionadas al menos una vez, lo que es útil para escenarios de selección de API.
- Auto
-
El modelo decide si llamar a una herramienta y a cuántas herramientas se llamará (comportamiento predeterminado).
Llamada a una herramienta
Cuando Amazon Nova decide llamar a una herramienta, devuelve un bloque de uso de herramientas como parte del mensaje del asistente con stopReason establecido en “tool_use”. El bloque de herramientas contiene el nombre de la herramienta y sus entradas.
nota
Ejecute las siguientes secciones de código secuencialmente (Llamada a una herramienta → Procesamiento de la llamada a la herramienta → Devolución de los resultados de la herramienta) en una sola sesión de Python. Para volver a ejecutar los ejemplos, reinicie la sesión de Python.
ejemplo Llamada a una herramienta
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']}")
Procesamiento de llamadas a herramientas
Extraiga el nombre y los argumentos de la herramienta del mensaje y, a continuación, invoque la herramienta:
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"])
Devolución de los resultados de la herramienta
Devuelva los resultados de la herramienta con el esquema 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}")
Gestión de errores
Informe de los errores a Amazon Nova para permitir la modificación de la solicitud y volver a intentarlo:
tool_result_message = { "role": "user", "content": [ { "toolResult": { "toolUseId": tool["toolUseId"], "content": [{"text": "A validation exception occurred on field: sample.field"}], "status": "error" } } ] }
Consideraciones de seguridad
-
Valide que las herramientas existan antes de invocarlas.
-
Asegúrese de que las entradas estén formateadas correctamente.
-
Compruebe que existan los permisos adecuados antes de ejecutar la herramienta.
-
Confíe en los detalles de la sesión en lugar de permitir que Amazon Nova ingrese información del usuario en las llamadas a herramientas.
-
Recuerde que los LLM pueden alucinar con las llamadas a herramientas, por lo que deberá validarlos siempre antes de ejecutarlos.
Herramientas del sistema integradas
Los modelos de Amazon Nova 2.0 incluyen herramientas integradas completamente administradas que no requieren una implementación personalizada. Habilite estas herramientas con un sencillo cambio en la API de Converse.
Code Interpreter
Intérprete de código permite a Nova poner en marcha código Python de forma segura en entornos de pruebas aislados. Esta herramienta está diseñada para cálculos matemáticos, operaciones lógicas y algoritmos iterativos.
nota
Code Interpreter está disponible en las regiones de AWS IAD, PDX y NRT. Para asegurarse de que las solicitudes se envíen a una región compatible, utilice CRIS global. Al utilizar claves de la API de Bedrock, tendrá que agregar manualmente los permisos InvokeTool a las definiciones de las políticas. El rol predeterminado de Bedrock no permite la acción InvokeTool.
Especifique el parámetro systemTool para habilitar Code Interpreter:
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"])
El intérprete ejecuta el código en un entorno de pruebas y devuelve el resultado en un esquema estándar:
{ "stdOut": "String", "stdErr": "String", "exitCode": "int", "isError": "boolean" }
Web Grounding
El Anclaje web permite a Amazon Nova acceder a información de Internet en tiempo real, lo que proporciona respuestas actualizadas y reduce las alucinaciones. Para habilitarlo, especifique la herramienta del sistema nova_grounding:
tool_config = { "tools": [{ "systemTool": {"name": "nova_grounding"} }] }
Para obtener información detallada sobre el Anclaje web, consulte Web Grounding.
Protocolo de contexto para modelos (MCP)
El protocolo de contexto para modelos (MCP) es un estándar abierto que permite las conexiones bidireccionales seguras entre orígenes de datos y herramientas basadas en IA. En lugar de crear adaptadores personalizados para cada API o servicio, ejecute un servidor MCP y deje que Amazon Nova detecte las herramientas automáticamente por medio de un puente cliente.
Una vez conectadas, Amazon Nova trata las herramientas MCP como cualquier otra integración externa: decide cuándo llamarlas, envía los parámetros obligatorios e incorpora los resultados en las respuestas. El uso de Amazon Nova con Strands facilita las cosas con un MCPClient integrado que administra automáticamente la detección, la conexión y la asignación de resultados.
