Agentes de voz

O agente de voz tem menos tempo que qualquer outro agente. Quem liga ouve silêncio enquanto o prompt é montado, então o contexto precisa estar pronto antes da primeira palavra, e cada consulta durante a ligação precisa caber num turno falado. Este guia liga um agente de voz à Niadra do toque do telefone ao fim da chamada: contexto durante o toque, consultas ao histórico no tamanho da fala, os dados da chamada que provam quem está ligando, a transcrição em duas levas e o transbordo para um atendente. Seguimos a Marina Souza. Às 14h02 ela reclamou no WhatsApp que o técnico não apareceu. Às 14h06 o agente de cobrança lançou um crédito de US$ 40 na fatura 0823. Às 14h07 ela liga. O agente de voz atende sabendo das duas coisas.

O que o agente de voz recebe

A view voice é a view de canal mais curta. Traz quem está ligando, o que continua em aberto, o que outros agentes acabaram de fazer e os destaques do histórico que mudam a conversa, no tamanho certo para o agente ler antes de falar. O que aconteceu em outro canal depois da compilação chega em live e vai no fim do prompt.

Orçamento	Valor	Onde se ajusta
Tempo do `context()` na voz	150 ms	SDK `Timeouts.context_voice` / `contextVoice`
Tempo da navegação do histórico na voz	300 ms	SDK `navigation_voice` / `navigationVoice`
Tokens devolvidos por uma busca no histórico	300	`max_tokens=300`

O SDK tem o próprio tempo máximo, independente da plataforma de voz. Se o tempo acaba, a ligação segue e o agente fala com o que tem.

Passo a passo

1. Leia o contexto enquanto o telefone toca

Abra a conversa assim que a plataforma de voz avisar da chamada, e peça o contexto no mesmo tratador. Quando a ligação é atendida, o contexto já está no prompt. O número de quem liga é o sujeito; o id da chamada na plataforma é o seu conversation_id.

from niadra import Niadra, phone

niadra = Niadra(channel="voice")

def on_incoming_call(call):
    conversation = niadra.conversation(
        "call-4471",
        subject=phone(call.from_number),  # +14155550123
        view="voice",
        verification="V1",
    )
    ctx = conversation.context()
    call.agent.set_instructions(f"{AGENT_INSTRUCTIONS}\n\n{ctx.system_block}")
    return conversation

import { Niadra, handles } from "@niadra/sdk";

const niadra = new Niadra();

async function onIncomingCall(call: IncomingCall) {
  const conversation = niadra.conversation({
    subject: handles.phone(call.fromNumber), // +14155550123
    channel: "voice",
    conversation_id: "call-4471",
    verification: "V1",
  });
  const ctx = await conversation.context();
  await call.agent.setInstructions(`${AGENT_INSTRUCTIONS}\n\n${ctx.text}`);
  return conversation;
}

curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/context" \
  -H "Authorization: Bearer $NIADRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": { "type": "phone_e164", "value": "+14155550123" },
    "view": "voice",
    "verification": "V1",
    "conversation_id": "call-4471"
  }'

Com conversation_id, o servidor fixa o contexto: todo turno desta ligação recebe os mesmos bytes, e o provedor do modelo mantém o início do prompt em cache. O que muda durante a ligação (uma ação nova de outro agente, uma mensagem no WhatsApp) chega como delta e como turnos ao vivo. Em Python, acrescente ctx.turn_block no fim de cada turno; em TypeScript, acrescente ctx.suffix.

Em TypeScript, a conversa no canal voice usa a view voice por padrão. Passe target com o provedor e o modelo do seu agente de voz quando souber, para o contexto sair no tamanho certo para o cache daquele modelo.

2. Envie os dados da chamada

O nível de verificação é o que a ligação provou, nunca um palpite. O atestado de rede da operadora (STIR/SHAKEN e equivalentes) é o sinal mais forte que uma chamada traz antes de qualquer pergunta. Nível A vira V2; níveis B e C viram V1. Número oculto ou de PABX fica em V0 ou V1, e o agente identifica a pessoa na conversa. Mande os dados da chamada no bloco voice do primeiro evento. Uma ligação costuma ter dois ids, o da plataforma e o do tronco: coloque o segundo em conversation_aliases, para os dois apontarem para a mesma conversa.

conversation.customer(
    "Hi, it's Marina. The technician never showed up this morning.",
    conversation_aliases=["trunk-7f2a9"],
    voice={
        "ani": "+14155550123",
        "dnis": "+18005550100",
        "trunk": "sip-east-2",
        "network_attestation": "A",
        "answered_at": "2026-09-22T17:07:03Z",
        "turn_offset_ms": 2400,
    },
)

conversation.track({
  speaker: "customer",
  text: "Hi, it's Marina. The technician never showed up this morning.",
  conversation_aliases: ["trunk-7f2a9"],
  voice: {
    ani: "+14155550123",
    dnis: "+18005550100",
    trunk: "sip-east-2",
    network_attestation: "A",
    answered_at: "2026-09-22T17:07:03Z",
    turn_offset_ms: 2400,
  },
});

O nível efetivo é sempre o menor de três valores: o que você pediu, o teto da sua fonte e o que a conversa provou. Uma fonte de agente automatizado tem teto V2. A resposta diz o que aconteceu em verification.requested, verification.effective e verification.reason.

3. Deixe o agente consultar o histórico, no tamanho da fala

O contexto responde sozinho à pergunta mais comum: a seção “Do histórico” diz se aquilo já aconteceu e como foi resolvido. Quando a cliente fala de algo mais antigo, o agente busca. Amarre as ferramentas a quem está ligando no seu código, para o modelo escolher a consulta e nunca o cliente, e use o orçamento de voz.

