POST /v1/context.
Uma chamada
subject (um handle do cliente) ou object (um pedido, ticket ou fatura, como invoice:erp:0823), nunca os dois. about acrescenta o que uma conta ou parceiro tem de relevante; veja Contas e parceiros. A chamada é POST porque handle é dado pessoal e nunca vai na URL.
O que o agente recebe
Às 14h07, quando Marina liga, o agente de voz recebe isto antes do alô:As camadas
O contexto é organizado do que muda menos para o que muda mais. É isso que permite ao provedor de IA reaproveitar o começo do prompt entre conversas:
A seção “Do histórico” custa de 25 a cerca de 80 tokens e responde sozinha à pergunta mais comum, “isso já aconteceu antes?”. Quando a conversa pede mais, o agente usa a navegação do histórico.
Views
A view decide o formato e o orçamento do contexto:
As views de tarefa priorizam os objetos do tipo da tarefa, as pendências ligadas a eles e o que foi dito sobre eles. Cada espaço tem até 8 views de tarefa.
A resposta
No SDK de TypeScript,
ctx.text traz o corpo e ctx.suffix traz o live e o delta já formatados, para o fim do prompt, depois da conversa. path igual a holdout significa que o cliente está no grupo de controle de um experimento: o contexto vem vazio de propósito, e o SDK trata isso como resposta válida.
Fixado por conversa
Comconversation_id (ou task_id), o contexto fica fixado: os mesmos bytes em todos os turnos daquela conversa. O provedor de IA reaproveita o prefixo, e o SDK responde a maioria dos turnos do próprio cache, com revalidação em segundo plano. Mudança relevante, como uma pendência nova ou um nível de verificação mais alto, chega pelo delta ou por um context() novo, nunca por mudança silenciosa no meio da conversa.
Para saber se algo mudou sem baixar o texto, mande o known_etag que você já tem. Se nada mudou, a resposta é not_modified: true, sem texto. O SDK faz isso sozinho.
Ferramentas que já têm o id do perfil, como o seu serviço de governança, leem o mesmo contexto por GET /v1/context?profile_id=..., com os mesmos view, verification, conversation_id e task_id na query. Ali a condição é o cabeçalho If-None-Match de sempre, e um contexto sem mudança responde 304, sem corpo. Só o id do perfil vai nessa URL, nunca um handle.
Com delta: true, a resposta traz só o que mudou desde a última vez que esta fonte leu este cliente: dezenas de tokens em vez do contexto inteiro. Serve ao agente de voz e ao agente interno do mesmo jeito.
Modelo de destino e cache
target diz qual modelo vai ler o contexto, como {"provider": "openai", "model": "gpt-realtime"}. Provedores só guardam em cache prefixos acima de um piso, que varia de 512 a 4.096 tokens, e quem fica abaixo paga a entrada cheia sem aviso. Com o destino conhecido, a Niadra dimensiona o conjunto estável (as suas instruções, as regras e o cliente estável) para cruzar esse piso, acrescentando conteúdo útil de menor prioridade, e devolve em cache até dois pontos de quebra. Com destino desconhecido, o texto sai neutro. A economia de cache depende do provedor; a Niadra mede o acerto e mostra no Console.
O contexto é dado, não instrução. Todo contexto abre com essa frase, e o agente deve seguir o que o cliente disser quando divergir do que a memória sabe.
Próximos passos
Navegação do histórico
quando o contexto não basta.
Identidade e verificação
o que cada nível libera.
Ler o contexto
a referência completa de
POST /v1/context.