Modo de Voz Avançado

A API MKA1 fornece uma interface de voz em tempo real por meio do LiveKit. Este guia aborda como obter um token de sala, conectar-se a uma sessão de voz, enviar entrada de áudio e texto e capturar as respostas do agente.

Visão geral

A integração de voz consiste em três componentes principais:

Token de sala: Um JWT que concede acesso a uma sala LiveKit
Conexão LiveKit: Comunicação em tempo real baseada em WebRTC
Agente de voz: Processa entradas de áudio/texto e gera respostas faladas

O pipeline do agente funciona da seguinte forma:

STT (Speech-to-Text): O áudio é transmitido via WebSocket a 16 kHz e transcrito
LLM: O texto transcrito é processado pela API de Respostas MKA1
TTS (Text-to-Speech): A saída do LLM é sintetizada em áudio a 24 kHz

Toda solicitação que o agente de voz envia para a API de Respostas inclui automaticamente "voice_mode": "true" nos metadata da solicitação. Isso permite distinguir respostas originadas por voz das baseadas em texto ao revisar o uso ou o histórico de respostas.

Como obter um token de sala

Para iniciar uma sessão de voz, primeiro solicite um token de sala da API MKA1. O endpoint de token requer uma chave de API e opcionalmente aceita X-On-Behalf-Of para identificar usuários finais. Consulte Autenticação para mais detalhes.

mka1 llm speech livekit-token \
  --llm '{"model":"meetkai:functionary-pt","reasoning":{"effort":"none"}}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

import { SDK } from '@meetkai/mka1';

const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

const session = await mka1.llm.speech.livekitToken({
  xOnBehalfOf: 'user-123', // Opcional
  livekitTokenRequest: {
    llm: {
      model: 'meetkai:functionary-pt',
      reasoning: { effort: 'none', summary: null }
    }
  }
});

console.log(session.token);    // Token JWT
console.log(session.url);      // URL do WebSocket
console.log(session.roomName); // Nome da sala

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

var res = await sdk.Llm.Speech.LivekitTokenAsync(new LivekitTokenRequest()
{
    Llm = new MeetKai.MKA1.Types.Components.Llm()
    {
        Model = "meetkai:functionary-pt",
        Instructions = "Você é um assistente de voz útil.",
    },
});

Console.WriteLine(res.Token);    // Token JWT
Console.WriteLine(res.Url);      // URL do WebSocket
Console.WriteLine(res.RoomName); // Nome da sala

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

session = sdk.llm.speech.livekit_token(
    llm={"model": "meetkai:functionary-pt", "reasoning": {"effort": "none"}},
)

print(session.token)      # Token JWT
print(session.url)        # URL do WebSocket
print(session.room_name)  # Nome da sala

curl https://apigw.mka1.com/api/v1/llm/speech/livekit/token \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'X-On-Behalf-Of: user-123' \
  --data '{
    "llm": {
      "model": "meetkai:functionary-pt",
      "reasoning": { "effort": "none" }
    }
  }'

Parâmetros

O corpo da solicitação possui dois objetos de nível superior:

{
  "llm": { ... },   // Obrigatório — configuração do LLM
  "stt": { ... }    // Opcional — ajuste de reconhecimento de fala
}

`llm` — Configuração do LLM (obrigatório)

O objeto llm aceita os mesmos campos do corpo da solicitação da API de Respostas, exceto os campos gerenciados pelo agente de voz (input, stream, store, background).

