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

Llamadas a funciones en tiempo real

Lección 4 de 18 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Llamadas a funciones en tiempo real
  2. Declaración de herramientas en la sesión
  3. El flujo de llamada a función
  4. Implementación del gestor de funciones
  5. Integración en el bucle de eventos
  6. Puntos clave

Actualización 2 de noviembre de 2026 — Modelos de audio. Varios modelos de este curso están obsoletos: tts-1, tts-1-hd y gpt-4o-mini-tts dejarán de funcionar el 6 de enero de 2027 (el sustituto indicado es gpt-realtime-2.1-mini, que la guía de TTS de OpenAI especifica que no es compatible con /v1/audio/speech: la migración de la síntesis de voz se traslada a la Realtime API); gpt-realtime, gpt-4o-realtime y los modelos de audio herederos el 20 de enero de 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe y /v1/audio/translations el 26 de febrero de 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Para la voz a dúplex completo, GPT-Live 1 está disponible en la API desde el 10 de septiembre de 2026.

Llamadas a funciones en tiempo real

La llamada a funciones en la Realtime API permite que tu agente de voz realice acciones concretas durante una conversación: consultar una base de datos, hacer un pedido o comprobar un estado. La mecánica es similar a la de la Responses API, pero adaptada al flujo de eventos de WebSocket.

Declaración de herramientas en la sesión

Declaras las herramientas en session.update, exactamente igual que las instrucciones y la voz. Cada herramienta es un esquema JSON que describe sus parámetros:

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Obtener el tiempo actual para una ciudad dada",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "Nombre de la ciudad"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Unidad de temperatura"
                }
            },
            "required": ["city"]
        }
    },
    {
        "type": "function",
        "name": "book_appointment",
        "description": "Reservar una cita",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {"type": "string", "description": "Fecha en formato AAAA-MM-DD"},
                "time": {"type": "string", "description": "Hora en formato HH:MM"},
                "service": {"type": "string", "description": "Tipo de servicio"}
            },
            "required": ["date", "time", "service"]
        }
    }
]

await ws.send(json.dumps({
    "type": "session.update",
    "session": {
        "type": "realtime",
        "output_modalities": ["audio"],
        "instructions": "Eres un asistente de voz. Usa las herramientas disponibles.",
        "audio": {"output": {"voice": "marin"}},
        "tools": tools,
        "tool_choice": "auto"
    }
}))

El flujo de llamada a función

Cuando el modelo decide llamar a una herramienta, la secuencia de eventos es la siguiente:

1

response.function_call_arguments.delta

Los argumentos de la función llegan mediante streaming, fragmento a fragmento.

2

response.function_call_arguments.done

Los argumentos están completos. Ahora puedes ejecutar la función.

3

conversation.item.create (tú)

Envías el resultado de la función de vuelta al modelo.

4

response.create (tú)

Pides al modelo que continúe su respuesta con el resultado.

Implementación del gestor de funciones

Aquí tienes un ejemplo completo de gestión de llamadas a funciones:

import json

# Registro de funciones disponibles
async def get_weather(city: str, unit: str = "celsius") -> dict:
    # Llamada a una API meteorológica real
    return {"city": city, "temperature": 22, "unit": unit, "condition": "sunny"}

async def book_appointment(date: str, time: str, service: str) -> dict:
    # Lógica de reserva
    return {"confirmed": True, "date": date, "time": time, "reference": "RDV-2026-0042"}

FUNCTION_REGISTRY = {
    "get_weather": get_weather,
    "book_appointment": book_appointment,
}

async def handle_function_call(ws, event):
    """Procesa una llamada a función y devuelve el resultado."""
    response = event["response"]

    for output in response.get("output", []):
        if output["type"] != "function_call":
            continue

        func_name = output["name"]
        call_id = output["call_id"]
        arguments = json.loads(output["arguments"])

        print(f"Llamando a la función: {func_name}({arguments})")

        # Ejecutar la función
        func = FUNCTION_REGISTRY.get(func_name)
        if func:
            result = await func(**arguments)
        else:
            result = {"error": f"Función desconocida: {func_name}"}

        # Enviar el resultado de vuelta al modelo
        await ws.send(json.dumps({
            "type": "conversation.item.create",
            "item": {
                "type": "function_call_output",
                "call_id": call_id,
                "output": json.dumps(result)
            }
        }))

    # Pedir al modelo que continúe con el resultado
    await ws.send(json.dumps({
        "type": "response.create"
    }))

Integración en el bucle de eventos

El gestor de funciones se integra en tu bucle principal:

async def event_loop(ws):
    """Bucle principal de procesamiento de eventos."""
    async for raw_message in ws:
        event = json.loads(raw_message)
        event_type = event["type"]

        if event_type == "response.done":
            response = event["response"]
            # Comprobar si el modelo ha llamado a alguna función
            has_function_calls = any(
                o["type"] == "function_call"
                for o in response.get("output", [])
            )
            if has_function_calls:
                await handle_function_call(ws, event)

        elif event_type == "response.output_audio.delta":
            # Reproducir el audio de respuesta
            audio_bytes = base64.b64decode(event["delta"])
            player.write(audio_bytes)

        elif event_type == "error":
            print(f"Error: {event['error']['message']}")

Múltiples llamadas a funciones

El modelo puede decidir llamar a varias funciones en una única respuesta. El campo output de response.done puede contener múltiples entradas de tipo function_call. Procesa todas ellas antes de llamar a response.create.

Puntos clave

  • Las herramientas se declaran en session.update usando un esquema JSON estándar
  • Los argumentos llegan mediante streaming a través de response.function_call_arguments.delta
  • Tras la ejecución, envía el resultado de vuelta mediante conversation.item.create con el call_id
  • Llama a response.create para que el modelo pueda formular su respuesta de voz con el resultado
  • Gestiona múltiples llamadas: el modelo puede invocar varias funciones a la vez