Ir al contenido principal
Español— Elegir un idioma
Menú

Llamadas a funciones por voz

Lección 13 de 16 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Ejecutar funciones desde una conversación de voz
  2. Declarar una función
  3. Recibir y gestionar una llamada a función
  4. Llamadas a funciones en paralelo
  5. Mejores prácticas
  6. Puntos clave

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.

1

El agente identifica la necesidad

El usuario dice algo que requiere una llamada a función. El agente genera los argumentos.

2

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.

3

Envías el resultado de vuelta

Envía conversation.item.create con el tipo function_call_output y el call_id.

4

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:

  1. Resuelve cada función antes de responder
  2. Envía cada resultado, con un conversation.item.create por resultado
  3. Envía un único response.create al 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.update con un esquema JSON para sus parámetros.
  • El resultado debe enviarse de vuelta mediante conversation.item.create con type: "function_call_output".
  • Envía siempre response.create después de remitir los resultados.
  • Para llamadas en paralelo, espera a todos los resultados antes de enviar un único response.create.