Engenharia de contexto: como decidimos o que o agente lê

Três falhas que pareciam burrice do modelo

Um agente fez uma pesquisa longa, chamou dezenas de ferramentas, tudo deu certo. E devolveu uma resposta vazia.

Outro respondeu com segurança um número que estava desatualizado. Parecia alucinação.

Um terceiro, rodando numa rotina agendada, terminou o trabalho pedindo autorização para continuar. Não havia ninguém do outro lado para autorizar.

As três situações aconteceram no OrganIA. Nas três, a pergunta óbvia era “qual modelo é melhor?” ou “subo o raciocínio?”. Nas três, a causa era outra.

O que o usuário viu	O que parecia	O que era
Resposta vazia depois de pesquisa bem-sucedida	Modelo fraco	Explosão de contexto: os resultados de ferramenta enterraram o próprio sinal, e perto do limite a saída degenera
Número velho apresentado como atual	Alucinação	Retrato antigo de painel no prompt, sem rótulo de idade. O modelo respondeu com o dado que estava ali, parecendo atual
Pedido de autorização para trabalho que ninguém ia ler	Comportamento estranho	Contexto de conversa numa execução sem conversa. A rotina herdou uma regra desenhada para o chat

Trocar de modelo teria custado mais e não resolveria nenhuma delas.

O terceiro caso ainda voltou por outra porta. O sistema já sabia distinguir rotina de conversa, mas o registro da rotina ainda não estava gravado quando a ferramenta foi ler, e a ausência foi lida como “é conversa”. Fato que outra parte do sistema precisa ler tem que estar gravado, não só pendente.

A tese: contexto é orçamento

Todo mundo discute qual modelo usar. O que decide a qualidade de um agente em produção é o que estava na frente do modelo no momento em que ele decidiu.

A janela de contexto não é memória. É orçamento.

Memória é algo que você preenche, e quanto mais, melhor. Orçamento é algo que você aloca. Cada token gasto com uma informação é um token que não está disponível para outra, e o que sobra é ruído que enterra o sinal. Tratar contexto como memória produz agentes que sabem tudo, custam caro e escolhem mal.

O anti-padrão que mais vejo, em todo lugar, é subir o esforço de raciocínio para resolver alucinação sobre dado. Quase sempre o problema é contexto (dado velho, ausente ou enterrado) ou ferramenta que não foi chamada. Pagar mais por token não conserta um dado que não estava lá.

Este artigo abre um dos quatro pilares do harness do OrganIA (contexto, ferramentas, ciclo e governança) e o transforma em método. Os números que cito foram medidos em runs reais da plataforma. Onde eu generalizo, aviso.

O ciclo de cinco operações

A forma comum de pensar contexto é “montar o prompt”: uma operação, no início. Isso descreve mal o que acontece. O contexto é recomposto a cada volta do agente, e cinco operações diferentes agem sobre ele.

fontes vivas ──(1 injetar)──(2 aterrar)──> contexto do turno ──> modelo ──> ferramentas
                                                 ▲                              │
                                                 │                  resultados voltam e crescem
                                                 │                              │
                                  (4 ponteiro no lugar) <── (3 comprimir) <── pressão de janela
                                                 │                              │
                                                 └──── leia primeiro ── (5 bancada)

1. Injetar, com condição, nunca por padrão. Cada bloco do prompt tem uma condição de entrada. Um agente simples recebe três blocos; um completo, catorze. Memória entra se existe gaveta para aquela pessoa. O catálogo visual entra se o modo visual está ligado. A ficha da pessoa entra se ela preencheu algo. O mesmo vale para ferramentas: grupos inteiros (reuniões, arquivos, Google, análise de dados) ficam fora da mesa até um sinal abrir. No Work Pilot, os esquemas de ferramenta caíram de 20.747 para 6.250 tokens por chamada.

Bloco novo nasce com condição. Se você não sabe dizer quando ele não deve entrar, ainda não entendeu o bloco.

2. Aterrar, com a semântica vinda da fonte viva. O que “atrasado” significa para um cliente é declarado na ferramenta e renderizado no prompt, a cada run, com o valor atual da configuração. Junto vai o inventário de conexões, com uma regra simples: uma conexão, use sem perguntar; várias, pergunte uma vez e lembre. Aterrar também é dizer de onde veio. Desde 12 de outubro, cada trecho de caderno chega ao modelo com uma linha de origem dizendo de que cliente é aquela reunião. O caso que motivou: objeções de venda de cinco reuniões, de cinco clientes diferentes, viraram “as objeções” de um só. O texto estava certo. A atribuição não.

