Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Criar um assistente de voz interativo

Aula 10 de 14 Atualizada a 29 de julho de 2026 Intermediario
Nesta página
  1. Do protótipo ao assistente de voz em produção
  2. O assistente web no navegador
  3. O assistente móvel
  4. O quiosque interativo
  5. Padrões partilhados pelas três arquiteturas
  6. Pontos-chave

Do protótipo ao assistente de voz em produção

Já sabe como configurar uma sessão de Agente de Voz e gerar áudio com TTS. O que falta é montar esses blocos de construção num produto que resista ao contacto com utilizadores reais. Três arquiteturas surgem repetidamente (o navegador, o telemóvel e o quiosque interativo), e cada uma impõe restrições técnicas muito antes de a qualidade do modelo entrar em jogo.

O assistente web no navegador

Este é o ponto de partida mais comum: um botão de microfone numa aplicação existente, o utilizador fala e o assistente responde em voz alta. O ciclo técnico funciona assim:

  1. O utilizador clica no botão: começa a capturar áudio com MediaRecorder ou AudioWorklet
  2. O áudio capturado é convertido para PCM em base64 e enviado para o Agente de Voz via WebSocket
  3. O VAD no lado do servidor deteta o fim da fala e gera uma resposta
  4. Os fragmentos de áudio da resposta chegam através de response.output_audio.delta
  5. Descodifica-os e reproduz-os com AudioContext

O problema raramente surge neste ciclo; vem do próprio navegador. O Safari exige que o AudioContext seja criado dentro de um manipulador de eventos do utilizador. Crie-o no primeiro clique no botão do microfone, não quando a página carrega, caso contrário obterá um contexto suspenso e silêncio total. A política de reprodução automática aponta no mesmo sentido: nenhuma reprodução de áudio inicia sem uma interação prévia do utilizador, o que exclui uma saudação que toque automaticamente quando alguém aterriza na página. Para formatos de saída, atenha-se ao PCM ou MP3, já que os navegadores não conseguem reproduzir nativamente mulaw e alaw. E a chave da API nunca vai para o código do cliente: fica no seu servidor, e o navegador usa um token efémero em vez disso (lição 13).

A captura também precisa de ajustes:

const stream = await navigator.mediaDevices.getUserMedia({
  audio: {
    sampleRate: 24000,
    channelCount: 1,
    echoCancellation: true,
    noiseSuppression: true
  }
});

O cancelamento de eco e a supressão de ruído não são extras. Sem eles, o microfone capta a resposta do assistente a sair dos altifalantes, o VAD confunde-a com o utilizador a falar e o agente continua a interromper-se a si mesmo. Teste sempre sem auscultadores: é nessa configuração que o feedback aparece.

O assistente móvel

Com React Native ou Flutter, o princípio mantém-se, mas o ambiente torna-se mais exigente. Utilize as APIs de captura nativas (AVAudioEngine no iOS, AudioRecord no Android) em vez de uma abstração genérica: a qualidade do sinal de entrada afeta diretamente o reconhecimento. Implemente uma reconexão automática, pois o WebSocket cai assim que a aplicação passa para segundo plano, o que acontece no momento em que chega uma notificação durante uma conversa.

Duas coisas escapam frequentemente aos testes internos. A primeira é o roteamento de áudio: altifalante ou auricular, o comportamento esperado difere consoante o utilizador segura o telemóvel junto ao ouvido ou o pousa numa mesa. A segunda é o Bluetooth, cuja própria latência se soma à da rede e à do modelo; uma conversa que flui suavemente com o microfone integrado torna-se por vezes entrecortada com auriculares sem fios.

O quiosque interativo

Para um quiosque numa loja, numa receção de hotel ou numa galeria de museu, a restrição dominante torna-se o ambiente sonoro. Um microfone cardioide e direcional limita a captação à pessoa que está em frente do quiosque. Não conte com uma definição de sensibilidade para filtrar a multidão: a deteção de turno do Agente de Voz apenas expõe o seu type e idle_timeout_ms, sem nenhum limiar para aumentar. Quando o local é realmente ruidoso, como o átrio de uma estação de comboios ou uma feira profissional, o push-to-talk com um botão físico é mais fiável do que qualquer deteção automática.

Por fim, lembre-se de encerrar as sessões após dois a três minutos de inatividade. Caso contrário, um visitante que se afaste a meio da conversa deixa uma sessão aberta que consome os seus recursos e ocupa um dos seus slots simultâneos.

Padrões partilhados pelas três arquiteturas

O Agente de Voz mantém o histórico da conversa durante toda a sessão. Pode prepará-lo antes da primeira palavra injetando contexto útil, como a identidade do cliente autenticado ou uma encomenda em curso, com conversation.item.create:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "system",
    "content": [
      {
        "type": "text",
        "text": "The signed-in customer is Sarah Miller, customer number C-4521. She has an order in progress, CMD-8834."
      }
    ]
  }
}

O agente deixa então de pedir aos utilizadores informações que a sua aplicação já possui, o que poupa bons dez segundos em cada conversa.

Para fazer o assistente falar primeiro, insira uma mensagem inicial e acione depois a resposta:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [{ "type": "text", "text": "Hello" }]
  }
}

Um { "type": "response.create" } enviado logo a seguir aciona a saudação.

Resta o feedback visual, que costuma ser tratado por último, embora pese fortemente na sensação que o produto transmite. Mostre um indicador enquanto o agente está a falar (uma onda sonora, um avatar animado) e outro enquanto está a capturar áudio. Sem esse sinal, os utilizadores não sabem se devem falar, se estão a ser ouvidos ou se a aplicação bloqueou, e acabam por falar por cima do agente.

Pontos-chave

  • Três arquiteturas principais: web, móvel e quiosque, cada uma com as suas próprias restrições
  • O áudio no navegador requer cuidados (AudioContext do Safari, política de reprodução automática)
  • Preencha previamente o contexto da conversa com conversation.item.create para personalizar a experiência
  • Uma saudação e feedback visual melhoram significativamente a experiência do utilizador