Criar um assistente de voz interativo
Nesta página
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:
- O utilizador clica no botão: começa a capturar áudio com
MediaRecorderouAudioWorklet - O áudio capturado é convertido para PCM em base64 e enviado para o Agente de Voz via WebSocket
- O VAD no lado do servidor deteta o fim da fala e gera uma resposta
- Os fragmentos de áudio da resposta chegam através de
response.output_audio.delta - 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.createpara personalizar a experiência - Uma saudação e feedback visual melhoram significativamente a experiência do utilizador