Agentes de voz

Los agentes de voz permiten que los usuarios hagan preguntas y completen tareas hablando con tu aplicación. La decisión clave de diseño es cómo conectar la voz con el razonamiento y las herramientas: una conversación continua con un backend separado, un único modelo de voz o un flujo de procesamiento 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, una capacidad llamada dúplex completo. El modelo en vivo se encarga de la interacción hablada y delega el razonamiento y el uso de herramientas a un backend separado. Los usuarios pueden seguir hablando mientras se ejecuta el trabajo en el backend.

Puedes conservar tu flujo de trabajo de texto actual, incluidas 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 el trabajo en el backend y proporciona el contexto de la conversación para ese trabajo:

• Delegación al cliente: conecta tu propio agente o flujo de trabajo con el modelo y el proveedor de backend que elijas. Tu aplicación ejecuta el trabajo 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 administra 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 el comportamiento al hablar en el prompt del modelo en vivo y las reglas de negocio en el prompt del backend.

Empieza con Primeros pasos con GPT-Live. Consulta Delegación y herramientas para configurar el backend y Diseño de prompts para modelos de voz para definir el comportamiento al hablar.

Crea un agente de voz a voz

Para Realtime API, un RealtimeAgent y una RealtimeSession ofrecen un punto de partida orientado al navegador. La sesión administra los turnos de audio, las herramientas, las interrupciones y las transferencias entre agentes. El ejemplo inicial completo ahora se encuentra en Primeros pasos con Realtime API.

Crea un flujo de trabajo de voz encadenado

Usa el enfoque encadenado cuando quieras inspeccionar o transformar el texto entre el reconocimiento de voz, tu agente y la generación de voz. Tu aplicación administra tres etapas:

1. Conversión de voz a texto
2. El flujo de trabajo del agente en sí
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", len(event.data))


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

Usa este enfoque cuando cada etapa deba ser visible o reemplazable. Por ejemplo, podrías almacenar la transcripción, verificar el cumplimiento de políticas antes de que el agente de texto responda, llamar a sistemas internos y generar voz solo después de que el flujo de trabajo llegue a una respuesta aprobada.

Evalúa tu agente de voz

Prueba por separado la calidad de la conversación y los resultados de las tareas. Una respuesta que suena natural no demuestra que se haya ejecutado una herramienta ni que haya cambiado el estado de la aplicación.

1. Elige escenarios representativos con resultados esperados, llamadas a herramientas y permisos.
2. Guarda el audio, los eventos, los resultados de las herramientas y el estado de la aplicación necesarios para verificar cada resultado. Distingue entre una ejecución de evaluación fallida y una ejecución válida en la que el agente no logra completar la tarea.
3. Repite los escenarios y compara la finalización de tareas, la latencia de la respuesta audible, las interrupciones y los silencios no deseados. Mantén constantes el interlocutor, la configuración del modelo, las herramientas y el transporte al comparar cambios.

Para GPT-Live, mide estas dimensiones de forma independiente:

• Resultados de tareas y herramientas: comprueba que se preserve la intención y revisa el trabajo delegado, los argumentos de las herramientas, los permisos y el estado final de la aplicación. Verifica que las confirmaciones habladas coincidan con las acciones completadas.
• Tiempos de la conversación: mide los tiempos de respuesta audible, los silencios no deseados, la superposición de voces y la cesión del turno ante interrupciones, incluidas las correcciones mientras se ejecuta el trabajo en el backend.
• Habla e idioma: prueba el reconocimiento de la entrada con distintos acentos, ruido de fondo, cambios de idioma, nombres y números. Evalúa la inteligibilidad de la salida y la elección del idioma por separado del reconocimiento.
• Confiabilidad de la sesión: registra los fallos 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 las etapas Gatear, caminar y correr para aumentar la complejidad de forma gradual:

1. Gatear: usa voz sintética para solicitudes controladas de un solo turno. Mantén fijos el audio generado, el contexto de la aplicación y el resultado esperado para que las comparaciones sean repetibles.
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.
3. Correr: usa un interlocutor simulado independiente para conversaciones continuas de varios turnos. Prueba las aclaraciones, los cambios en los requisitos, las interrupciones y la recuperación mientras la conversación y el trabajo en el backend ocurren en paralelo.

Complementa las puntuaciones automatizadas con la escucha humana para evaluar la pronunciación, la naturalidad y si el ritmo de la conversación se percibe como adecuado.

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

Para obtener un arnés de ejecución de evaluaciones de Realtime y ejemplos desarrollados, usa la guía de evaluación de Realtime en el OpenAI Cookbook. El Cookbook contiene las recetas de evaluación ejecutables; esta página proporciona la lista de verificación común para las pruebas.

Mide la latencia

Define un evento observable de inicio y uno de fin para cada métrica de latencia. El tiempo hasta la primera respuesta audible, hasta la delegación, hasta ceder el turno ante una interrupción, hasta la finalización del backend y hasta la finalización verificada de la tarea miden intervalos distintos. Usa una única escala de tiempo monotónica e informa la población que cumple los criterios de inclusión, la mediana y la latencia en la cola de la distribución. No sustituyas el tiempo de respuesta de extremo a extremo por una medición limitada al backend.

Mantén fijos el interlocutor, la grabación, el modelo del backend, el prompt, el transporte, la cadencia del audio y el evaluador al comparar modelos del frontend.

Para GPT-Live, registra las etapas que tu aplicación puede observar: recepción de la delegación, inicio de la solicitud al backend, primer resultado útil, inicio y fin de la herramienta, envío del resultado, llegada del audio y reproducción en el cliente. La delegación al cliente le da a tu aplicación visibilidad directa de sus solicitudes al backend; la delegación a Responses expone los eventos de respuestas anidadas y las herramientas personalizadas que ejecuta tu aplicación.

Usa los intervalos para localizar demoras en el establecimiento de la conexión, el trabajo del modelo, las herramientas, el almacenamiento en búfer de la aplicación y la reproducción. Mide la primera respuesta hablada útil por separado de un aviso como “Lo estoy revisando”. Un aviso más temprano no demuestra que el resultado solicitado haya llegado antes.

Cambia un factor a la vez y repite los mismos escenarios. Compara la mediana y la cola de la distribución del tiempo hasta las respuestas habladas útiles, junto con el éxito de las tareas, el funcionamiento correcto de las herramientas y las interrupciones. Consulta Reduce la latencia del backend para obtener orientación sobre la implementación.

Los agentes de voz siguen usando los mismos componentes fundamentales de los agentes

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

• Consulta Uso de herramientas cuando el agente de voz necesite capacidades externas.
• Consulta Ejecución de agentes cuando los flujos de trabajo de voz necesiten streaming, continuación o estado persistente.
• Consulta Orquestación y transferencias entre agentes cuando los flujos de trabajo de voz se ramifiquen entre especialistas.
• Consulta Medidas de protección y revisión humana cuando los flujos de trabajo de voz necesiten verificaciones de seguridad o aprobaciones.
• Consulta Integraciones y observabilidad cuando necesites capacidades basadas en MCP o quieras inspeccionar cómo se comportó el flujo de trabajo de voz.

La regla práctica es: elige primero la arquitectura de audio y luego diseña el resto del flujo de trabajo del agente de la misma manera que lo harías para texto.

Próximos pasos