kit = niadra.tools(phone("+14155550123"), conversation_id="call-4471", voice=True)

# Entregue kit.definitions ao seu modelo de voz; encaminhe as chamadas de ferramenta para cá:
output = kit.call("search_customer_history", {"query": "credit for missed technician visit"})

const kit = conversation.tools(); // amarrado a quem liga, orçamento de voz

// Entregue kit.definitions ao seu modelo de voz; encaminhe as chamadas de ferramenta para cá:
const output = await kit.call("search_customer_history", { query: "credit for missed technician visit" });

Uma busca feita numa conversa de voz devolve até 300 tokens, cortados por valor, com o bloco recurrence quando a consulta bate com uma categoria: “segunda visita perdida em 12 meses; na anterior, crédito de US$ 40”. Trecho literal de transcrição nunca vai para audiência de voz.

4. Registre o que o agente fala

Capture os turnos do agente à medida que acontecem. Chame mark_injected() (Python) ou markInjected() (TypeScript) toda vez que o contexto entrar no prompt: os próximos turnos e ações do agente passam a levar um context_stamp com o ETag daquele contexto e o momento em que entrou, e é assim que a medição do aproveitamento do contexto separa o contexto atrasado do contexto não usado. Se o seu agente usa o cliente da OpenAI, o wrap() dos dois SDKs injeta o contexto, carimba e registra as respostas por você.

ctx = conversation.context()
conversation.mark_injected(ctx)  # the pack went into this prompt
conversation.agent("Marina, I can see the $40 credit on your August bill was already applied at 2:06 pm.")

const ctx = await conversation.context();
conversation.markInjected(ctx); // the pack went into this prompt
conversation.agent("Marina, I can see the $40 credit on your August bill was already applied at 2:06 pm.");

5. Transfira para um atendente, com passagem de caso

Quando a cliente pede uma pessoa, registre a transferência antes de transferir. Com mode="warm", a mesa que recebe lê a view brief: uma passagem de caso curta, no tamanho de uma fala, que a sua plataforma pode sussurrar ao atendente. O atendente continua na ferramenta que a sua empresa já usa; o contexto chega a ela por API, webhook ou MCP.

conversation.handoff("human", target_source="src_service_desk", reason="asked for a person", mode="warm")

brief = niadra.context(subject=phone("+14155550123"), view="brief", conversation_id="call-4471")

await conversation.handoff({ target: "human", target_source: "src_service_desk", reason: "asked for a person", mode: "warm" });

const brief = await niadra.context({ subject: handles.phone("+14155550123"), view: "brief", conversation_id: "call-4471" });

Transferência cujo destino não lê o contexto em 10 minutos aparece como transferência sem leitura na medição.

6. Encerre a ligação e depois mande a transcrição final

Encerre a conversa no momento em que a ligação cai. Em Python, sair do bloco with já faz isso; você também pode chamar end(). A sessão fecha na hora, sem esperar a inatividade, e a memória derivada fica pronta em menos de um minuto.

niadra.track({
    "channel": "voice",
    "conversation_id": "call-4471",
    "handles": [phone("+14155550123")],
    "speaker": {"role": "system"},
    "kind": "system_event",
    "canonical_type": "call.ended",
    "voice": {"ended_at": "2026-09-22T17:11:40Z", "end_reason": "caller_hangup", "recording_ref": "rec_88213"},
})
conversation.end()

conversation.track({
  speaker: "system",
  kind: "system_event",
  canonical_type: "call.ended",
  voice: { ended_at: "2026-09-22T17:11:40Z", end_reason: "caller_hangup", recording_ref: "rec_88213" },
});
await conversation.end();

Plataformas de voz entregam em duas levas: a transcrição em tempo real durante a ligação e uma melhor depois dela. Mande a transcrição pós-chamada como eventos novos no mesmo conversation_id, com chaves de idempotência próprias. Dado tardio nunca é atualização: ele marca a conversa para uma extração nova, e o episódio ganha outra versão. Turnos com confiança de transcrição abaixo do limite não contam como pergunta nem como afirmação na medição.

O áudio nunca viaja dentro de um evento. Envie a gravação com upload_media() em Python ou uploadMedia() em TypeScript, passando quem ligou como subject, para que apagar o cliente apague também a gravação, e ponha o media_ref devolvido em voice.recording_ref ou em content.media_ref, com o SHA-256. Por HTTP, POST /v1/media/uploads devolve a URL e os upload_headers exatos que vão no PUT.

Próximos passos

O contexto e as views

camadas, fixação, turnos ao vivo e delta.

Identidade e verificação

como V0 a V4 são provados e limitados.

Navegação do histórico

busca, linha do tempo e abrir item, com orçamento.

Agentes de WhatsApp

o outro lado da mensagem das 14h02.

​O que o agente de voz recebe

​Passo a passo

​1. Leia o contexto enquanto o telefone toca

​2. Envie os dados da chamada

​3. Deixe o agente consultar o histórico, no tamanho da fala

​4. Registre o que o agente fala

​5. Transfira para um atendente, com passagem de caso

​6. Encerre a ligação e depois mande a transcrição final

​Próximos passos

O contexto e as views

Identidade e verificação

Navegação do histórico

Agentes de WhatsApp

O que o agente de voz recebe

Passo a passo

1. Leia o contexto enquanto o telefone toca

2. Envie os dados da chamada

3. Deixe o agente consultar o histórico, no tamanho da fala

4. Registre o que o agente fala

5. Transfira para um atendente, com passagem de caso

6. Encerre a ligação e depois mande a transcrição final

Próximos passos