3. Comprimir, só sob pressão real e sem destruir. Comprimir tem custo próprio: invalida o cache de prefixo do provedor. Comprimir cedo é pagar duas vezes. E remover resultado de ferramenta é remover trabalho que o modelo já fez, por isso a poda aqui grava antes de apagar.

4. Recuperar pelo ponteiro que fica no lugar. Quando a poda remove algo, deixa um texto substituto. Esse texto não é aviso. É a instrução que dirige a recuperação. Se aponta para o material bruto, o modelo recompra tudo. Se aponta primeiro para o registro destilado, ele lê o resumo e só desce ao bruto pelo detalhe que existe apenas lá.

5. Registrar fora do contexto. Em tarefa longa, o contexto é rascunho. O registro é a bancada, um arquivo markdown por conversa. Quem escreve nela é o harness, não o modelo: um destilador extrai para lá exatamente o que a compressão vai remover. Pedir ao modelo que registre não segura. Medimos isso, e volto ao número adiante.

O que não existe nesse desenho é uma seta em que a plataforma pede ao modelo que se comporte bem. Cada transição é executada pelo código.

Onde mora cada informação

A pergunta que aparece toda semana para quem constrói agente é: “o agente precisa saber X, onde eu ponho X?”. Responder “no prompt” é o reflexo mais comum e o mais caro, porque o prompt é reenviado a cada volta, para sempre.

Até agosto, a resposta era uma árvore de sete perguntas. Ela parou de servir quando a plataforma passou a guardar o que o agente sabe de cada pessoa. Hoje são catorze destinos, e a decisão tem duas etapas.

Etapa zero: um porteiro antes de gravar

Toda frase que o agente tenta guardar passa por cinco perguntas, feitas por código e não pelo modelo:

É cadência (“toda segunda às 8h, me mande os leads”)? Vai para agendamento. O porteiro recusa e oferece criar; nunca grava sozinho.
Redefine uma régua do agente (“urgente é P0”)? Vai para a configuração, que quem muda é o dono.
É forma de entrega sem escopo (tom, formato, idioma, como chamar a pessoa)? Vai para a ficha da pessoa. Campo vazio é preenchido; campo com outro valor, ele pergunta antes.
É jeito de trabalhar com escopo (“nos meus relatórios, resumo antes da tabela”)? Vira skill, e o agente pergunta se vale só para ela ou para todos.
Cita uma empresa que a casa conhece? Grava e sugere o Brain, que é da empresa. O funil só aponta, não escreve lá.

As regras são estreitas de propósito. “Entregamos o relatório toda sexta” é compromisso, não cadência, e vira memória.

A ficha nasceu de um conflito medido. Ela dizia “responda em tópicos” e o acervo de memórias dizia “responda em tabela”, os dois no mesmo prompt para a mesma pergunta. Deduplicar não resolvia: similaridade enxerga paráfrase, mas não enxerga versão nova da mesma ideia. “10 leads”, “5 leads” e “3 leads” da mesma rotina pontuavam abaixo de 0,55 entre si. Um campo tem um valor só por construção; duas frases contrárias são um estado legal do acervo.

Depois do porteiro: de quem é, e que forma tem

A primeira pergunta tem uma régua de uma frase: se eu trocar de agente, isto continua verdade? Se sim, é da pessoa e vale em todo agente que ela usa. Se não, é do agente.

Dono	Destinos
Empresa (o mesmo para todos)	Base de conhecimento, Brain, Live Apps
Agente (como ele trabalha)	Skill, semântica calibrada, memória do time
Pessoa (vale em todo agente dela)	Ficha, skill pessoal, memória da pessoa, caderno, pasta de trabalho
Run (morre com a tarefa)	Bancada, cache de resultado e conjunto de dados, contexto de tela, o próprio turno

Antes dessa coluna da pessoa existir, tudo que o agente sabia de alguém ficava preso ao agente onde tinha sido dito. Medido antes da mudança: o agente de suporte alcançava 13% do que a pessoa já tinha dito a outros agentes, e nenhuma das 18 memórias de assunto.

O caso difícil é distinguir cache de resultado e pasta de trabalho, porque os dois “guardam coisa grande”. A diferença é de dono. Cache é entulho de máquina: o sistema escreve, invisível ao agente, sem cota, vale 24 horas. Pasta é produto de trabalho: durável, por pessoa, com cota. Avaliamos unificar e rejeitamos, porque a cota da pasta desligaria em silêncio a garantia de que a poda é recuperável. Chamar os dois de “scratchpad” foi o que criou a confusão. O nome único escondia dois contratos.

