Lab 02 — Agente Realtime: workshop passo a passo
English · Índice dos workshops · ← Lab 01
Neste workshop você cria uma aplicação speech-to-speech real seguindo ações concretas: abra o terminal, crie o arquivo indicado, coloque o conteúdo completo, execute o checkpoint e só então avance.
Ao terminar, você terá uma aplicação Next.js que:
- cria um client secret Realtime curto no servidor;
- mantém
OPENAI_API_KEYfora do navegador; - conecta áudio e eventos por WebRTC;
- trata conexão, escuta, raciocínio, fala, mute e interrupção;
- oferece alternativa por texto e transcript em memória;
- encerra e limpa a sessão explicitamente;
- possui testes sem abrir uma sessão faturável;
- pode ser publicada com HTTPS.
Comece em 5 minutos
Se você já possui uma API key, microfone e cobrança ativa, execute a solução final:
git clone --depth 1 https://github.com/glaucia86/openai-voice-playground.git
cd openai-voice-playground/labs/lab-02-realtime-voice-agent
npm ci
cp .env.example .env.local
npm run dev
No Windows PowerShell, use Copy-Item .env.example .env.local. Preencha OPENAI_API_KEY= antes de iniciar, abra http://localhost:3000, leia o aviso de privacidade, use fones e encerre a sessão explicitamente. O teste real gera consumo da API.
Prefere construir?
- Com apoio (recomendado): use a branch starter e o primeiro checkpoint.
- Desde uma pasta vazia: abra o Capítulo 1 e escolha o caminho completo.
- Código final: consulte a implementação na
mainsem substituir seu trabalho.
Veja o resultado antes de construir
A gravação precisa mostrar consentimento, conexão, fala, interrupção, mute, mensagem de texto e encerramento com liberação do microfone. Ela será adicionada quando houver uma sessão controlada e sem dados pessoais.
Siga o roteiro seguro de gravação →Arquitetura em uma tela
O servidor usa OPENAI_API_KEY apenas para validar o pedido e emitir um client secret curto com no-store. O navegador usa esse segredo temporário para negociar a sessão WebRTC diretamente com a Realtime API; áudio e eventos ao vivo não passam continuamente pelo servidor Next.js. O client secret continua sendo uma credencial bearer: deve ser emitido somente quando necessário, não pode ser logado e não substitui autenticação, consentimento, quotas distribuídas e limites de sessão em produção.
Pergunta de compreensão: por que um client secret de 60 segundos reduz o risco, mas não transforma o navegador numa fronteira confiável?
Escolha como acompanhar
| Caminho | O que você faz | Recomendação |
|---|---|---|
| A — executar e investigar | clona a main e abre a solução final |
bom para conhecer Realtime primeiro |
| B — construir pelo starter | parte de uma base compilável e implementa cada fatia | recomendado para acompanhar o workshop |
| C — criar do zero | cria também pastas, configuração e dependências | bom para estudo aprofundado ou aula longa |
O guia de acompanhamento explica como preservar seu trabalho e consultar checkpoints sem usar comandos destrutivos.
Comece agora
- Prepare conta, terminal, microfone e projeto — Escolha o caminho, proteja a API key e prove que a base executa sem abrir uma sessão.
- Construa a aplicação arquivo por arquivo — Crie contrato, autorização, client secret, agente, WebRTC, estados, interface e testes com arquivos completos.
- Execute, diagnostique e publique — Rode os gates, faça um smoke test curto, diagnostique microfone/WebRTC e publique com HTTPS.
Para compreender as decisões antes ou depois da implementação, leia o artigo arquitetural do Lab 02. O artigo explica os porquês; os capítulos acima conduzem suas ações.
Starter recomendado
git clone --branch workshop/lab-02-v1-starter \
https://github.com/glaucia86/openai-voice-playground.git
cd openai-voice-playground
git switch -c minha-solucao-lab-02
npm ci --prefix labs/lab-02-realtime-voice-agent
npm run check:lab02
O primeiro gate deve passar sem API key, permissão de microfone ou sessão OpenAI. Depois, abra o Capítulo 1.
Checkpoints de recuperação
| Depois de concluir | Referência | Comparação |
|---|---|---|
| base inicial | workshop/lab-02-v1-starter |
ponto de partida |
| contrato da sessão | workshop/lab-02-v1-step-01-session-contract |
ver diff |
| autorização e client secret | workshop/lab-02-v1-step-02-authorization |
ver diff |
| conversa e interface | workshop/lab-02-v1-step-03-conversation |
ver diff |
Faça commit na sua branch antes de comparar. Checkpoints são referências de leitura, não atalhos para apagar sua implementação.
Antes de continuar, confirme que: você entende quando o microfone será ativado, sabe encerrar a sessão, escolheu uma rota e consegue distinguir a API key padrão do client secret curto.
Evidência final
npm run check:lab02
git status -sb
O primeiro comando executa lint, TypeScript, testes e build sem ligar microfone ou abrir conexão paga. O segundo deve confirmar que nenhum segredo ou artefato foi adicionado ao Git.