Configuración de herramientas
Amazon Nova 2 Sonic admite el uso de herramientas (también conocido como llamada a funciones), lo que permite al modelo solicitar información o acciones externas durante las conversaciones, como llamadas a la API, consultas a bases de datos o funciones de código personalizadas. Esto permite que el asistente de voz tome medidas, recupere información e integre servicios externos en función de las solicitudes de los usuarios.
Nova 2 Sonic incluye llamadas asíncronas a las herramientas, lo que permite a la IA seguir conversando de forma natural mientras las herramientas se ejecutan en segundo plano, lo que crea una experiencia de usuario más fluida y con mayor capacidad de respuesta.
A continuación se muestran pasos simplificados sobre cómo usar las herramientas:
-
Definición de herramientas: especifique las herramientas disponibles con sus parámetros en el evento promptStart.
-
Habla del usuario: el usuario hace una solicitud que requiere una herramienta (por ejemplo, “¿Qué tiempo hace en Seattle?”).
-
Invocación de la herramienta: Nova 2 Sonic reconoce la necesidad y envía un evento toolUse.
-
Ejecución de la herramienta: la aplicación ejecuta la herramienta y devuelve los resultados.
-
Generación de la respuesta: Nova 2 Sonic incorpora los resultados en su respuesta hablada.
En el siguiente diagrama, se ilustra cómo funciona el uso de herramientas:
Definición de herramientas
Las herramientas se definen con un esquema JSON que describe su propósito, los parámetros y las entradas esperadas.
A continuación se muestran los componentes y las explicaciones de la definición de herramientas:
-
Nombre: identificador único para la herramienta (utilice snake_case)
-
Descripción: explicación clara de lo que hace la herramienta, ayuda a la IA a decidir cuándo utilizarla
-
InputSchema: esquema JSON que define los parámetros que acepta la herramienta
-
Propiedades: parámetros individuales con tipos y descripciones
-
Obligatorio: conjunto de nombres de parámetros que se deben proporcionar
A continuación se muestra una definición sencilla de una herramienta de meteorologí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"] } } } }
La configuración de herramientas se pasa a Nova 2 Sonic en el evento promptStart junto con la configuración de la salida de audio y texto:
{ "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": {} } } } } }
Parámetros de elección de herramientas
Nova 2 Sonic admite tres parámetros de elección de herramientas para controlar cuándo y qué herramientas se utilizan. Especifique el parámetro toolChoice en la configuración de herramientas:
-
Automático (predeterminado): el modelo decide si se necesita alguna herramienta y puede llamar a varias herramientas si es necesario. Ofrece la máxima flexibilidad.
-
Cualquiera: garantiza que se llame al menos a una de las herramientas disponibles al inicio de la respuesta, pero el modelo seleccionará la más adecuada. Útil cuando tiene varias bases de conocimiento o herramientas y quiere asegurarse de que se utilice una.
-
Herramienta: obliga a llamar exactamente una vez a una herramienta específica al inicio de la respuesta. Por ejemplo, si especifica una herramienta de base de conocimiento, el modelo la consultará antes de responder, independientemente de si considera que es necesaria.
Ejemplos de elección de herramientas
Auto (valor predeterminado)
"toolChoice": { "auto": {} }
Cualquiera:
"toolChoice": { "any": {} }
Herramienta específica:
"toolChoice": { "tool": { "name": "get_weather" } }
Recepción y procesamiento de eventos de uso de herramientas
Cuando Amazon Nova 2 Sonic determina que se necesita una herramienta, envía un evento toolUse que contiene lo siguiente:
-
toolUseID: identificador único para la invocación de la herramienta -
ToolName: nombre de la herramienta que se ejecutará
-
Contenido: cadena JSON que contiene los parámetros extraídos de la solicitud del usuario
-
SessionID: identificador de la sesión actual
-
Rol: establecido en “HERRAMIENTA” para los eventos de uso de herramientas
Ejemplo de evento de uso de herramientas
{ "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>" } } }
Pasos de procesamiento
-
Reciba el evento toolUse de Nova 2 Sonic.
-
Extraiga el nombre y los parámetros de la herramienta del evento.
-
Ejecute la lógica de la herramienta (llamada a la API, consulta a la base de datos, etc.).
-
Devuelva el resultado mediante un evento toolResult.
Ejemplo de evento ToolResult
{ "event": { "toolResult": { "promptName": "<prompt-id>", "contentName": "<content-id>", "content": "{\"temperature\": 72, \"condition\": \"sunny\", \"humidity\": 45}" } } }
Prácticas recomendadas
-
Descripciones claras: escriba descripciones detalladas de las herramientas para ayudar a Nova 2 Sonic a entender cuándo se debe usar cada herramienta.
-
Validación de parámetros: valide siempre los parámetros de la herramienta antes de la ejecución para evitar errores. Defina los parámetros de la herramienta con un esquema JSON adecuado con tipos de datos estructurados (como enumeraciones, números o booleanos) en lugar de cadenas abiertas siempre que sea posible.
-
Gestión de errores: devuelve mensajes de error significativos en eventos toolResult cuando las herramientas fallan.
-
Ejecución asíncrona: aproveche las llamadas asíncronas a las herramientas para mantener el flujo de la conversación.
-
Denominación de herramientas: utilice nombres descriptivos y orientados a la acción (como get_weather, search_database, send_email).
