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

Configurar uma sessão de voz

Aula 2 de 14 Atualizada a 3 de novembro de 2026 Intermediario
Nesta página
  1. A mensagem que define tudo: session.update
  2. Escreva instruções para o ouvido, não para o olho
  3. Deteção de turno
  4. Escolha o formato de áudio adequado
  5. Forneça ferramentas ao agente
  6. Pontos-chave

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:

TipoCodificaçãoTaxas de amostragem
audio/pcmPCM Linear16, little-endian8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz
audio/pcmuG.711 mu-law (telefonia norte-americana)Apenas 8000 Hz
audio/pcmaG.711 A-law (telefonia europeia)Apenas 8000 Hz
audio/opusOpus, um pacote por mensagem24000 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.update configura 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.type definido como null) 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