Configurar uma sessão de voz
Nesta página
Atualizado a 3 de novembro de 2026, com base na página Speech to Speech da xAI e no guia de prompts de voz. Fontes: Speech to Speech · Prompting Guide.
A mensagem que define tudo: session.update
Assim que a ligação WebSocket estiver estabelecida, nada acontece ainda. A mensagem session.update é o que confere personalidade ao agente: a voz que utiliza, as instruções que segue, como deteta as mudanças de turno e quais as ferramentas que pode acionar. Encare-a como o certificado de nascimento da sessão. Tudo o resto na conversa deriva desta configuração.
{
"type": "session.update",
"session": {
"instructions": "You are a professional voice assistant for an e-commerce company. Keep your answers short and help customers with their orders.",
"voice": "Ara",
"turn_detection": {
"type": "server_vad"
},
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
},
"tools": [
{ "type": "web_search" }
]
}
}
O servidor confirma a receção com um evento session.updated. Não precisa de enviar esta mensagem apenas uma vez. Pode reenviá-la a meio da conversa para alterar uma definição em tempo real, por exemplo, para mudar de voz quando a chamada transita das vendas para o apoio técnico, sem jamais interromper a ligação.
Escreva instruções para o ouvido, não para o olho
O campo instructions desempenha o papel do prompt de sistema. Utilize-o para definir a personalidade do agente (formal, informal, técnica), os tópicos que pode abordar, as restrições às suas respostas (comprimento, formato, idioma) e o contexto empresarial necessário: o nome da sua empresa, a gama de produtos e os procedimentos internos.
O problema é que o que funciona num prompt escrito muitas vezes falha num agente de voz. Se deixado à sua sorte, o modelo gera respostas de dez linhas. Lidas em voz alta, tornam-se arrastadas e o utilizador perde a atenção antes do fim. Por isso, peça explicitamente respostas curtas e diretas. Se a sua aplicação funciona num único idioma, especifique qual, caso contrário o agente pode mudar de língua para corresponder ao sotaque do interlocutor. E indique-lhe o que fazer quando não compreender: uma instrução como “faça uma pergunta de esclarecimento em vez de adivinhar” impede que um número de encomenda mal ouvido desencadeie uma pesquisa inútil. O guia de prompts de voz da xAI sugere até uma estrutura em cinco partes (papel e persona, objetivo, fluxo da conversa, limites e escalonamento, estilo de voz) e recomenda uma ou duas frases curtas por turno, a menos que o interlocutor peça mais detalhes.
Deteção de turno
O bloco turn_detection decide quem fala e quando, e a documentação da xAI fornece apenas duas definições para o efeito. A primeira é o type. No modo "server_vad", o servidor deteta autonomamente o fim de cada enunciado, confirma o áudio, inicia a resposta e gere as interrupções: tudo o que tem de fazer é enviar áudio com input_audio_buffer.append. A segunda definição, idle_timeout_ms, é opcional. Se o utilizador permanecer em silêncio durante esse número de milissegundos após uma resposta, o servidor solicita uma intervenção, repetindo o processo após cada novo silêncio da mesma duração.
{
"turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}
Não existe nenhum limiar de sensibilidade ou duração de silêncio para ajustar. Os parâmetros threshold, silence_duration_ms e prefix_padding_ms, que verá em exemplos escritos para a API Realtime da OpenAI, não constam na documentação da xAI.
Se o comportamento automático não lhe convier, defina o tipo como null e assuma o controlo. Caber-lhe-á então armazenar o áudio em buffer com input_audio_buffer.append, confirmar o turno explicitamente com input_audio_buffer.commit e acionar a geração com response.create. O modo manual é a escolha certa para uma interface de “carregar para falar” (push-to-talk) ou sempre que deseje um controlo preciso sobre quando o agente fala.
Escolha o formato de áudio adequado
O bloco audio define os formatos de entrada e saída de forma independente:
{
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
São aceites quatro tipos. Se não especificar nenhum, obterá PCM a 24.000 Hz:
| Tipo | Codificação | Taxas de amostragem |
|---|---|---|
audio/pcm | PCM Linear16, little-endian | 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz |
audio/pcmu | G.711 mu-law (telefonia norte-americana) | Apenas 8000 Hz |
audio/pcma | G.711 A-law (telefonia europeia) | Apenas 8000 Hz |
audio/opus | Opus, um pacote por mensagem | 24000 Hz |
O seu canal de entrega dita a escolha. Uma aplicação web num navegador funciona bem com PCM a 24.000 Hz, um bom equilíbrio entre qualidade percebida e largura de banda. Uma integração com telefone SIP não tem escolha: a rede transporta G.711 a 8.000 Hz, e forçar um formato de maior qualidade apenas adiciona uma conversão inútil.
Forneça ferramentas ao agente
O array tools lista o que o agente pode invocar durante a conversa, podendo misturar diferentes tipos na mesma sessão:
{
"tools": [
{ "type": "web_search" },
{ "type": "x_search", "allowed_x_handles": ["gaborit_music"] },
{
"type": "function",
"name": "get_order_status",
"parameters": {
"type": "object",
"properties": {
"order_id": { "type": "string" }
},
"required": ["order_id"]
}
}
]
}
Você fornece a caixa de ferramentas; o agente escolhe a ferramenta. À medida que a conversa avança, ele decide que uma pergunta sobre notícias exige uma pesquisa na web, enquanto um número de encomenda requer get_order_status. Assim, o seu trabalho consiste menos em orquestrar chamadas e mais em descrever cada ferramenta com clareza, para que o agente faça a escolha correta.
Pontos-chave
- A mensagem
session.updateconfigura a voz, as instruções, o VAD e as ferramentas - O VAD do lado do servidor (
server_vad) deteta os turnos e gere as interrupções;idle_timeout_msé a única definição disponível - O modo manual (
turn_detection.typedefinido comonull) oferece-lhe controlo preciso, por exemplo, com push-to-talk - Os formatos de áudio PCM, G.711 e Opus cobrem casos de uso tanto na web como em telefonia
- Pode alterar a configuração a meio da sessão sem interromper a ligação