Llamadas a funciones en tiempo real
En esta página
Actualización 2 de noviembre de 2026 — Modelos de audio. Varios modelos de este curso están obsoletos:
tts-1,tts-1-hdygpt-4o-mini-ttsdejarán de funcionar el 6 de enero de 2027 (el sustituto indicado esgpt-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-realtimey 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-transcribey/v1/audio/translationsel 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:
response.function_call_arguments.delta
Los argumentos de la función llegan mediante streaming, fragmento a fragmento.
response.function_call_arguments.done
Los argumentos están completos. Ahora puedes ejecutar la función.
conversation.item.create (tú)
Envías el resultado de la función de vuelta al modelo.
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.updateusando 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.createcon elcall_id - Llama a
response.createpara 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