Herramientas y llamada a funciones en voz
En esta página
Un agente que actúa, no solo habla
Un asistente de voz limitado a conversar choca pronto con un muro: responde educadamente a «¿Dónde está mi pedido?» sin saber nada al respecto. El verdadero valor del Agente de Voz reside en su capacidad para actuar en mitad de una conversación (consultar una base de datos, ejecutar una búsqueda web, llamar a una API empresarial o alcanzar un servidor MCP) y leer el resultado como si tal cosa.
Los cinco tipos de herramientas
La búsqueda web, en su forma más simple, no requiere parámetros:
{ "type": "web_search" }
El agente busca entonces en la web en tiempo real, lo que cubre preguntas factuales, noticias y cualquier dato que cambie con demasiada frecuencia para residir en un prompt.
La búsqueda en X funciona igual, con la opción de limitarla a ciertas cuentas:
{
"type": "x_search",
"allowed_x_handles": ["corsen_ai"]
}
El parámetro allowed_x_handles es opcional, pero cambia la naturaleza de la herramienta. Sin él, el agente busca en toda la plataforma; con él, el agente se convierte en un portavoz que solo cita tus publicaciones oficiales.
La búsqueda de archivos consulta colecciones de documentos vectorizados, como manuales, procedimientos y documentación de producto:
{
"type": "file_search",
"vector_store_ids": ["vs_abc123"],
"max_num_results": 10
}
Las funciones personalizadas abren la puerta a tus propios sistemas. Este es el tipo de herramienta que más usarás, y vale la pena declararla con cuidado:
{
"type": "function",
"name": "check_order",
"description": "Comprueba el estado de un pedido de cliente",
"parameters": {
"type": "object",
"properties": {
"order_number": {
"type": "string",
"description": "El número de pedido, con el formato CMD-XXXX"
}
},
"required": ["order_number"]
}
}
Puedes conectar un CRM, un ERP, un calendario o una base de datos interna de la misma manera. Por último, los servidores MCP dan acceso a herramientas estandarizadas mediante el Protocolo de Contexto de Modelo (Model Context Protocol), de modo que no tengas que reescribir una integración para cada servicio:
{
"type": "mcp",
"server_url": "https://mcp.example.com/sse",
"server_label": "Mi servidor MCP"
}
El ciclo completo de llamada a función
Cuando el agente decide llamar a una función, no la ejecuta: te pide a ti que lo hagas, y tu aplicación realiza el trabajo. Los argumentos llegan primero en flujo a través de response.function_call_arguments.delta. Luego, el evento response.function_call_arguments.done marca el final de la solicitud y te proporciona el call_id junto con los argumentos completos. Te corresponde ejecutar la función y devolver el resultado como un conversation.item.create de tipo function_call_output:
{
"type": "conversation.item.create",
"item": {
"type": "function_call_output",
"call_id": "call_abc123",
"output": "{\"status\": \"shipped\", \"delivery_date\": \"2026-04-05\"}"
}
}
Un último paso es esencial, y es el que la gente olvida: envía response.create para que el agente integre el resultado en su respuesta hablada. Sin ello, el resultado llega a la conversación, pero no ocurre nada. El usuario oye silencio y tú buscas el error donde no es.
Cuando se disparan varias funciones a la vez
El modelo puede muy bien decidir llamar a dos o tres funciones simultáneamente, por ejemplo, para comprobar un pedido y consultar el calendario de entregas. Recibirás entonces varios eventos function_call_arguments.done, cada uno con su propio call_id. Ejecútalos todos, en paralelo si es posible para que las latencias no se sumen, envía cada resultado en su propio conversation.item.create y manda un único response.create al final del todo. Un response.create por función desencadenaría tantas respuestas de voz competidoras, y el agente empezaría a hablarse a sí mismo.
// Recibir y ejecutar todas las funciones
const results = await Promise.all(
pendingCalls.map(call => executeFunction(call))
);
// Enviar todos los resultados
for (const result of results) {
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: result.callId,
output: JSON.stringify(result.data)
}
}));
}
// Activar la respuesta
ws.send(JSON.stringify({ type: "response.create" }));
Restricciones específicas de la voz
Lo que pasa desapercibido en una interfaz de texto se vuelve evidente en el habla, empezando por el tiempo. Nadie espera más de tres a cinco segundos en mitad de una conversación. Pasado ese umbral, los usuarios piensan que la línea se ha cortado y empiezan a hablar. Si tu función consulta un sistema lento, haz que el agente diga una frase de espera durante la llamada en lugar de dejar un silencio sepulcral.
El tamaño de los resultados importa tanto como el tiempo. El agente tiene que resumir en voz alta whatever que le des, y una lista de cuarenta pedidos produce bien un recital interminable o un resumen tosco. Devuelve datos estructurados, pero limítalos a lo esencial. Cuida también la descripción de cada función, ya que es lo único en lo que el modelo se basa para elegir: una descripción vaga como «gestiona pedidos» hace que dude o elija la herramienta equivocada. Y prevé el fallo. Cuando una función se cae, devuelve un mensaje de error explícito en output en lugar de nada; de lo contrario, el agente improvisará una respuesta sin saber que la llamada ha fallado.
Puntos clave
- El Agente de Voz admite cinco tipos de herramientas: búsqueda web, búsqueda en X, búsqueda de archivos, funciones y MCP
- Una llamada a función pasa por cuatro pasos: recibir los argumentos, ejecutar la función, devolver el resultado y activar la respuesta
- Las llamadas paralelas son posibles: ejecútalo todo, envíalo todo y luego manda un único
response.create - En voz, el tiempo de respuesta de la función es crítico: apunta a menos de 3 segundos