Ordem é custo: o cache de prefixo

Uma decisão que quase ninguém trata como decisão é a ordem dos blocos no prompt.

Provedores cobram menos por trechos que já viram, e o desconto vale até o primeiro caractere diferente. Um bloco com data e hora no topo invalida tudo que vem depois, a cada minuto. No fim, invalida só a si mesmo.

O bloco que muda mais rápido vai por último.

Essa regra ninguém descobre lendo documentação de modelo. Aparece quando você olha a própria fatura bloco por bloco.

Validamos com uma sonda que compara byte a byte os pedidos consecutivos do loop. A montagem é append-only: 100% do pedido anterior vira prefixo do seguinte. Quando a poda dispara, preserva 77% do prefixo. O aproveitamento real medido é de 76% dos tokens de entrada no chat e de 40% a 58% nas rotinas agendadas.

Uma confissão sobre esse número: versões anteriores da nossa documentação citavam 68%. Era uma linha de base com defeito de medição. Três “culpados óbvios” foram absolvidos por medição barata antes de qualquer conserto, e o painel de custos, que superestimava a entrada em cerca de 2,5 a 3 vezes, passou a cobrar o token servido do cache pelo preço de cache. Cada decisão de ordem passou a aparecer em dinheiro.

Duas consequências que valem como regra geral:

Estável antes de volátil, mesmo entre blocos novos. A ficha da pessoa muda quando ela edita; o bloco de tela muda a cada minuto. A ficha entra logo antes da tela, nunca depois.
A maior economia vem de não enviar. Servir o vocabulário visual completo a um agente sem painel custava cerca de 2,5 mil tokens por turno. Servir a versão essencial resolveu. O mesmo princípio aplicado às ferramentas deu −70% de tokens por chamada no Work Pilot e −47% no agente de suporte.

Oito anti-padrões e o número que derrubou cada um

Nenhum destes veio de leitura. Todos foram construídos aqui, medidos e desfeitos.

1. Empurrar o modelo pelo contexto para ele se comportar. Quando o agente esquece de registrar, a tentação é pedir com mais firmeza. Pedimos o registro via skill a um modelo auxiliar: zero fichas gravadas em 3 runs, confirmado em 10 runs antes de trocar de abordagem. Empurrar produz relato melhor, não trabalho melhor. No lugar, o harness extrai e grava.

2. Destruir contexto para abrir espaço. Sem gravar antes, o modelo recompra o que perdeu, e a saída da recompra é podada no passo seguinte. Medimos 26 de 117 chamadas de ferramenta como releitura, 22% do orçamento do run, e 4 de 9 itens fecharam sem dado. Com persistir-e-apontar e o ponteiro preferindo o registro destilado:

Mesmo pedido	Antes	Depois
Releituras de material bruto	26	0
Duração	17,3 min	8,4 min
Tokens	2,09 M	1,26 M

E a qualidade subiu.

3. Copiar a semântica do cliente para dentro do agente. Escrever “para este cliente, atrasado = 5 dias” nas instruções parece prático. É garantia de divergência: alguém muda a configuração da ferramenta, o prompt continua dizendo a coisa antiga. A semântica vem da configuração viva, renderizada a cada run.

4. Deixar o retrato antigo parecer atual. O retrato de painel no prompt é ótimo para conversa e péssimo para pergunta factual. Hoje ele é rotulado com a idade real do dado, e pergunta do tipo “quantos estão abertos hoje” suprime o retrato e manda consultar a ferramenta.

5. Entregar amostra e deixar o modelo agregar. Passar 50 linhas de 3 mil e pedir um total é convidar um número errado com cara de certo. Leitura tabular é por referência, com corte declarado, e as contas saem de ferramenta determinística.

6. Tratar dado ausente como dado. O pior de todos, porque se disfarça de robustez. Dez consultas passaram a falhar por mudança de versão de API. Os valores padrão somaram 79,2 pontos e o veredito saiu “Saudável”, com zero avisos. 79,2 caía justamente na faixa que não dispara alerta. A regra: não pontuar o que não se mediu. O cálculo exclui a parcela ausente e declara a cobertura.

7. Guardar preferência como frase. É o caso da ficha que dizia tópicos e do acervo que dizia tabela. O que é estável e enumerável vira campo. O que é aberto continua frase.

8. Pôr a ferramenta na mesa antes do pré-requisito. A ferramenta de anotar na bancada era oferecida antes de a bancada existir. O modelo leu “não chame de novo” 12 vezes e chamou de novo. Em outro caso, uma ferramenta de lembrança servida do cache sem passar pelo contador foi chamada 47 vezes numa pergunta trivial: 6,7 milhões de tokens. Sem o pré-requisito, a ferramenta não é oferecida. O modelo não chama o que não vê.

