Llamadas a funciones por voz
En esta página
Ejecutar funciones desde una conversación de voz
La llamada a funciones por voz permite que tu agente desencadene acciones reales durante una conversación: consultar una base de datos, realizar un pedido, enviar un correo electrónico o llamar a una API externa. El agente decide cuándo llamar a una función basándose en lo que dice el usuario.
El agente identifica la necesidad
El usuario dice algo que requiere una llamada a función. El agente genera los argumentos.
Tu aplicación ejecuta la función
Recibes los argumentos a través del evento function_call_arguments.done y ejecutas tu lógica de negocio.
Envías el resultado de vuelta
Envía conversation.item.create con el tipo function_call_output y el call_id.
El agente continúa la conversación
Envía response.create para que el agente integre el resultado en su respuesta hablada.
Declarar una función
Declaras las funciones en el array tools de session.update:
{
"type": "session.update",
"session": {
"tools": [
{
"type": "function",
"name": "get_balance",
"description": "Gets the balance of a customer's bank account",
"parameters": {
"type": "object",
"properties": {
"client_id": {
"type": "string",
"description": "Customer ID"
}
},
"required": ["client_id"]
}
}
]
}
}
Recibir y gestionar una llamada a función
Cuando el agente decide llamar a una función, recibes los argumentos como un flujo y, a continuación, todos juntos:
let functionArgs = "";
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "response.function_call_arguments.delta":
functionArgs += event.delta;
break;
case "response.function_call_arguments.done":
const args = JSON.parse(event.arguments);
const callId = event.call_id;
const functionName = event.name;
// Ejecutar la función
handleFunctionCall(functionName, args, callId);
break;
}
});
async function handleFunctionCall(name, args, callId) {
let result;
switch (name) {
case "get_balance":
result = await getBalance(args.client_id);
break;
default:
result = { error: "Unknown function" };
}
// Enviar el resultado de vuelta
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(result)
}
}));
// Pedir al agente que continúe
ws.send(JSON.stringify({
type: "response.create"
}));
}
Llamadas a funciones en paralelo
El agente puede decidir llamar a varias funciones a la vez. En ese caso, recibirás varios eventos function_call_arguments.done. La regla es:
- Resuelve cada función antes de responder
- Envía cada resultado, con un
conversation.item.createpor resultado - Envía un único
response.createal final
const pendingCalls = new Map();
let expectedCalls = 0;
case "response.function_call_arguments.done":
const result = await executeFunction(event.name, event.arguments);
pendingCalls.set(event.call_id, result);
if (pendingCalls.size === expectedCalls) {
// Cada función está resuelta
for (const [callId, output] of pendingCalls) {
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(output)
}
}));
}
// Un único response.create para todas las salidas
ws.send(JSON.stringify({ type: "response.create" }));
pendingCalls.clear();
}
break;
Mejores prácticas
- Descripciones claras: la calidad de las descripciones de tus funciones determina cuándo las usa el agente.
- Ejecución rápida: una función que tarda más de 2 o 3 segundos genera un silencio incómodo.
- Gestión de errores: devuelve un mensaje de error legible en lugar de una excepción técnica.
- Confirmación hablada: para acciones sensibles (pagos, eliminaciones), pide al usuario que las confirme antes de ejecutarlas.
Puntos clave
- La llamada a funciones por voz sigue un ciclo de cuatro pasos: detección, ejecución, devolución del resultado y continuación.
- Declaras las funciones en
session.updatecon un esquema JSON para sus parámetros. - El resultado debe enviarse de vuelta mediante
conversation.item.createcontype: "function_call_output". - Envía siempre
response.createdespués de remitir los resultados. - Para llamadas en paralelo, espera a todos los resultados antes de enviar un único
response.create.