Primeiros passos com a Realtime API

Crie um agente de voz que opere 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 criar um aplicativo que roda no navegador. Consulte os guias de conexão de nível mais baixo quando precisar controlar a conexão diretamente.

Para conversas full-duplex com delegação a um backend separado, consulte GPT-Live. Para comparar arquiteturas de voz e pipelines com etapas encadeadas, consulte Agentes de voz.

Crie um agente de voz que opere de fala para fala

Use a Realtime API quando a interação precisar ter a fluidez e a rapidez de uma conversa. Ela é o melhor ponto de partida para agentes de voz que precisam permitir que o usuário interrompa uma resposta, começar a responder em áudio com baixa latência, alternar a vez de falar de forma natural e usar ferramentas em tempo real.

No navegador, o fluxo geralmente segue estas etapas:

1. O servidor do aplicativo cria um segredo de cliente efêmero para a sessão Realtime.
2. O frontend cria uma instância de RealtimeSession.
3. A sessão se conecta via WebRTC no navegador ou via WebSocket no servidor.
4. Nessa sessão, o agente gerencia os turnos de fala, o uso de ferramentas, as interrupções e as transferências de controle 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,
});

Em seguida, adicione ferramentas, transferências de controle e mecanismos de proteção ao RealtimeAgent da mesma forma que faria com um agente de texto. Cuide do transporte de áudio na camada de sessão e mantenha a lógica de negócio na definição do agente.

Quando precisar de controle em um nível mais baixo, comece pela documentação de transporte:

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

Identificadores de segurança

Se o aplicativo identifica cada usuário final, inclua um identificador de segurança nas requisições à Realtime API. A OpenAI recomenda o uso desses identificadores, mas eles são opcionais. Com eles, a OpenAI pode detectar comportamentos nocivos e aplicar medidas apenas ao usuário envolvido, sem afetar toda a organização. Use um valor estável que preserve a privacidade, como o hash do ID interno do usuário.

Nas requisições à Realtime API, envie o identificador no cabeçalho OpenAI-Safety-Identifier. Se usar tokens efêmeros, defina o cabeçalho na requisição que o servidor envia para criar o segredo de cliente. Isso associa o identificador à sessão. Se a conexão partir de um servidor confiável e usar WebSocket ou a interface unificada de WebRTC, defina o cabeçalho na requisição de conexão.

A sessão não herda identificadores de segurança 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, envie o mesmo valor estável ao criar cada sessão Realtime ou ao se conectar a ela.

Migração da versão beta para a versão de disponibilidade geral (GA)

Se sua integração com a Realtime API ainda usa a versão beta, migre para a interface GA antes de iniciar novos desenvolvimentos. As principais mudanças 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 que rodam no navegador ou em 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 especial, defina session.type, mova a configuração do áudio de saída para 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 estiver migrando um aplicativo de fala para fala, comece pelo exemplo para navegador. Se estiver migrando um fluxo de transcrição, consulte Transcrição em tempo real.

Para ver o fluxo atual da versão GA, consulte a referência de eventos do cliente Realtime, a referência de sessões Realtime e o exemplo para navegador.

Próximos passos

• Gerenciamento de conversas: configure sessões e trabalhe com á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.
• Prompts para modelos de voz: consulte o guia do seu modelo Realtime.
• Otimização de custos: entenda como a Realtime API contabiliza o uso e como funciona o cache.
• Controles no servidor: mantenha a execução de ferramentas e o controle da sessão no servidor.

Outros fluxos de trabalho com áudio

Agora você encontra as orientações para escolher um fluxo de trabalho e os termos comuns aos fluxos de áudio em Áudio e voz. Para tradução contínua, consulte Tradução ao vivo. Para gerar legendas ao vivo, consulte Transcrição ao vivo. Para transcrever áudio gravado, consulte Transcrição de arquivos.