Primeros pasos con la Realtime API

Crea un agente de voz con interacción de voz a voz mediante la Realtime API. El modelo trabaja directamente con audio, mantiene el estado de la conversación y puede llamar a herramientas. Esta guía comienza con el SDK de agentes para una aplicación de navegador; usa las guías de conexión de más bajo nivel cuando necesites control directo.

Para conversaciones full-duplex con un backend delegado independiente, consulta GPT-Live. Para comparar arquitecturas de voz y flujos de procesamiento encadenados, consulta Agentes de voz.

Crea un agente de voz con interacción de voz a voz

Usa la Realtime API cuando la interacción deba sentirse como una conversación y ser inmediata. Es el mejor punto de partida para agentes de voz que necesitan admitir interrupciones, tener baja latencia hasta el primer audio, alternar turnos de forma natural y usar herramientas en tiempo real.

El flujo habitual en el navegador es el siguiente:

1. El servidor de tu aplicación crea un secreto de cliente efímero para la sesión de Realtime.
2. Tu frontend crea una RealtimeSession.
3. La sesión se conecta a través de WebRTC en el navegador o de WebSocket en el servidor.
4. El agente gestiona los turnos de audio, las herramientas, las interrupciones y las transferencias dentro de esa sesión.

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";

const agent = new RealtimeAgent({
  name: "Assistant",
  instructions: "You are a helpful voice assistant.",
});

const session = new RealtimeSession(agent, {
  model: "gpt-realtime-2.1",
});

await session.connect({
  apiKey: "ek_...(ephemeral key from your server)",
});

A partir de ahí, agrega herramientas, transferencias y medidas de protección al RealtimeAgent del mismo modo que lo harías con un agente de texto. Mantén los aspectos relacionados con el transporte de audio en la capa de sesión y la lógica de negocio en la definición del agente.

Comienza con la documentación de transporte cuando necesites control de más bajo nivel:

• Descripción general de audio y voz
• Realtime API con WebRTC
• Realtime API con WebSocket

Identificadores de seguridad

Si tu aplicación identifica a los usuarios finales de forma individual, incluye un identificador de seguridad en las solicitudes a Realtime API. OpenAI recomienda los identificadores de seguridad, pero no los exige. Ayudan a OpenAI a detectar comportamientos dañinos y a aplicar medidas a un usuario específico en lugar de a toda tu organización. Usa un valor estable que preserve la privacidad, como un hash del ID interno del usuario.

Para las solicitudes a Realtime API, envía el identificador en el encabezado OpenAI-Safety-Identifier. Cuando uses tokens efímeros, establece el encabezado en la solicitud del lado del servidor que crea el secreto del cliente para asociar el identificador con la sesión. Cuando te conectes desde un servidor de confianza mediante WebSocket o la interfaz unificada de WebRTC, establece el encabezado en la solicitud de conexión.

Los identificadores de seguridad no se transfieren desde las solicitudes a la API Responses ni desde otras sesiones. Si usas el parámetro safety_identifier de la API Responses en otra parte de tu aplicación, pasa el mismo valor estable cuando crees o conectes cada sesión en tiempo real.

Migración de beta a GA

Si todavía tienes una integración con la versión beta de Realtime, mígrala a la interfaz GA antes de continuar con nuevos desarrollos. Los cambios más importantes son:

• Elimina el encabezado OpenAI-Beta: realtime=v1 al llamar a la interfaz GA.
• Usa POST /v1/realtime/client_secrets para crear credenciales efímeras para clientes de navegador o dispositivos móviles.
• Usa /v1/realtime/calls al establecer sesiones WebRTC.
• Actualiza las estructuras de las sesiones y los eventos para la interfaz GA. En particular, configura session.type, mueve la configuración del audio de salida a session.audio.output y usa los nombres más recientes de los eventos de respuesta, como response.output_text.delta, response.output_audio.delta y response.output_audio_transcript.delta.
• Si estás actualizando una aplicación de voz a voz, parte del ejemplo para el navegador. Si estás actualizando un flujo de trabajo de transcripción, usa Transcripción en tiempo real.

Consulta la referencia de eventos del cliente de Realtime, la referencia de sesiones de Realtime y el ejemplo para el navegador para conocer el flujo actual de GA.

Siguientes pasos

• Gestión de conversaciones: configura sesiones y gestiona audio, texto y eventos.
• Detección de actividad de voz: configura la detección automática de turnos.
• Herramientas y MCP: agrega funciones, servidores MCP y conectores.
• Diseño de prompts para modelos de voz: usa la guía de tu modelo de Realtime.
• Optimización de costos: comprende cómo se contabiliza el uso y cómo funciona el almacenamiento en caché en Realtime.
• Controles del lado del servidor: mantén la ejecución de herramientas y el control de sesiones en tu servidor.

Otros flujos de trabajo de audio

El selector de flujos de trabajo y el vocabulario compartido de audio ahora se encuentran en Audio y voz. Para traducción continua, usa Traducción en vivo. Para subtítulos en vivo, usa Transcripción en vivo; para audio grabado, usa Transcripción de archivos.