Campo	Obrigatório	Descrição
`model`	Sim	Modelo LLM a ser usado (por exemplo, `auto`)
`instructions`	Não	Instruções de sistema personalizadas para o agente
`previous_response_id`	Não	Encadeie esta sessão a uma resposta específica de uma sessão anterior
`conversation`	Não	Continue uma conversa existente — passe `{ "id": "conv_abc123..." }` ou o ID da conversa como uma string
`tools`	Não	Array de definições de ferramentas (function, web_search, file_search etc.)
`tool_choice`	Não	Como o modelo seleciona ferramentas (`"auto"`, `"none"`, `"required"` ou uma ferramenta específica)
`parallel_tool_calls`	Não	Se deve permitir a execução paralela de ferramentas
`max_tool_calls`	Não	Número máximo de chamadas de ferramentas por resposta (padrão: 30)
`temperature`	Não	Temperatura de amostragem (por exemplo, `0.7`)
`max_output_tokens`	Não	Máximo de tokens na resposta
`reasoning`	Não	Configuração de raciocínio (por exemplo, `{ "effort": "high" }`). Defina `{ "effort": "none" }` para sessões de voz a fim de minimizar a latência — veja a observação abaixo.
`top_p`	Não	Parâmetro de amostragem por núcleo
`presence_penalty`	Não	Penalidade de presença para repetição de tokens
`frequency_penalty`	Não	Penalidade de frequência para repetição de tokens
`truncation`	Não	`"auto"` ou `"disabled"` — controla o truncamento de contexto
`context_management`	Não	Estratégias de gerenciamento de contexto para truncamento de conversas
`service_tier`	Não	`"auto"`, `"default"`, `"flex"` ou `"priority"`
`prompt`	Não	Referência a um modelo de prompt e suas variáveis
`text`	Não	Configuração de saída de texto (formato, detalhamento)
`metadata`	Não	Metadados de chave-valor transmitidos à API de Respostas

Não é possível especificar previous_response_id e conversation ao mesmo tempo.

Os metadados do token são incorporados em um JWT, que é transmitido como um cabeçalho HTTP. Mantenha a carga total de llm abaixo de aproximadamente 8 KB — arrays grandes de tools podem precisar ser reduzidos.

Para sessões de voz, desative o raciocínio definindo "reasoning": { "effort": "none" }. O raciocínio adiciona tempo de reflexão antes de o modelo responder, o que aumenta a latência e cria pausas perceptíveis na conversa. Desativá-lo mantém as respostas rápidas e naturais.

`stt` — Configuração de reconhecimento de fala (opcional)

Controla a detecção de atividade de voz (VAD) no servidor e o comportamento de detecção de fim de fala.

Campo	Obrigatório	Descrição
`silence_timeout_ms`	Não	Milissegundos de silêncio antes de finalizar a fala (100–5000)
`initial_silence_timeout_ms`	Não	Tempo limite antes de detectar qualquer fala (1000–30000)

Configuração avançada

Você pode transmitir ferramentas, instruções personalizadas e ajuste de STT em uma única solicitação de token:

mka1 llm speech livekit-token \
  --llm '{
    "model": "meetkai:functionary-pt",
    "instructions": "Você é um assistente de viagens útil. Seja conciso nas respostas de voz.",
    "temperature": 0.7,
    "tools": [
      { "type": "web_search", "user_location": { "country": "US" } },
      {
        "type": "function",
        "name": "book_flight",
        "description": "Reservar um voo para o usuário",
        "parameters": {
          "type": "object",
          "properties": {
            "origin": { "type": "string" },
            "destination": { "type": "string" },
            "date": { "type": "string" }
          },
          "required": ["origin", "destination", "date"]
        }
      }
    ],
    "tool_choice": "auto"
  }' \
  --stt '{"silence_timeout_ms":500,"initial_silence_timeout_ms":10000}'

const session = await mka1.llm.speech.livekitToken({
  livekitTokenRequest: {
    llm: {
      model: 'meetkai:functionary-pt',
      instructions: 'Você é um assistente de viagens útil. Seja conciso nas respostas de voz.',
      temperature: 0.7,
      tools: [
        {
          type: 'web_search',
          userLocation: { country: 'US' }
        },
        {
          type: 'function',
          name: 'book_flight',
          description: 'Reservar um voo para o usuário',
          strict: false,
          parameters: {
            type: 'object',
            properties: {
              origin: { type: 'string' },
              destination: { type: 'string' },
              date: { type: 'string' }
            },
            required: ['origin', 'destination', 'date']
          }
        }
      ],
      toolChoice: 'auto'
    },
    stt: {
      silenceTimeoutMs: 500,
      initialSilenceTimeoutMs: 10000
    }
  }
});

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

