Construye un agente de voz completo
En esta página
Actualizado el 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 (sucesor:gpt-realtime-2.1-mini, que la guía de TTS de OpenAI indica que no es compatible con/v1/audio/speech: la migración de la síntesis de voz se traslada a la API en tiempo real);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 comunicación full-duplex de voz, GPT-Live 1 está disponible en la API desde el 10 de septiembre de 2026.
Corregido el 3 de noviembre de 2026. La transcripción de entrada utilizaba
gpt-live-transcribe, que solo funciona en una sesión de transcripción y no admite niserver_vadnisemantic_vad. En una sesión de conversación como esta, donde el VAD valida cada turno, la documentación especificagpt-transcribe, que transcribe los turnos validados y utiliza los turnos anteriores como contexto. Fuentes: Transcripción en tiempo real · GPT-Transcribe · GPT-Live-Transcribe.
Construye un agente de voz completo
Esta lección reúne todos los conceptos vistos hasta ahora para construir un agente de voz funcional de extremo a extremo. Crearás un asistente que escucha al usuario, comprende su solicitud, ejecuta acciones y responde por voz, todo en tiempo real mediante la API en tiempo real.
Arquitectura del agente
Cuatro módulos y, sobre todo, una restricción que impulsa toda la arquitectura: todo debe ocurrir a la vez. El micrófono captura mientras el modelo responde, los eventos llegan mientras se reproduce el audio y el usuario puede interrumpir en cualquier momento. Un agente de voz no es un bucle de pregunta y respuesta; es un sistema donde múltiples flujos avanzan en paralelo, razón por la cual dependemos en gran medida de asyncio en lo que sigue.
La clase VoiceAgent
La clase agrupa el estado que estos flujos paralelos deben compartir: la conexión, la sesión actual y la respuesta que se está reproduciendo en ese momento. Precisamente porque múltiples tareas acceden a este estado simultáneamente, un objeto es preferible a un conjunto de variables globales; cuando necesitas cancelar una respuesta en curso, debes saber que existe una.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Agente de voz completo basado en la API en tiempo real."""
def __init__(self, api_key: str, instructions: str, tools: list = None):
self.api_key = api_key
self.instructions = instructions
self.tools = tools or []
self.ws = None
self.is_playing = False
self.sample_rate = 24000
self.chunk_size = 2400 # 100 ms
async def connect(self):
"""Establece la conexión y configura la sesión."""
url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"
headers = {
"Authorization": f"Bearer {self.api_key}"
}
self.ws = await websockets.connect(url, additional_headers=headers)
# Esperar session.created
event = json.loads(await self.ws.recv())
print(f"Sesión: {event['session']['id']}")
# Configurar
await self.ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": self.instructions,
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000},
"transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"silence_duration_ms": 600
}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000},
"voice": "marin"
}
},
"tools": self.tools,
"tool_choice": "auto"
}
}))
await self.ws.recv() # session.updated
print("Agente de voz listo.")
async def start(self):
"""Inicia el agente de voz."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Módulo de captura de audio
async def _capture_audio(self):
"""Captura la entrada del micrófono y la envía a la API en tiempo real."""
loop = asyncio.get_event_loop()
queue = asyncio.Queue()
def callback(indata, frames, time_info, status):
pcm = (indata[:, 0] * 32767).astype(np.int16)
loop.call_soon_threadsafe(queue.put_nowait, pcm)
stream = sd.InputStream(
samplerate=self.sample_rate,
channels=1,
dtype="float32",
blocksize=self.chunk_size,
callback=callback
)
with stream:
while True:
pcm_data = await queue.get()
audio_b64 = base64.b64encode(pcm_data.tobytes()).decode()
await self.ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": audio_b64
}))
Módulo de procesamiento de eventos
async def _process_events(self):
"""Procesa todos los eventos del servidor."""
pa = pyaudio.PyAudio()
player = pa.open(
format=pyaudio.paInt16, channels=1,
rate=self.sample_rate, output=True
)
try:
async for raw in self.ws:
event = json.loads(raw)
t = event["type"]
if t == "response.output_audio.delta":
audio = base64.b64decode(event["delta"])
player.write(audio)
self.is_playing = True
elif t == "response.output_audio.done":
self.is_playing = False
elif t == "response.output_audio_transcript.delta":
print(event["delta"], end="", flush=True)
elif t == "input_audio_buffer.speech_started":
if self.is_playing:
await self.ws.send(json.dumps({
"type": "response.cancel"
}))
self.is_playing = False
elif t == "response.done":
await self._handle_response_done(event)
elif t == "error":
print(f"\nError: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Módulo de gestión de herramientas
Este módulo transforma al agente de un simple chatbot de voz a un asistente capaz de realizar acciones. La diferencia con la llamada a funciones clásica radica en la restricción de tiempo: el usuario está en la línea sin ningún indicador visual de progreso. Si la ejecución tarda más de uno o dos segundos, haz que el agente hable mientras trabaja («Déjame comprobarlo ahora mismo»), porque el silencio en una conversación de voz suena a fallo técnico.
async def _handle_response_done(self, event):
"""Gestiona las llamadas a funciones en la respuesta."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Nueva línea tras la transcripción
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Ejecutar la función (adaptar a tu lógica de negocio)
result = await self._execute_function(name, args)
await self.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
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Despacha la llamada a la función."""
# Implementar según tu lógica de negocio
return {"error": f"Función {name} no implementada"}
Lanzar el agente
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"Eres un asistente de voz para Corsen AI. "
"Ayudas a los usuarios a gestionar sus citas "
"y a obtener información sobre nuestros servicios. "
"Responde en francés, de forma concisa y profesional."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Comprueba la disponibilidad para un intervalo de tiempo",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Puntos clave
- Un agente de voz completo combina cuatro módulos: audio, sesión, herramientas y gestión del estado
- La clase
VoiceAgentencapsula toda la lógica tras una interfaz sencilla asyncio.gatherpermite la captura del micrófono y el procesamiento de eventos en paralelo- La gestión de interrupciones (cancelar una respuesta cuando el usuario habla) es esencial
- Las herramientas transforman al agente de un simple chatbot de voz a un asistente capaz de actuar