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

Configurar a sessão com session.update

Aula 3 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Configure o seu agente de voz
  2. A estrutura completa de session.update
  3. As definições em detalhe
  4. Atualizar a sessão a meio da conversa
  5. Pontos-chave

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_detection definido apenas pelo seu type (com idle_timeout_ms opcional). 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ós session.created
  • O campo instructions define 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.update várias vezes para alterar o comportamento a meio da conversa