> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Aproveitamento do contexto > A medição por agente e por fornecedor: uso, repetição, contradição e transferência sem leitura. Uma memória entregue e não usada não vale nada. A Niadra mede se cada agente usou o contexto que recebeu, por agente, por fornecedor e por canal. Só a memória consegue fazer isso: ela segura os dois lados da conta, o contexto entregue e a conversa que veio depois. A medição olha para o que o agente fez com o contexto. Ela nunca dá nota a fornecedor, nunca sugere prompt e nunca decide nada. ## Os quatro sinais | Sinal | O que significa | Como é detectado | O que não conta | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Aproveitamento** | O agente citou ou usou um item que recebeu: a visita perdida, o crédito de 40, a promessa anterior | Casamento determinístico entre os itens do manifesto da entrega e os turnos do agente (datas, valores e ids normalizados), mais as ações registradas na sessão | Item entregue e irrelevante para a tarefa conta como não usado, sem penalidade | | **Repetição** | Depois da entrega, o agente pediu um dado que já tinha naquele nível de verificação: nome, número de documento, número do pedido, motivo do contato | As perguntas extraídas da conversa, cruzadas com os itens e as categorias do manifesto | Pergunta de verificação exigida pela sua política; confirmação explícita de um valor entregue quando a fonte está marcada como "confirma antes de agir"; pergunta sobre item que a política reteve | | **Contradição** | O agente afirmou algo que um fato ou uma ação entregue desmente: "o crédito ainda está em análise" com a ação das 14h06 no contexto | As afirmações do agente conferidas contra os fatos e as ações entregues | Divergência com fato que não estava no contexto. Isso é falha de seleção, medida à parte, nunca atribuída ao agente | | **Transferência sem leitura** | A conversa passou para um humano ou outro agente, e quem recebeu não pediu contexto | Evento `handoff` sem comprovante da fonte de destino para aquela conversa em 10 minutos | Transferência para fonte que não está integrada. Ela aparece na cobertura | O que conta como entregue: o contexto, os turnos `live`, o `delta` e os itens devolvidos pela navegação do histórico, cada um com a hora da entrega, gravada nos comprovantes. Só é repetição a pergunta feita depois da entrega. Um item citado só conta como aproveitado se for pertinente ao turno, então recitar o contexto inteiro não infla o número. Em agentes internos, o aproveitamento é medido pela ação registrada, e a repetição aparece como não medida. ## Primeiro, a cobertura Dois contadores acompanham os sinais: * **Sessões sem contexto**: a fonte integrou `track`, mas nunca chamou `context()`. * **Contexto tardio**: o contexto chegou depois da primeira resposta do agente. O SDK carimba `context_injected_at` e `first_agent_turn_at` na conversa quando você usa `conversation()` e o turno `agent()`. Sem cobertura não há o que medir, e o número aparece como **não medido**, nunca como zero. Na API, uma taxa sem nada a medir vem `null`. Voz tem uma regra a mais. Turno do agente com confiança do reconhecimento de fala abaixo do limiar não gera pergunta nem afirmação. A primeira leva da transcrição, sem o texto do agente, fica como não medida, com o motivo `partial_transcript`, e a segunda leva mede de novo. O texto que o modelo do seu agente gerou, capturado pelo SDK, vale mais que a transcrição. ## Como roda A medição roda no mesmo caminho da extração, sem chamada extra de modelo de linguagem. As perguntas e as afirmações do agente saem da única chamada de extração que já existe; o cruzamento com o manifesto é determinístico. O resultado fica pronto junto com a memória derivada, em menos de um minuto depois do fim da sessão. Uma segunda fase roda 10 minutos depois do fim para ver se quem recebeu uma transferência leu o contexto. Tudo é recalculado quando o extrator muda de versão: a medição é dado derivado, nunca a fonte da verdade. ## Leia os números [`GET /v1/context-use`](/api/context-use) agrupa por qualquer um de `day`, `source_id` (o padrão), `vendor`, `channel`, `view` e `experiment_group`, repetindo `group_by`, e filtra por `since` e `until` (datas), `source_id`, `channel`, `view` e `experiment_group`. Pede uma pessoa do Console com o papel `analysis` ou `vendor`, ou uma chave de escopo `admin`. ```bash cURL theme={null} curl "https://acme-prod.us-east-1.api.niadra.com/v1/context-use?group_by=vendor&group_by=channel&since=2026-09-01&until=2026-09-22" \ -H "Authorization: Bearer $NIADRA_TOKEN" ``` ```python Python theme={null} import os import httpx response = httpx.get( "https://acme-prod.us-east-1.api.niadra.com/v1/context-use", params={"group_by": ["vendor", "channel"], "since": "2026-09-01", "until": "2026-09-22"}, headers={"Authorization": f"Bearer {os.environ['NIADRA_TOKEN']}"}, ) for bucket in response.json()["buckets"]: rate = bucket["usage_rate"] print(bucket["vendor"], bucket["channel"], rate and (rate["value"], rate["low"], rate["high"])) ``` ```typescript TypeScript theme={null} const url = new URL("https://acme-prod.us-east-1.api.niadra.com/v1/context-use"); for (const g of ["vendor", "channel"]) url.searchParams.append("group_by", g); url.searchParams.set("since", "2026-09-01"); url.searchParams.set("until", "2026-09-22"); const response = await fetch(url, { headers: { Authorization: `Bearer ${process.env.NIADRA_TOKEN}` } }); const { buckets } = await response.json(); ``` Cada grupo conta `sessions`, `deliveries`, `deliveries_used`, `questions`, `repeated`, `contradicted`, `transfers`, `transfers_unread`, `recontacts`, `late_deliveries`, `no_context` (sessões sem nenhuma leitura de contexto), `not_measured` e `selection_misses` (contradições de itens que o contexto não levava, que nunca são do agente). As taxas `usage_rate`, `repetition_rate`, `transfer_unread_rate` e `recontact_rate` vêm com `value`, os limites `low` e `high` de um intervalo de Wilson de 95% e a amostra `n`, e ficam `null` quando nada pôde ser medido, nunca zero. Para entender por que um número mudou, abra uma conversa com [Aproveitamento de uma conversa](/api/context-use-conversation): uma entrada por entrega, com os itens usados, as perguntas repetidas, as contradições, se chegou tarde e o manifesto contra o qual foi medida. Uma pessoa com o papel `vendor` só vê as fontes nomeadas no vínculo do papel dela, então um fornecedor nunca vê os números de outro. A Niadra nunca compara fornecedores em público. O que você faz com os números é decisão sua. ## Grupo de controle e recontato em 72 horas A medição explica; o recontato prova. Recontato é uma sessão iniciada pelo cliente até 72 horas depois do fim de outra, do mesmo perfil, na mesma categoria normalizada (ou em qualquer categoria, para a taxa geral). Contato ativo da sua empresa não conta. Para medir o efeito da memória, o seu espaço pode rodar um experimento: uma fração estável dos clientes, sorteada pelo HMAC do handle mais antigo de cada um, recebe a memória, e o restante forma o grupo de controle. O mesmo cliente fica no mesmo grupo em todos os canais e fornecedores. No grupo de controle, o `context()` devolve contexto vazio com `path: "holdout"` e a navegação volta vazia, enquanto a memória continua sendo construída para a comparação valer. O SDK trata `holdout` como contexto vazio, nunca como erro. Um manifesto sombra registra o que teria sido entregue, e é contra ele que a repetição do grupo de controle é contada. Sessões com promessa da empresa vencida, categoria regulada ou fonte marcada como crítica saem dos dois grupos e recebem a memória normalmente. Sessões do grupo de controle não são cobradas. ## Revisão por amostra O seu time confere a medição por amostra. [`GET /v1/review/queue`](/api/review-queue) entrega até 50 amostras de cada vez, com os fatos que a memória extraiu, os sinais que a medição achou e os padrões novos, mostrados com a máscara do papel de quem revisa. Quem revisa registra um veredito por item com [`POST /v1/review/{sample_id}/verdicts`](/api/review-verdicts): o `target` (`fact`, `signal` ou `trait`), o id dele e o veredito. O veredito é a única escrita de governança que só uma pessoa faz: pede uma pessoa do Console com o papel `review`, nunca uma chave de fonte. [`GET /v1/review/agreement`](/api/review-agreement) mostra quanto revisores e sistema concordam nos últimos `days` (90 por padrão), o número que diz se dá para confiar na medição. Um veredito nunca muda a memória sozinho: fato errado sai por uma [correção](/api/feedback), padrão errado por uma [retirada](/api/trait-retract). ## Uso O que o seu espaço consome vem de [`GET /v1/usage`](/api/usage), numa janela `since` e `until`, por `hour` ou `day`, e se quiser só para alguns valores de `metric`. Com `group_by=source`, cada linha nomeia a fonte, e você vê qual agente e qual fornecedor geraram as conversas e tarefas. Pede o papel `analysis` ou uma chave `admin`. Os totais cobrados do tenant inteiro estão na [API de controle](/api/control/usage). Sessões do grupo de controle não são cobradas. ## Privacidade A medição lê o que a célula já tem, e o resultado é sobre o agente, nunca sobre o titular. Atendentes humanos são agregados por fonte, fila ou equipe por padrão, nunca pelo id de quem atendeu; o detalhe por pessoa fica desligado, a menos que você o configure com a base legal registrada. Apagar um perfil remove as linhas de medição dele pela mesma linhagem. ## Próximos passos o registro de entrega para o qual cada sinal aponta. receba um aviso quando a taxa de repetição passar do seu limite. o endpoint de agregados em detalhe. capture os turnos para a medição ter o texto do agente.