Os anti-padrões 1 e 8 parecem dizer coisas opostas, e dizem a mesma. É proibido criar mecanismo cuja função seja convencer o modelo a se auto-relatar bem. É obrigatório que o servidor confira e produza: compare a promessa da resposta com o conteúdo real, grave o artefato se o modelo não gravou, só marque uma etapa como concluída se o banco confirma. A garantia nunca passa pelo modelo.

Como medir antes de declarar pronto

Método sem medição é opinião. Usamos quatro instrumentos, do mais barato ao mais caro:

Instrumento	O que responde	Custo
Log de montagem	Que blocos entraram neste run e quantos tokens cada um custou	Zero, sai em toda execução
Rastro do que o agente recebeu	Por chamada, o tamanho e a origem de cada peça e o que o mecanismo fez (poda, resumo, ferramenta guardada)	Zero, gravado sempre, sem conteúdo por padrão
Auditor de tarefas longas	Sobre traces reais: terminou honestamente? salvou o trabalho? convergiu em até três runs? quanto foi desperdício?	Baixo, sob demanda
Bateria de confiabilidade	Banco de perguntas por agente no runtime real: determinismo ao centavo, resposta vazia, uso de ferramenta, grounding	Alto, é a régua de pré-produção

O rastro foi o que mostrou que, de 23.124 tokens de “instruções” de um agente, só cerca de 5.400 eram texto escrito para ele. O resto era plataforma.

“Pareceu bom no chat” não é evidência. Mexeu em poda, compressão, ordem de bloco ou grounding, rode a régua antes de declarar pronto.

Foi assim que descobrimos que a poda causava 22% de desperdício em runs que “funcionavam”.

E a régua também mostra onde o método ainda falha aqui. O índice de skills deveria chegar ao modelo em toda conversa, porque é nele que mora a ordem: regra escrita só no corpo da skill deu zero aberturas em 5 execuções, porque o modelo decide abrir lendo apenas o índice. Só que a condição que descarta o índice procura um texto que, nas instruções geradas, aparece também no passo a passo. Medido em produção em 13 de outubro: 6 de 8 agentes com skills afetados. Uma skill de mapas vinculada ao Work Pilot foi carregada zero vezes enquanto ele fez mapas em 17 conversas. Sem erro nenhum na tela. A análise do conserto está pronta.

Outro achado da mesma passada: 41 ferramentas do assistente de configuração eram construídas e nunca oferecidas a ele. Hoje um teste impede esse número de crescer.

Como aplicar na sua empresa

O que segue vale para qualquer agente em produção, construído no OrganIA ou não. É a versão de bolso do método.

Quando o agente erra, abra o que ele recebeu antes de trocar de modelo. Se você não consegue ver o que estava no prompt naquela chamada, comece por aí.
Dê a cada bloco de prompt e a cada grupo de ferramentas uma condição de entrada. Escreva a condição em que ele não entra.
No prompt vai o índice; o conteúdo vem sob demanda. E o índice é onde as ordens moram, então trate o índice como orçamento, com teto, consolidando em vez de empilhar.
Semântica de negócio vem da configuração viva, a cada run. Nunca copiada nas instruções.
O que muda rápido vai para o fim do prompt. Meça quanto da entrada vem do cache e cobre pelo preço certo.
Comprima só sob pressão real, e grave antes de apagar. O contexto nunca pode ser o único lugar onde está o trabalho em andamento.
Escreva o texto do ponteiro decidindo para onde ele empurra o modelo.
Quem registra é o código. Registro que depende de o modelo lembrar não existe.
Dado ausente nunca vira dado. Valor padrão otimista sobre ausência é pior que erro.
O estável é campo; o aberto é frase. E pergunte, para cada informação: se eu trocar de agente, isto continua verdade?
Defina a régua de aceite antes de mexer em contexto. E rode.

Se você só tiver tempo para dois itens, faça o 1 e o 5. O primeiro muda a forma como a equipe discute erro. O segundo aparece na fatura do mês seguinte.

O que levo disso

A conversa sobre agentes ainda gira em torno de escolher o modelo e escrever o prompt. O que os números deste período me mostraram é que as garantias de um agente confiável são estruturais: condições de entrada, ponteiros, registros e conferências que o harness executa, sem depender da boa vontade do modelo.

O modelo raciocina. O contexto é o material sobre o qual ele raciocina. Decidir o que está lá, em que ordem e por quanto tempo é engenharia, e dá para medir.