Configurar a sessão com session.update
Nesta página
Atualizado a 3 de novembro de 2026, com base nas páginas Speech to Speech e Text to Speech da xAI: 28 vozes integradas e
turn_detectiondefinido apenas pelo seutype(comidle_timeout_msopcional). Fontes: Speech to Speech · Text to Speech.
Configure o seu agente de voz
Assim que a ligação WebSocket estiver estabelecida e tiver recebido o evento session.created, configure a sessão enviando uma mensagem session.update. É aqui que define o comportamento do seu agente de voz: a sua personalidade, a voz, as ferramentas que pode utilizar e a deteção de turnos de fala.
A estrutura completa de session.update
Eis um exemplo de configuração detalhado:
{
"type": "session.update",
"session": {
"instructions": "You are a professional voice assistant for a law firm. Answer concisely and precisely. Use a formal tone.",
"voice": "Rex",
"tools": [
{"type": "web_search"},
{
"type": "function",
"name": "look_up_case",
"description": "Looks up a client case by number",
"parameters": {
"type": "object",
"properties": {
"case_number": {
"type": "string",
"description": "Client case number"
}
},
"required": ["case_number"]
}
}
],
"turn_detection": {
"type": "server_vad"
},
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
As definições em detalhe
Instruções (prompt do sistema)
O campo instructions equivale ao prompt do sistema nas APIs de texto: define a personalidade, o contexto e as restrições do seu agente de voz. No entanto, a redação impõe uma restrição específica para a voz: a brevidade. Cada token do prompt é processado antes da primeira resposta, e um prompt extenso custa-lhe uma latência notável no momento em que a chamada se estabelece. Limite-se ao essencial e transfira os detalhes para a lógica da sua aplicação. Dentro desse orçamento apertado, três elementos merecem destaque. O tom (formal, amigável, técnico), pois o agente de voz encarna literalmente a sua marca no ouvido do cliente. O idioma: especifique-o («responda em inglês»), caso contrário, o agente poderá seguir o idioma do utilizador ou da pergunta. E os limites: o que o agente pode fazer e, acima de tudo, o que deve recusar ou transferir para um humano, porque, ao telefone, uma resposta fora do escopo é proferida antes de alguém a poder rever.
Voz
A definição voice aceita uma das 28 vozes integradas da xAI (a partir de 3 de novembro de 2026), partilhadas pelo agente de voz e pela síntese de texto em fala (text-to-speech), ou o ID de uma voz personalizada criada com a API Custom Voices. Os IDs de voz não distinguem maiúsculas de minúsculas: eve, Eve e EVE referem-se à mesma voz. Todas as vozes falam todos os idiomas suportados.
As cinco vozes originais, conforme descritas pela xAI:
- eve: enérgica e otimista, sotaque britânico
- ara: calorosa e amigável
- rex: confiante e clara
- sal: suave e equilibrada
- leo: autoritária e poderosa, sotaque britânico
Vinte e três vozes mais recentes juntam-se a elas: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora e liora. Pode obter a lista atualizada, com o tom e os casos de uso de cada voz, através de GET /v1/tts/voices ou na página Text to Speech da xAI.
Ferramentas
O array tools define as ferramentas que o agente pode invocar durante a conversa. Pode combinar vários tipos: pesquisa na web, pesquisa no X, funções personalizadas, coleções RAG e servidores MCP. As próximas lições abordam as ferramentas em pormenor.
Configuração de áudio
O objeto audio define os formatos de entrada e saída. Pode utilizar formatos diferentes para entrada e saída se a sua arquitetura o exigir (por exemplo, receber G.711 de um sistema telefónico e enviar PCM para um navegador).
Atualizar a sessão a meio da conversa
Pode enviar session.update várias vezes durante uma conversa. Isso permite-lhe alterar o comportamento do agente em tempo real:
// Alterar a voz a meio da conversa
ws.send(JSON.stringify({
type: "session.update",
session: {
voice: "Ara"
}
}));
// Adicionar outra ferramenta
ws.send(JSON.stringify({
type: "session.update",
session: {
tools: [
{ type: "web_search" },
{ type: "x_search" }
]
}
}));
A documentação da xAI suporta explicitamente alterações a meio da sessão para várias definições (idioma de transcrição, palavras-chave, substituições de pronúncia, transporte de áudio), e session.updated confirma-as: verifique-o para confirmar a configuração que foi aplicada.
Pontos-chave
session.updateé a primeira mensagem a enviar apóssession.created- O campo
instructionsdefine a personalidade e as restrições do agente - Estão disponíveis 28 vozes integradas (incluindo eve, ara, rex, sal e leo), além de vozes personalizadas
- A configuração de áudio e as ferramentas são personalizáveis
- Pode enviar
session.updatevárias vezes para alterar o comportamento a meio da conversa