Primeros pasos con la Realtime API

Crea un agente de voz a voz con 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. Si necesitas controlar la conexión directamente, consulta las guías de conexión de más bajo nivel.

Para conversaciones en dúplex completo con un backend delegado independiente, consulta GPT-Live. Para comparar arquitecturas de voz y flujos de procesamiento en cadena, consulta Agentes de voz.

Crea un agente de voz a voz

Usa la Realtime API cuando la interacción deba sentirse como una conversación y la respuesta deba ser inmediata. Es el mejor punto de partida para los agentes de voz que necesitan permitir que el usuario interrumpa una respuesta, reproducir el primer fragmento de audio con baja latencia, alternar los turnos de forma natural y usar herramientas en tiempo real.

En el navegador, el flujo habitual 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 instancia de RealtimeSession.
3. La sesión se conecta mediante WebRTC en el navegador o mediante WebSocket en el servidor.
4. Dentro de esa sesión, el agente gestiona los turnos de voz, las herramientas, las interrupciones y las transferencias entre agentes.

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

const ephemeralKey = process.env.OPENAI_REALTIME_EPHEMERAL_KEY;
if (!ephemeralKey)
  throw new Error("Set OPENAI_REALTIME_EPHEMERAL_KEY from your server.");

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: ephemeralKey,
});

A continuación, agrega herramientas, transferencias entre agentes y mecanismos de protección al RealtimeAgent tal como lo harías con un agente de texto. Gestiona el transporte de audio en la capa de sesión y mantén la lógica de negocio en la definición del agente.

Si necesitas un control de más bajo nivel, comienza por la documentación sobre el transporte de audio:

• Introducción al audio y la voz
• Realtime API con WebRTC
• Realtime API con WebSocket

Identificadores de seguridad

Si tu aplicación identifica a cada usuario final, incluye un identificador de seguridad en las solicitudes a la Realtime API. OpenAI recomienda usar estos identificadores, aunque son opcionales. Ayudan a OpenAI a detectar conductas dañinas y a aplicar medidas al usuario responsable sin afectar a toda tu organización. Usa un valor estable que preserve la privacidad, como el hash del ID interno del usuario.

En las solicitudes a la Realtime API, envía el identificador en el encabezado OpenAI-Safety-Identifier. Si usas tokens efímeros, incluye el encabezado en la solicitud que envía el servidor para crear el secreto de cliente. Así, el identificador queda asociado a la sesión. Si te conectas desde un servidor de confianza mediante WebSocket o la interfaz unificada de WebRTC, incluye el encabezado en la solicitud de conexión.

Las sesiones de Realtime no heredan los identificadores de seguridad de las solicitudes a la Responses API ni de otras sesiones. Si usas el parámetro safety_identifier de la Responses API en otra parte de tu aplicación, envía el mismo valor estable al crear cada sesión de Realtime o al conectarte a ella.

Migración de la versión beta a la versión de disponibilidad general (GA)

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

• 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 móviles.
• Usa /v1/realtime/calls al establecer sesiones de WebRTC.
• Actualiza la estructura de las sesiones y los eventos para la interfaz GA. En particular, establece session.type, mueve la configuración del audio de salida a session.audio.output y usa los nuevos nombres de los eventos de respuesta, como response.output_text.delta, response.output_audio.delta y response.output_audio_transcript.delta.
• Si migras una aplicación de voz a voz, comienza con el ejemplo para el navegador. Si migras un flujo de trabajo de transcripción, consulta Transcripción en tiempo real.

Para conocer el flujo actual de la versión GA, consulta la referencia de eventos de cliente de Realtime, la referencia de sesiones de Realtime y el ejemplo para el navegador.

Próximos 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.
• Prompts para modelos de voz: usa la guía correspondiente a tu modelo de Realtime.
• Optimización de costos: conoce cómo se contabiliza el uso en Realtime y cómo funciona el almacenamiento en caché.
• Controles del lado del servidor: ejecuta las herramientas y controla las sesiones desde tu servidor.

Otros flujos de trabajo de audio

Ahora encontrarás el selector de flujos de trabajo y la terminología común de audio en Audio y voz. Para la traducción continua, consulta Traducción en vivo. Para generar subtítulos en vivo, consulta Transcripción en vivo. Para transcribir audio grabado, consulta Transcripción de archivos.