var res = await sdk.Llm.Speech.LivekitTokenAsync(new LivekitTokenRequest()
{
    Llm = new MeetKai.MKA1.Types.Components.Llm()
    {
        Model = "meetkai:functionary-pt",
        Instructions = "Você é um assistente de voz conciso.",
        Temperature = 0.6,
    },
    Stt = new SttConfig()
    {
        SilenceTimeoutMs = 500,
        InitialSilenceTimeoutMs = 3000,
    },
});

Console.WriteLine(res.Token);

session = sdk.llm.speech.livekit_token(
    llm={
        "model": "meetkai:functionary-pt",
        "instructions": "Você é um assistente de viagens útil. Seja conciso nas respostas de voz.",
        "temperature": 0.7,
        "tools": [
            {
                "type": "web_search",
                "user_location": {"country": "US"},
            },
            {
                "type": "function",
                "name": "book_flight",
                "description": "Reservar um voo para o usuário",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "origin": {"type": "string"},
                        "destination": {"type": "string"},
                        "date": {"type": "string"},
                    },
                    "required": ["origin", "destination", "date"],
                },
            },
        ],
        "tool_choice": "auto",
    },
    stt={
        "silence_timeout_ms": 500,
        "initial_silence_timeout_ms": 10000,
    },
)

curl https://apigw.mka1.com/api/v1/llm/speech/livekit/token \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "llm": {
      "model": "meetkai:functionary-pt",
      "instructions": "Você é um assistente de viagens útil. Seja conciso nas respostas de voz.",
      "temperature": 0.7,
      "tools": [
        {
          "type": "web_search",
          "user_location": { "country": "US" }
        },
        {
          "type": "function",
          "name": "book_flight",
          "description": "Reservar um voo para o usuário",
          "parameters": {
            "type": "object",
            "properties": {
              "origin": { "type": "string" },
              "destination": { "type": "string" },
              "date": { "type": "string" }
            },
            "required": ["origin", "destination", "date"]
          }
        }
      ],
      "tool_choice": "auto"
    },
    "stt": {
      "silence_timeout_ms": 500,
      "initial_silence_timeout_ms": 10000
    }
  }'

Resposta

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "url": "wss://apigw.mka1.com/api/v1/livekit",
  "roomName": "550e8400-e29b-41d4-a716-446655440000"
}

Campo	Descrição
`token`	Token de acesso JWT (TTL de 5 minutos) com permissões para entrar na sala, publicar e assinar
`url`	URL do WebSocket LiveKit ao qual se conectar
`roomName`	UUID gerado automaticamente para esta sessão

O token inclui metadados que o agente de voz usa para configurar a sessão.

Como continuar uma sessão

Para continuar a partir de uma resposta anterior:

mka1 llm speech livekit-token \
  --llm '{"model":"meetkai:functionary-pt","previous_response_id":"resp_abc123..."}'

const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

const session = await mka1.llm.speech.livekitToken({
  xOnBehalfOf: 'user-123', // Opcional, mas deve corresponder se a sessão original o utilizou
  livekitTokenRequest: {
    llm: {
      model: 'meetkai:functionary-pt',
      previousResponseId: 'resp_abc123...'
    }
  }
});

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

var res = await sdk.Llm.Speech.LivekitTokenAsync(new LivekitTokenRequest()
{
    Llm = new MeetKai.MKA1.Types.Components.Llm()
    {
        Model = "meetkai:functionary-pt",
        PreviousResponseId = "resp_abc123...",
    },
});

Console.WriteLine(res.Token);

session = sdk.llm.speech.livekit_token(
    llm={"model": "meetkai:functionary-pt", "previous_response_id": "resp_abc123..."},
)

curl https://apigw.mka1.com/api/v1/llm/speech/livekit/token \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'X-On-Behalf-Of: user-123' \
  --data '{
    "llm": {
      "model": "meetkai:functionary-pt",
      "previous_response_id": "resp_abc123..."
    }
  }'

Para continuar uma conversa existente:

