Primeiros passos com a Realtime API

Crie um agente de voz de fala para fala com a Realtime API. O modelo trabalha diretamente com áudio, mantém o estado da conversa e pode chamar ferramentas. Este guia começa com o SDK de Agentes para um aplicativo no navegador; consulte os guias de conexão de baixo nível quando precisar de controle direto.

Para conversas full-duplex com um backend separado para tarefas delegadas, consulte GPT-Live. Para comparar arquiteturas de voz e pipelines encadeados, consulte Agentes de voz.

Crie um agente de voz de fala para fala

Use a Realtime API quando a interação precisar ser fluida como uma conversa e imediata. Esse é o melhor ponto de partida para agentes de voz que precisam permitir que o usuário interrompa a fala do agente, ter baixa latência até o início do áudio, alternar naturalmente os turnos de fala e usar ferramentas em tempo real.

O fluxo típico no navegador é:

1. O servidor do seu aplicativo cria um segredo de cliente efêmero para a sessão em tempo real.
2. Seu frontend cria uma RealtimeSession.
3. A sessão se conecta via WebRTC no navegador ou WebSocket no servidor.
4. O agente gerencia turnos de áudio, ferramentas, interrupções e transferências nessa sessão.

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 daí, adicione ferramentas, transferências e mecanismos de proteção ao RealtimeAgent da mesma forma que faria com um agente de texto. Mantenha o tratamento do transporte de áudio na camada de sessão e a lógica de negócio na definição do agente.

Comece pela documentação de transporte quando precisar de controle em um nível mais baixo:

• Visão geral de áudio e voz
• Realtime API com WebRTC
• Realtime API com WebSocket

Identificadores de segurança

Se seu aplicativo identifica usuários finais individualmente, inclua um identificador de segurança nas requisições à Realtime API. A OpenAI recomenda identificadores de segurança, mas não os exige. Eles ajudam a OpenAI a detectar comportamentos prejudiciais e a direcionar medidas de aplicação das políticas a um usuário específico, em vez de à organização inteira. Use um valor estável que preserve a privacidade, como um hash do ID interno do usuário.

Nas requisições à Realtime API, envie o identificador no cabeçalho OpenAI-Safety-Identifier. Ao usar tokens efêmeros, defina o cabeçalho na requisição feita pelo servidor que cria o segredo do cliente, para associar o identificador à sessão. Ao se conectar a partir de um servidor confiável com WebSocket ou com a interface unificada de WebRTC, defina o cabeçalho na requisição de conexão.

Identificadores de segurança não são transferidos de requisições à Responses API nem de outras sessões. Se você usa o parâmetro safety_identifier da Responses API em outra parte do aplicativo, passe o mesmo valor estável ao criar cada sessão em tempo real ou se conectar a ela.

Migração de beta para GA

Se você ainda tem uma integração beta com Realtime, migre para a interface GA antes de iniciar novos trabalhos. As mudanças mais importantes são:

• Remova o cabeçalho OpenAI-Beta: realtime=v1 ao chamar a interface GA.
• Use POST /v1/realtime/client_secrets para criar credenciais efêmeras para clientes de navegador ou dispositivos móveis.
• Use /v1/realtime/calls ao estabelecer sessões WebRTC.
• Atualize as estruturas de sessões e eventos para a interface GA. Em particular, defina session.type, mova a configuração de áudio de saída para dentro de session.audio.output e use os nomes mais recentes dos eventos de resposta, como response.output_text.delta, response.output_audio.delta e response.output_audio_transcript.delta.
• Se você está migrando um aplicativo de fala para fala, comece pelo exemplo para navegador. Se está migrando um fluxo de trabalho de transcrição, use Transcrição em tempo real.

Consulte a referência de eventos do cliente Realtime, a referência de sessões em tempo real e o exemplo para navegador para conhecer o fluxo atual da versão GA.

Próximos passos

• Gerenciamento de conversas: Configure sessões e processe áudio, texto e eventos.
• Detecção de atividade de voz: Configure a detecção automática de turnos de fala.
• Ferramentas e MCP: Adicione funções, servidores MCP e conectores.
• Criação de prompts para modelos de voz: Use o guia do seu modelo Realtime.
• Otimização de custos: Entenda a contabilização de uso e o armazenamento em cache na Realtime API.
• Controles do lado do servidor: Mantenha a execução de ferramentas e o controle de sessões no seu servidor.

Outros fluxos de trabalho de áudio

O seletor de fluxos de trabalho e o vocabulário compartilhado de áudio agora estão em Áudio e voz. Para tradução contínua, use Tradução ao vivo. Para legendas ao vivo, use Transcrição ao vivo; para áudio gravado, use Transcrição de arquivos.