Agentes de voz

Los agentes de voz permiten a los usuarios hacer preguntas y completar tareas al hablar con tu aplicación. La principal decisión de diseño es cómo conectar la voz con el razonamiento y las herramientas. Puedes usar una conversación continua con un backend independiente, un solo modelo de voz o un flujo que controlas etapa por etapa.

Elige la arquitectura adecuada

Crea un agente de voz en dúplex completo

GPT-Live puede escuchar y hablar al mismo tiempo. Esta capacidad se conoce como dúplex completo. El modelo en tiempo real se encarga de la conversación por voz y delega el razonamiento y el uso de herramientas a un backend independiente. Los usuarios pueden seguir hablando mientras el backend procesa las tareas.

Puedes conservar tu flujo de trabajo de texto, con su lógica de negocio y sus herramientas, y agregar GPT-Live como interfaz de voz. El modo de delegación determina quién ejecuta las tareas del backend y quién proporciona el contexto de la conversación:

• Delegación al cliente: conecta tu propio agente o flujo de trabajo con el modelo de backend y el proveedor que elijas. Tu aplicación ejecuta las tareas y devuelve los resultados a GPT-Live.
• Delegación a Responses: elige un modelo de Responses alojado por OpenAI para el razonamiento y el uso de herramientas en el backend. GPT-Live proporciona el contexto de la conversación y gestiona las llamadas a ese modelo. Tu aplicación sigue ejecutando las funciones personalizadas.

En ambos modos, tu aplicación controla los permisos y los registros del negocio. Define cómo debe hablar el agente en el prompt del modelo en tiempo real y especifica las reglas de negocio en el prompt del backend.

Comienza con Primeros pasos con GPT-Live. Consulta Delegación y herramientas para configurar el backend y Prompts para modelos de voz para definir cómo debe hablar el modelo.

Crea un agente de voz a voz

Para empezar a usar la Realtime API desde el navegador, puedes usar un RealtimeAgent y una RealtimeSession. La sesión gestiona los turnos de voz, las herramientas, las interrupciones y las transferencias entre agentes. Ahora puedes encontrar el ejemplo inicial completo en Primeros pasos con la Realtime API.

Crea un flujo de voz encadenado

Usa un flujo encadenado cuando quieras inspeccionar o transformar el texto que pasa del reconocimiento de voz a tu agente y de ahí a la generación de voz. Tu aplicación gestiona tres etapas:

1. Conversión de voz a texto
2. El flujo de trabajo del agente
3. Conversión de texto a voz

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import asyncio
import numpy as np

from agents import Agent, function_tool
from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline


@function_tool
def get_weather(city: str) -> str:
    """Get the weather for a given city."""
    return f"The weather in {city} is sunny."


agent = Agent(
    name="Assistant",
    instructions="You are a helpful voice assistant.",
    model="gpt-6-astra",
    tools=[get_weather],
)


async def main() -> None:
    pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
    audio_input = AudioInput(buffer=np.zeros(24000 * 3, dtype=np.int16))
    result = await pipeline.run(audio_input)
    async for event in result.stream():
        if event.type == "voice_stream_event_audio":
            print("Received audio bytes", event.data.nbytes)


if __name__ == "__main__":
    asyncio.run(main())

Usa este enfoque cuando necesites observar o reemplazar cada etapa. Por ejemplo, puedes guardar la transcripción, verificar que se cumplan las políticas antes de que responda el agente de texto, hacer llamadas a sistemas internos y generar voz solo cuando el flujo de trabajo llegue a una respuesta aprobada.

Evalúa tu agente de voz

Evalúa tanto la conversación como el resultado de la tarea. Si pruebas un asistente para reservar citas, escucha la confirmación y comprueba que se haya guardado la cita correcta.

1. Elige escenarios representativos y define los resultados esperados, las llamadas a herramientas y los permisos para cada uno.
2. Guarda el audio, los eventos, los resultados de las herramientas y el estado de la aplicación que necesites para verificar cada resultado. Distingue entre una evaluación que falla al ejecutarse y una evaluación válida en la que el agente no logra completar la tarea.
3. Repite los escenarios y compara el grado de cumplimiento de las tareas, el tiempo que tarda en oírse la respuesta, las interrupciones y los silencios no deseados. Al comparar cambios, usa el mismo interlocutor, la misma configuración del modelo, las mismas herramientas y el mismo transporte.

En GPT-Live, evalúa los siguientes aspectos por separado:

• Resultados de las tareas y las herramientas: comprueba que se respete la intención del usuario y revisa las tareas delegadas, los argumentos de las herramientas, los permisos y el estado final de la aplicación. Verifica que las confirmaciones por voz coincidan con las acciones realizadas.
• Ritmo de la conversación: mide el tiempo que tarda en oírse la respuesta, los silencios no deseados, los momentos en que ambos hablan a la vez y la rapidez con que el agente cede la palabra cuando lo interrumpen. Incluye las correcciones que hace el usuario mientras el backend procesa las tareas.
• Voz e idioma: prueba el reconocimiento de voz con distintos acentos, ruido de fondo, cambios de idioma, nombres y números. Evalúa por separado el reconocimiento de voz, la claridad con que se entiende la respuesta y la elección del idioma de respuesta.
• Confiabilidad de la sesión: lleva un registro de las fallas de conexión, las pérdidas de audio, los tiempos de espera agotados y las sesiones incompletas por separado de las puntuaciones de las tareas.

Usa el método Gatear, caminar y correr para aumentar la complejidad por etapas:

1. Gatear: usa voz sintética para probar solicitudes controladas de un solo turno. Mantén constantes el audio generado, el contexto de la aplicación y el resultado esperado para poder repetir las comparaciones.
2. Caminar: reproduce grabaciones representativas de personas que hacen solicitudes de un solo turno para probar cómo influyen las voces, los micrófonos, las pausas y las condiciones acústicas en el comportamiento del agente.
3. Correr: usa un interlocutor simulado independiente para mantener conversaciones continuas de varios turnos. Prueba cómo maneja el agente las aclaraciones, los cambios de requisitos, las interrupciones y la reanudación de la conversación mientras el backend sigue trabajando.

Complementa las puntuaciones automatizadas con evaluaciones de personas que escuchen las conversaciones y valoren la pronunciación, la naturalidad y si el ritmo resulta adecuado.

Para obtener un arnés de ejecución para evaluar GPT-Live, consulta el ejemplo de evaluación de agentes de voz del Cookbook.

Para obtener un arnés de ejecución para evaluar Realtime y ver ejemplos resueltos, consulta la guía de evaluación de Realtime del OpenAI Cookbook.

Mide la latencia

Mide cuánto espera quien llama hasta escuchar una respuesta útil. Registra por separado el tiempo que tarda el backend para detectar demoras y compara la mediana y el percentil 95 entre llamadas similares.

Al comparar modelos de frontend, mantén constantes el interlocutor, la grabación, el modelo de backend, el prompt, el transporte, la cadencia del audio y el evaluador.

En GPT-Live, registra las etapas que tu aplicación puede observar: la recepción de la tarea delegada, el inicio de la solicitud al backend, el primer resultado útil, el inicio y el fin de la ejecución de la herramienta, el envío del resultado, la llegada del audio y su reproducción en el cliente. Con la delegación al cliente, tu aplicación puede observar directamente las solicitudes que hace al backend. Con la delegación a Responses, puede observar los eventos de respuesta anidados y las herramientas personalizadas que ejecuta.

Usa estos tiempos para detectar demoras al establecer la conexión, durante el procesamiento del modelo o la ejecución de las herramientas, al almacenar el audio en el búfer o al reproducirlo. Mide por separado el tiempo que tardan en oírse los avisos como “Estoy revisando” y el que tarda en oírse la respuesta que necesita quien llama.

Cambia un solo factor a la vez y repite los mismos escenarios. Comprueba si responder más rápido también afecta el éxito de la tarea, el uso correcto de las herramientas o las interrupciones. Consulta Reduce la latencia del backend.

Los agentes de voz usan los mismos componentes básicos que los demás agentes

La interfaz de voz cambia el transporte y el ciclo de entrada y salida de audio, pero las decisiones fundamentales del flujo de trabajo siguen siendo las mismas:

• Consulta Uso de herramientas cuando el agente de voz necesite capacidades externas.
• Consulta Ejecución de agentes cuando los flujos de trabajo por voz necesiten transmisión en tiempo real, continuidad de la ejecución o un estado persistente.
• Consulta Orquestación y transferencias entre agentes cuando los flujos de trabajo por voz se dividan entre varios agentes especializados.
• Consulta Medidas de protección y revisión humana cuando los flujos de trabajo por voz necesiten controles de seguridad o aprobaciones.
• Consulta Integraciones y observabilidad cuando necesites capacidades basadas en MCP o quieras examinar cómo se comportó el flujo de trabajo por voz.

En la práctica, elige primero la arquitectura de audio y luego diseña el resto del flujo de trabajo del agente como lo harías para texto.

Próximos pasos