mka1 llm speech livekit-token \
  --llm '{"model":"meetkai:functionary-pt","conversation":{"id":"conv_abc123..."}}'

const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

const session = await mka1.llm.speech.livekitToken({
  xOnBehalfOf: 'user-123', // Opcional, mas deve corresponder se a sessão original o utilizou
  livekitTokenRequest: {
    llm: {
      model: 'meetkai:functionary-pt',
      conversation: { id: 'conv_abc123...' }
    }
  }
});

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

var res = await sdk.Llm.Speech.LivekitTokenAsync(new LivekitTokenRequest()
{
    Llm = new MeetKai.MKA1.Types.Components.Llm()
    {
        Model = "meetkai:functionary-pt",
        Conversation = new ConversationRef() { Id = "conv_abc123..." },
    },
});

Console.WriteLine(res.Token);

session = sdk.llm.speech.livekit_token(
    llm={"model": "meetkai:functionary-pt", "conversation": {"id": "conv_abc123..."}},
)

curl https://apigw.mka1.com/api/v1/llm/speech/livekit/token \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'X-On-Behalf-Of: user-123' \
  --data '{
    "llm": {
      "model": "meetkai:functionary-pt",
      "conversation": { "id": "conv_abc123..." }
    }
  }'

Ao continuar uma sessão, a chave de API e o cabeçalho X-On-Behalf-Of (se usado) devem corresponder à sessão original. O agente de voz criptografa ambos no token de sala e os transmite a todos os serviços MKA1 downstream. Se não corresponderem, o agente não terá acesso ao contexto anterior.

Como conectar-se a uma sala

Depois de obter um token, use o SDK do LiveKit para conectar-se à sala.

import { Room, RoomEvent, Track } from 'livekit-client';

const room = new Room();

// Conectar-se à sala
await room.connect(session.url, session.token);

console.log('Conectado à sala:', room.name);

Como enviar entrada de áudio

O agente aceita entrada de áudio por meio da faixa de áudio da sala LiveKit. O áudio é processado a uma taxa de amostragem de 16 kHz.

import { createLocalAudioTrack } from 'livekit-client';

// Criar uma faixa de áudio local a partir do microfone
const audioTrack = await createLocalAudioTrack({
  echoCancellation: true,
  noiseSuppression: true,
  autoGainControl: true
});

// Publicar a faixa na sala
await room.localParticipant.publishTrack(audioTrack);

Comportamento de áudio

Detecção de atividade de voz (VAD): O VAD é tratado no servidor pelo agente MKA1, não localmente. O agente detecta automaticamente quando você para de falar e começa o processamento.
Taxa de amostragem: O áudio é transmitido a 16 kHz para o serviço STT.
Detecção de fim de fala: O agente usa detecção de fim de fala no servidor para determinar quando a fala termina. Não há atraso local de detecção de fim de fala.

Como enviar entrada de texto

Você também pode enviar mensagens de texto diretamente ao agente sem falar.

// Enviar uma mensagem de texto ao agente
const message = JSON.stringify({
  type: 'user_message',
  content: 'Qual é a capital da França?'
});

await room.localParticipant.publishData(
  new TextEncoder().encode(message),
  { reliable: true, topic: 'lk.chat' }
);

Como receber respostas do agente

O agente responde de três maneiras:

Saída de áudio: Fala sintetizada por meio de uma faixa de áudio
Transcrição: Texto do que o agente está dizendo (para legendas)
Metadados da resposta: ID da resposta e ID da conversa por meio do canal de dados

Como assinar a saída de áudio

import { RoomEvent, Track } from 'livekit-client';

room.on(RoomEvent.TrackSubscribed, (track, publication, participant) => {
  if (track.kind === Track.Kind.Audio && participant.identity !== room.localParticipant.identity) {
    // Esta é a saída de áudio do agente
    const audioElement = track.attach();
    document.body.appendChild(audioElement);
  }
});

Como receber transcrições

O agente publica transcrições de sua fala. Você pode usá-las para legendas ou registros.

