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

Construye un agente de voz completo

Lección 14 de 18 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Construye un agente de voz completo
  2. Arquitectura del agente
  3. La clase VoiceAgent
  4. Módulo de captura de audio
  5. Módulo de procesamiento de eventos
  6. Módulo de gestión de herramientas
  7. Lanzar el agente
  8. Puntos clave

Actualizado el 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 (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-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 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 ni server_vad ni semantic_vad. En una sesión de conversación como esta, donde el VAD valida cada turno, la documentación especifica gpt-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.

Audio
Captura y reproducción
Sesión
WebSocket y configuración
Herramientas
Acciones de negocio
Estado
Gestión de la conversación

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 VoiceAgent encapsula toda la lógica tras una interfaz sencilla
  • asyncio.gather permite 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