# Uso de herramientas (llamada a funciones) con Amazon Nova
**nota**
Esta documentación corresponde a la versión 1 de Amazon Nova. Para obtener información sobre el uso de herramientas con Amazon Nova 2, consulte [Using tools (function calling)](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-tools.html).
Las herramientas son una forma de proporcionar funcionalidades externas a Amazon Nova, como una llamada a la API o una función de código. En esta sección, se explicará cómo puede definir e integrar las herramientas al trabajar con modelos de Amazon Nova.
El uso de herramientas implica tres pasos importantes:
+ **Consulta de usuario**: usted define las herramientas que Amazon Nova puede utilizar proporcionando un esquema JSON que describa la funcionalidad y los requisitos de entrada de cada herramienta.
+ **Selección de herramientas**: cuando un usuario envía un mensaje, Amazon Nova lo analiza para determinar si necesita una herramienta para generar una respuesta. Esto se conoce como elección de herramienta de `Auto`. Para obtener más información, consulte [Elección de herramientas](https://docs.aws.amazon.com/nova/latest/userguide/tool-choice.html). Si Amazon Nova identifica una herramienta adecuada, “llamará a la herramienta” y devolverá su nombre y los parámetros que se van a utilizar.
Usted, como desarrollador, es responsable de ejecutar la herramienta en función de la solicitud del modelo. Esto significa que debe escribir el código que invoca la funcionalidad de la herramienta y procesa los parámetros de entrada proporcionados por el modelo.
**nota**
Como todas las respuestas de LLM, es posible que Amazon Nova genere una llamada de herramienta alucinada. Es responsabilidad suya, como desarrollador, validar que la herramienta existe, que las entradas están formateadas correctamente y que ya se han establecido los permisos adecuados.
+ **Devolver resultados**: después de ejecutar la herramienta, debe enviar los resultados a Amazon Nova en un formato estructurado. Los formatos válidos incluyen JSON o una combinación de texto e imágenes. Esto permite que Amazon Nova incorpore los resultados de la herramienta en la respuesta final al usuario.
Si se produce algún error durante la ejecución de la herramienta, puede indicarlo en la respuesta de la herramienta a Amazon Nova, lo que permitirá que Amazon Nova ajuste su respuesta en consecuencia.
Analicemos un ejemplo sencillo de una herramienta de calculadora:
------
#### [ User query ]
El primer paso en el flujo de trabajo de llamada a herramientas es la consulta del usuario a Amazon Nova para obtener el resultado de una ecuación matemática: 10 por 5. Esta consulta se envía como petición a Amazon Nova junto con una especificación de herramienta que representa la calculadora.
```
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 utiliza el contexto de la herramienta junto con la petición del usuario para determinar la herramienta que se debe utilizar y la configuración requerida. Se devuelve como parte de la respuesta de la API.
```
{
"toolUse": {
"toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
"name": "calculator",
"input": {
"equation": "10*5"
}
}
}
```
La aplicación es responsable de ejecutar la herramienta y almacenar el resultado.
```
def calculator(equation: str):
return eval(equation)
tool_result = calculator("10*5")
```
------
#### [ Return results ]
Para devolver el resultado de la herramienta a Amazon Nova, este se incluye en una nueva solicitud de la API. Tenga en cuenta que el identificador de uso de la herramienta es coherente con el que Amazon Nova devolvió en la respuesta anterior.
```
{
"toolResult": {
"toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
"content": [
{
"json": {
"result": "50"
}
}
],
"status": "success"
}
}
```
+ Amazon Nova utilizará todo el contexto de los mensajes, incluida la consulta inicial del usuario, el uso de la herramienta y el resultado de la herramienta para determinar la respuesta final al usuario. En este caso, Amazon Nova responderá al usuario que “10 por 5 es 50”.
------
Amazon Nova permite el uso de herramientas tanto en la API de Invoke como en la de Converse; sin embargo, para obtener una gama completa de funciones, recomendamos utilizar la [API de Converse](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use-inference-call.html) y utilizaremos ejemplos con esta API en el futuro.
**Topics**
+ [Definición de una herramienta](tool-use-definition.md)
+ [Invocación de una herramienta](tool-use-invocation.md)
+ [Elección de herramientas](tool-choice.md)
+ [Devolución de los resultados de la herramienta](tool-use-results.md)
+ [Uso de herramientas integradas](tool-built-in.md)
+ [Notificación de un error](tool-use-error.md)
+ [Referencias adicionales](#tool-use-resources)
# Definición de una herramienta
Un paso fundamental en el flujo de trabajo de llamada a la herramienta es definir la herramienta. La definición de la herramienta debe incluir todo el contexto necesario para guiar al modelo sobre cuándo es apropiado invocar la herramienta.
Para definir una herramienta, cree una configuración de herramienta y pásela a la API junto con el mensaje del usuario. El esquema de [configuración de la herramienta](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html) espera una matriz de herramientas y, opcionalmente, un parámetro de elección de herramientas.
**nota**
Amazon Nova es compatible con las opciones `auto`, `any` y `tool` para `toolChoice`. Para obtener más información, consulte [ToolChoice](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolChoice.html) en la documentación de la API de Amazon Bedrock y [Uso de una herramienta para completar una respuesta del modelo de Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html).
A continuación, se muestra un ejemplo de cómo definir una herramienta:
```
tool_config = {
"tools": [
{
"toolSpec": {
"name": "top_song",
"description": "Get the most popular song played on a radio station.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"sign": {
"type": "string",
"description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ, and WKRP."
}
},
"required": [
"sign"
]
}
}
}
}
],
}
```
El nombre, la descripción y el esquema de entrada deben ser explícitos con la funcionalidad exacta de la herramienta. Asegúrese de que los diferenciadores clave sobre cuándo utilizar la herramienta se reflejen en la configuración de la herramienta.
**nota**
Actualmente, los modelos de comprensión de Amazon Nova solo admiten un subconjunto de la funcionalidad de JsonSchema cuando se utilizan para definir el [ToolInputSchema](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolInputSchema.html) en la API de Converse.
El esquema de nivel superior debe ser del tipo [Object](https://json-schema.org/understanding-json-schema/reference/object).
Solo se admiten tres campos en el Object de nivel superior: type (debe estar configurado como “object”), [https://json-schema.org/understanding-json-schema/reference/object#properties](https://json-schema.org/understanding-json-schema/reference/object#properties) y [https://json-schema.org/understanding-json-schema/reference/object#required](https://json-schema.org/understanding-json-schema/reference/object#required).
Para las llamadas a herramientas, se recomienda configurar la temperatura en 0 para permitir una decodificación codiciosa.
A continuación, se muestra un ejemplo de llamada a una herramienta con la API de Converse:
```
import json
import boto3
client = boto3.client("bedrock-runtime", region_name="us-east-1")
input_text = "What is the most popular song on WZPZ?"
messages = [{
"role": "user",
"content": [{"text": input_text}]
}]
inf_params = {"maxTokens": 1000, "temperature": 0}
response = client.converse(
modelId="us.amazon.nova-lite-v1:0",
messages=messages,
toolConfig=tool_config,
inferenceConfig=inf_params
)
messages.append(response["output"]["message"])
# Pretty print the response JSON.
print("[Full Response]")
print(json.dumps(response, indent=2))
# Print the tool content for easy readability.
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
print("\n[Tool Response]")
print(tool)
```
# Invocación de una herramienta
Si Amazon Nova decide llamar a una herramienta, se devolverá un bloque de uso de la herramienta como parte del mensaje del asistente y el motivo de la detención será “tool\$1use”. El bloque de herramientas contendrá el nombre de la herramienta y sus entradas.
**nota**
Para mejorar la precisión de las llamadas a las herramientas, el comportamiento predeterminado de los modelos de Amazon Nova es utilizar el razonamiento en cadena de pensamiento para llamar a las herramientas. El proceso de pensamiento estará disponible en el mensaje del asistente y estará incluido en las etiquetas . Es posible tener varias llamadas a herramientas y bloques de pensamiento en una respuesta, por lo que su aplicación debería tener esto en cuenta.
Si la elección de la herramienta está configurada en `any` o `tool`, esto anulará el comportamiento de la cadena de pensamiento, y la respuesta solo contendrá las llamadas a herramientas necesarias.
```
{
"toolUse":
{
"toolUseId": "tooluse_20Z9zl0BQWSXjFuLKdTJcA",
"name": "top_song",
"input": {
"sign": "WZPZ"
}
}
}
```
Para llamar realmente a la herramienta, el nombre y los argumentos de la herramienta se pueden extraer del mensaje y, a continuación, la aplicación puede invocarla.
Este es un ejemplo de cómo se puede procesar una llamada a una herramienta.
```
def get_top_song(sign):
print(f"Getting the top song at {sign}")
return ("Espresso", "Sabrina Carpenter")
stop_reason = response["stopReason"]
tool, song, artist = None, None, None
if stop_reason == "tool_use":
thought_process = next(
block["text"]
for block in response["output"]["message"]["content"]
if "text" in block
)
print(thought_process)
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
if tool["name"] == "top_song":
song, artist = get_top_song(tool["input"]["sign"])
```
Es importante tener en cuenta la seguridad a la hora de definir e invocar herramientas. Los LLM como Amazon Nova no tienen acceso a los detalles de la sesión, por lo que los permisos deben validarse cuando sea necesario antes de invocar una herramienta. Confíe en los detalles de usuario de su sesión en lugar de aumentar la petición y permitir que Amazon Nova la incorpore a la llamada de herramientas.
# Elección de herramientas
Los modelos de Amazon Nova admiten la funcionalidad de *elección de herramientas*. La elección de herramientas le permite a usted, como desarrollador, controlar la forma en que se llama a una herramienta. Se admiten tres opciones de parámetros para la elección de herramientas: `tool`, `any` y `auto`.
+ **Tool**: la herramienta especificada se llamará una vez.
+ **Any**: se llamará a una de las herramientas proporcionadas al menos una vez.
+ **Auto**: el modelo decidirá si debe llamar a una herramienta y, si es necesario, llamará a varias.
------
#### [ Tool ]
Utilizar `tool` como opción de herramienta le permite controlar la herramienta específica que el modelo llama. El siguiente ejemplo destaca esto con un caso de uso de salida estructurada en el que se requiere que la respuesta esté formateada de manera coherente.
```
tool_config = {
"toolChoice": {
"tool": { "name" : "extract_recipe"}
},
"tools": [
{
"toolSpec": {
"name": "extract_recipe",
"description": "Extract recipe for cooking instructions",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the recipe"
},
"description": {
"type": "string",
"description": "Brief description of the dish"
},
"ingredients": {
"type": "array",
"items": {
"type": "string",
"description": "Name of ingredient"
}
}
},
"required": ["name", "description", "ingredients"]
}
}
}
}
]
}
```
------
#### [ Any ]
Utilizar `any` como opción de herramienta le permite asegurarse de que se llame al menos a una herramienta cada vez. Aunque la decisión de qué herramienta llamar se deja al modelo, siempre se devolverá una herramienta. En el siguiente ejemplo, se destaca el uso de la opción de herramienta “any” para un caso de uso de selección de punto de conexión de la API. Este es un ejemplo de cuándo resulta útil requerir que el modelo devuelva una herramienta específica.
```
tool_config = {
"toolChoice": {
"any": {}
},
"tools": [
{
"toolSpec": {
"name": "get_all_products",
"description": "API to retrieve multiple products with filtering and pagination options",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"sort_by": {
"type": "string",
"description": "Field to sort results by. One of: price, name, created_date, popularity",
"default": "created_date"
},
"sort_order": {
"type": "string",
"description": "Order of sorting (ascending or descending). One of: asc, desc",
"default": "desc"
},
},
"required": []
}
}
}
},
{
"toolSpec": {
"name": "get_products_by_id",
"description": "API to retrieve retail products based on search criteria",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Unique identifier of the product"
},
},
"required": ["product_id"]
}
}
}
}
]
}
```
------
#### [ Auto ]
El uso de `auto` como elección de herramientas es la funcionalidad predeterminada del soporte de herramientas y permite que el modelo decida cuándo llamar a una herramienta y a cuántas llamar. Este será el comportamiento si no incluye la elección de la herramienta en su solicitud.
**nota**
El comportamiento predeterminado de las llamadas a herramientas de Amazon Nova es utilizar la cadena de pensamiento para la selección de herramientas. Cuando se utiliza el comportamiento predeterminado o la opción de herramienta `auto`, también aparecerá el resultado del proceso de pensamientos en etiquetas .
En el siguiente ejemplo, se destaca un caso de uso de un chatbot en el que quizás quiera permitir que el modelo busque información reciente en Internet o que responda directamente al usuario. Esta elección de herramienta proporciona flexibilidad y permitirá que el modelo razone.
```
tool_config = {
"toolChoice": {
"auto": {}
},
"tools": [
{
"toolSpec": {
"name": "search",
"description": "API that provides access to the internet",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Query to search by",
},
},
"required": ["query"]
}
}
}
}
]
}
```
------
**nota**
Al configurar el parámetro de elección de herramienta, es posible que siga viendo el texto de salida del modelo o que realice llamadas de herramienta secuenciales después de la selección original de la herramienta. Le recomendamos que establezca aquí una secuencia de parada para limitar la salida solo a la herramienta:
```
“stopSequences”: [“”]
```
Para obtener más información, consulte [InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_InferenceConfiguration.html) en la guía de la API de Amazon Bedrock.
# Devolución de los resultados de la herramienta
Una vez que la aplicación haya invocado la herramienta, el último paso consiste en proporcionar el resultado de la herramienta al modelo. Esto se hace devolviendo un resultado de la herramienta con el ID de la llamada a la herramienta y el contenido de la respuesta. Este contenido sigue el esquema [ToolResultBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultBlock.html):
```
{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}],
"status": "success"
}
}
```
El contenido del `ToolResultBlock` debe ser un único JSON o una combinación de texto e imágenes.
El campo de estado se puede utilizar para indicar al modelo el estado de la ejecución de la herramienta. Si no se puede usar la herramienta, puede indicar el error, y Amazon Nova intentará modificar su llamada original a la herramienta.
Consulte la documentación de [ToolResultContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultContentBlock.html) para obtener más información sobre el esquema.
A continuación, se muestra un ejemplo de cómo utilizar la API de Converse para devolver los resultados de la herramienta:
```
messages.append({
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}],
"status": "success"
}
}
]
})
inf_params = {"maxTokens": 1000, "temperature": 0}
# Send the tool result to the model.
response = client.converse(
modelId="us.amazon.nova-lite-v1:0",
messages=messages,
toolConfig=tool_config,
inferenceConfig=inf_params
)
print(response['output']['message'])
```
Para obtener más información sobre cómo aprovechar las herramientas, consulte la documentación de [Uso de herramientas de Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html) o visite los [ejemplos de uso de herramientas](https://github.com/aws-samples/amazon-nova-samples/blob/main/multimodal-understanding/repeatable-patterns/10-tool-calling-with-converse/10_tool_calling_with_converse.ipynb) en el repositorio de muestras de Amazon Nova.
# Uso de herramientas integradas
Las herramientas integradas son herramientas completamente administradas que están disponibles de forma inmediata, sin necesidad de una implementación personalizada. Se pueden activar en la API de Converse con solo pulsar un botón.
## Intérprete de código
Intérprete de código permite a Nova poner en marcha código Python de forma segura en entornos de pruebas aislados. Esto permite escribir y poner en marcha código, analizar datos, crear visualizaciones y resolver problemas matemáticos. Por ejemplo, Intérprete de código se puede utilizar para lo siguiente:
+ Generar informes financieros basados en los datos subidos
+ Hacer análisis estadísticos completos o simulaciones de algoritmos
+ Poner en marcha scripts de migración de bases de datos en entornos aislados
+ Poner en marcha pruebas unitarias para el nuevo código generado
A continuación, se muestra un ejemplo de cómo activar Intérprete de código con la API de Converse:
```
{
"messages": [
{
"role": "user",
"content": [{"text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82")}]
}
],
"toolConfig": {
"tools": [
{
"systemTool": {
"name": "nova_code_interpreter"
}
}
]
},
```
En este caso, el modelo determinará que la solicitud requiere cálculo, por lo que genera el código Python requerido y llama a la herramienta de interpretación de código.
```
{
"toolUse": {
"input": {
"code": "'''Calculate the average of the given numbers.'''\nnumbers = [10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82]\nsum_numbers = sum(numbers)\ncount = len(numbers)\naverage = sum_numbers / count\n(sum_numbers, count, average)"
},
"name": "nova_code_interpreter",
"toolUseId": "tooluse_WytfF0g1S5qUeEPm0ptOdQ",
"type": "server_tool_use"
}
},
```
El intérprete pone en marcha este código en un entorno de pruebas y captura el resultado. Esta es la salida que se genera en un esquema estándar:
```
{
"stdOut": String,
"stdErr": String,
"exitCode": int,
"isError": boolean
}
```
En este caso, recibirá lo siguiente:
```
{
"toolResult": {
"content": [
{
"text": "{\"stdOut\":\"(1212, 12, 101.0)\",\"stdErr\":\"\",\"exitCode\":0,\"isError\":false}"
}
],
"status": "success",
"toolUseId": "tooluse_WytfF0g1S5qUeEPm0ptOdQ",
"type": "nova_code_interpreter_result"
}
}
```
## Protocolo de contexto para modelos
El protocolo de contexto para modelos (MCP) es un estándar abierto que permite a los desarrolladores crear conexiones bidireccionales seguras entre sus orígenes de datos y herramientas basadas en IA. En lugar de crear adaptadores personalizados para cada API o servicio, puede poner en marcha un servidor MCP y dejar que Nova detecte sus herramientas automáticamente por medio de un puente cliente. Una vez conectadas, Nova trata estas herramientas como cualquier otra integración externa: decide cuándo llamarlas, envía los parámetros necesarios e incorpora los resultados en su respuesta.
# Notificación de un error
Hay algunos casos en los que los parámetros seleccionados por Amazon Nova pueden provocar un error externo. En estos casos, puede resultar beneficioso comunicárselo a Amazon Nova para que la solicitud pueda modificarse y volver a intentarse. Para notificar los errores, devuelva igual el resultado de la herramienta, pero modifique el estado para informar del error y comparta el mensaje de excepción.
A continuación, se muestra un ejemplo que informa de un mensaje de estado de error:
```
tool_result_message = {
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool["toolUseId"],
"content": [{"text": "A validation exception occured on field: sample.field"}],
"status": "error"
}
}
]
}
```
## Referencias adicionales
1. [Uso de una herramienta para completar una respuesta del modelo](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)
1. [Creación de agentes de IA con Amazon Nova](agents.md)
1. [Prácticas recomendadas para peticiones de comprensión de textos](prompting-text-understanding.md)
1. [Solución de problemas de llamadas a herramientas](prompting-tool-troubleshooting.md)