room.on(RoomEvent.TranscriptionReceived, (segments, participant) => {
  for (const segment of segments) {
    console.log(`O agente disse: ${segment.text}`);
  }
});

Como receber metadados da resposta

O agente publica o response_id e o conversation_id (se aplicável) quando começa a gerar uma resposta. Salve o response_id para encadear sessões futuras usando previous_response_id.

room.on(RoomEvent.DataReceived, (payload, participant) => {
  if (participant.identity !== room.localParticipant.identity) {
    const data = JSON.parse(new TextDecoder().decode(payload));

    if (data.response_id) {
      console.log('ID da resposta:', data.response_id);
      console.log('ID da conversa:', data.conversation_id); // presente ao usar uma conversa
      // Salve response_id para encadear sessões futuras com previous_response_id
    }
  }
});

Continuidade de conversa

O agente oferece suporte a conversas com vários turnos e memória persistente. Cada resposta recebe automaticamente um response_id, enquanto as conversas devem ser criadas e gerenciadas explicitamente por meio da API de Conversas. Há duas formas de continuar uma conversa: llm.previous_response_id encadeia uma nova sessão a uma resposta específica. O agente recebe o contexto dessa resposta e de todas as respostas anteriores da cadeia. Use isto quando:

Você deseja continuar a partir de um ponto específico de uma conversa
Você está criando um fluxo de conversa linear
Você deseja criar uma ramificação a partir de uma resposta específica

llm.conversation faz referência a uma conversa criada pela API de Conversas. Use isto quando:

Você precisa gerenciar metadados da conversa (títulos, tags etc.)
Você deseja listar ou pesquisar conversas anteriores
Você está criando uma interface de chat com histórico de conversa persistente
Vários clientes precisam acessar a mesma conversa

Como iniciar uma nova sessão

import { Room, RoomEvent } from 'livekit-client';
import { SDK } from '@meetkai/mka1';

const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

// 1. Obter um token para uma nova sessão
const session = await mka1.llm.speech.livekitToken({
  xOnBehalfOf: 'user-123', // Opcional
  livekitTokenRequest: {
    llm: { model: 'meetkai:functionary-pt' }
  }
});

// 2. Conectar-se à sala
const room = new Room();
await room.connect(session.url, session.token);

// 3. Rastrear o ID da resposta quando o agente responder
let lastResponseId: string;
room.on(RoomEvent.DataReceived, (payload, participant) => {
  const data = JSON.parse(new TextDecoder().decode(payload));
  if (data.response_id) {
    lastResponseId = data.response_id;
  }
});

// 4. Ter uma conversa...
// 5. Desconectar ao terminar
room.disconnect();

Como continuar a partir de uma resposta anterior

Use previous_response_id para encadear uma nova sessão à última resposta, preservando o contexto da conversa:

// Use a mesma chave de API e X-On-Behalf-Of da sessão original
const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

// 1. Obter um novo token encadeado à resposta anterior
const session = await mka1.llm.speech.livekitToken({
  xOnBehalfOf: 'user-123', // Opcional, mas deve corresponder se a sessão original o utilizou
  livekitTokenRequest: {
    llm: {
      model: 'meetkai:functionary-pt',
      previousResponseId: lastResponseId
    }
  }
});

// 2. Conectar-se à nova sala
const room = new Room();
await room.connect(session.url, session.token);

// 3. O agente agora tem o contexto da sessão anterior
// Usuário: "O que eu perguntei antes?"
// Agente: "Você perguntou sobre a capital da França..."

Como continuar a partir de uma conversa

Use conversation_id para continuar uma conversa existente criada por meio da API de Conversas:

// Use a mesma chave de API e X-On-Behalf-Of da sessão original
const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

// 1. Obter um novo token com o ID da conversa
const session = await mka1.llm.speech.livekitToken({
  xOnBehalfOf: 'user-123', // Opcional, mas deve corresponder se a sessão original o utilizou
  livekitTokenRequest: {
    llm: {
      model: 'meetkai:functionary-pt',
      conversation: { id: conversationId }
    }
  }
});

// 2. Conectar-se à nova sala
const room = new Room();
await room.connect(session.url, session.token);

// 3. O agente agora tem o contexto de todo o histórico da conversa

Ao continuar uma conversa, a chave de API e o cabeçalho X-On-Behalf-Of (se usado) devem corresponder à sessão original. O contexto é limitado à identidade autenticada.

Como lidar com desconexões

Os tokens expiram após 5 minutos. Se precisar de sessões mais longas, implemente a lógica de reconexão:

room.on(RoomEvent.Disconnected, async () => {
  console.log('Desconectado da sala');

  // Obter um novo token (continuando a partir da última resposta)
  const newSession = await mka1.llm.speech.livekitToken({
    livekitTokenRequest: {
      llm: {
        model: 'meetkai:functionary-pt',
        previousResponseId: savedResponseId
      }
    }
  });

  // Reconectar
  await room.connect(newSession.url, newSession.token);
});

Exemplo completo

Aqui está um exemplo completo que reúne tudo:

import { Room, RoomEvent, Track, createLocalAudioTrack } from 'livekit-client';
import { SDK } from '@meetkai/mka1';

async function startVoiceSession(model: string = 'meetkai:functionary-pt') {
  const mka1 = new SDK({ bearerAuth: `Bearer ${YOUR_API_KEY}` });

  // Obter credenciais da sala
  const session = await mka1.llm.speech.livekitToken({ livekitTokenRequest: { llm: { model } } });

  // Criar e conectar-se à sala
  const room = new Room();

  let lastResponseId: string | undefined;

  // Processar saída de áudio do agente
  room.on(RoomEvent.TrackSubscribed, (track, publication, participant) => {
    if (track.kind === Track.Kind.Audio) {
      const audio = track.attach();
      document.body.appendChild(audio);
    }
  });

  // Processar transcrições
  room.on(RoomEvent.TranscriptionReceived, (segments) => {
    for (const segment of segments) {
      console.log('Agente:', segment.text);
    }
  });

  // Processar metadados da resposta
  room.on(RoomEvent.DataReceived, (payload, participant) => {
    const data = JSON.parse(new TextDecoder().decode(payload));
    if (data.response_id) {
      lastResponseId = data.response_id;
    }
  });

  // Conectar-se à sala
  await room.connect(session.url, session.token);

  // Capturar e publicar áudio do microfone
  const audioTrack = await createLocalAudioTrack({
    echoCancellation: true,
    noiseSuppression: true
  });
  await room.localParticipant.publishTrack(audioTrack);

  // O agente cumprimentará você automaticamente
  // Comece a falar para interagir!

  return { room, getLastResponseId: () => lastResponseId };
}

Tratamento de erros

Erros do endpoint de token

Eles são retornados como respostas HTTP ao solicitar um token de sala:

Erro	Causa	Solução
400 Bad Request	Parâmetro `llm.model` obrigatório ausente	Inclua `model` dentro do objeto `llm`
400 Bad Request	`previous_response_id` e `conversation` especificados	Use apenas um, não ambos
401 Unauthorized	Chave de API inválida ou ausente	Verifique se sua chave de API é válida

Erros na sessão

Durante uma sessão de voz ativa, o agente publica erros pelo canal de dados LiveKit. Escute-os junto com os metadados da resposta:

room.on(RoomEvent.DataReceived, (payload, participant) => {
  if (participant.identity === room.localParticipant.identity) return;

  const data = JSON.parse(new TextDecoder().decode(payload));

  if (data.error) {
    console.error(`[${data.error.service}] ${data.error.code}: ${data.error.message}`);
    // data.error.details pode conter informações adicionais de depuração
  }

  if (data.response_id) {
    lastResponseId = data.response_id;
  }
});

A estrutura da carga de erro:

{
  "error": {
    "code": "rate_limited",
    "message": "HTTP 429",
    "service": "llm",
    "details": "..."
  }
}

Campo	Descrição
`code`	Código de erro (veja a tabela abaixo)
`message`	Breve descrição do erro
`service`	Qual parte do pipeline falhou: `llm`, `stt` ou `tts`
`details`	Contexto adicional para depuração (opcional)

Códigos de erro:

Código	Serviço	Causa
`invalid_session`	—	Campos de metadados obrigatórios ausentes (`sub`, `llm`)
`auth_error`	—	Falha ao descriptografar credenciais do token de sala
`session_error`	—	O agente não conseguiu iniciar a sessão de voz
`invalid_request`	`llm`	Solicitação inválida à API de Respostas (HTTP 400)
`auth_error`	`llm`	Chave de API inválida (HTTP 401)
`access_denied`	`llm`	Permissões insuficientes (HTTP 403)
`rate_limited`	`llm`	Limite de taxa excedido (HTTP 429)
`service_error`	`llm`	Erro interno do servidor (HTTP 500)
`service_unavailable`	`llm`	Serviço upstream indisponível (HTTP 502/503)
`timeout`	`llm`	Tempo limite da solicitação excedido (HTTP 504)
`connection_error`	`llm`	Falha ao conectar-se à API de Respostas
`transcription_error`	`stt`	Falha no processamento de reconhecimento de fala
`speech_error`	`tts`	Falha na síntese de texto para fala

Erros de conexão

Problema	Causa	Solução
Tempo limite de conexão	Problemas de rede ou token inválido	Obtenha um token novo e tente novamente
Token expirado	A sessão ultrapassou 5 minutos	Obtenha um novo token com `previous_response_id` para continuar

Próximas etapas

Explore o endpoint de token LiveKit na referência da API
Saiba mais sobre a API de Respostas que alimenta o agente de voz
Revise os endpoints TTS e STT para casos de uso que não exigem tempo real

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Modo de Voz Avançado

Visão geral

Como obter um token de sala

Parâmetros

`llm` — Configuração do LLM (obrigatório)

`stt` — Configuração de reconhecimento de fala (opcional)

Configuração avançada

Resposta

Como continuar uma sessão

Como conectar-se a uma sala

Como enviar entrada de áudio

Comportamento de áudio

Como enviar entrada de texto

Como receber respostas do agente

Como assinar a saída de áudio

Como receber transcrições

Como receber metadados da resposta

Continuidade de conversa

Como iniciar uma nova sessão

Como continuar a partir de uma resposta anterior

Como continuar a partir de uma conversa

Como lidar com desconexões

Exemplo completo

Tratamento de erros

Erros do endpoint de token

Erros na sessão

Erros de conexão

Próximas etapas

​Visão geral

​Como obter um token de sala

​Parâmetros

​llm — Configuração do LLM (obrigatório)

​stt — Configuração de reconhecimento de fala (opcional)

​Configuração avançada

​Resposta

​Como continuar uma sessão

​Como conectar-se a uma sala

​Como enviar entrada de áudio

​Comportamento de áudio

​Como enviar entrada de texto

​Como receber respostas do agente

​Como assinar a saída de áudio

​Como receber transcrições

​Como receber metadados da resposta

​Continuidade de conversa

​Como iniciar uma nova sessão

​Como continuar a partir de uma resposta anterior

​Como continuar a partir de uma conversa

​Como lidar com desconexões

​Exemplo completo

​Tratamento de erros

​Erros do endpoint de token

​Erros na sessão

​Erros de conexão

​Próximas etapas

Visão geral

Como obter um token de sala

Parâmetros

`llm` — Configuração do LLM (obrigatório)

`stt` — Configuração de reconhecimento de fala (opcional)

Configuração avançada

Resposta

Como continuar uma sessão

Como conectar-se a uma sala

Como enviar entrada de áudio

Comportamento de áudio

Como enviar entrada de texto

Como receber respostas do agente

Como assinar a saída de áudio

Como receber transcrições

Como receber metadados da resposta

Continuidade de conversa

Como iniciar uma nova sessão

Como continuar a partir de uma resposta anterior

Como continuar a partir de uma conversa

Como lidar com desconexões

Exemplo completo

Tratamento de erros

Erros do endpoint de token

Erros na sessão

Erros de conexão

Próximas etapas