Orçamento de atenção e de execução

Um token é uma unidade de texto processada pelo modelo; não equivale sempre a palavra ou caractere. Contexto é tudo o que chega efetivamente à execução: instruções, conversa, arquivos, resultados de ferramentas e, conforme o produto, estado recuperado. Janela de contexto é o limite operacional, não uma promessa de que cada detalhe receberá a mesma atenção. Ferramentas ampliam o que o sistema pode observar ou fazer. Custo combina entrada, saída, chamadas, computação, armazenamento e tempo humano.

Não confunda token de LLM com access token de autenticação. Um mede/representa unidades do texto do modelo; o outro é uma credencial. Também não confunda uma chamada ao provedor com “uma funcionalidade”: um único clique pode provocar várias chamadas, e uma chamada pode incluir mil ordens em um resultado de ferramenta.

Pedido da pessoa
  + instruções estáveis
  + arquivos selecionados
  + histórico necessário
  + resultados das ferramentas
  = entrada ao modelo

entrada + saída + ferramentas + infraestrutura = custo da execução

Contexto útil, não contexto máximo

Colar o repositório inteiro parece seguro, mas cria competição entre regras, duplica fatos e encarece cada turno. Comece com objetivo, fonte de verdade e caminhos relevantes. Deixe o agente pesquisar com ferramentas de leitura. Depois de uma fase, faça clearing: preserve spec, decisões e evidência; remova exploração abandonada.

Para um ticket de aprovação de OS, o contexto inicial pode conter AGENTS.md, o ticket, a spec e o contrato de domínio. O agente consulta arquivos de implementação sob demanda. Não precisa receber logs antigos, design de faturamento ou a conversa que originou o projeto.

Cache de prefixo pode reaproveitar processamento quando um provedor oferece esse recurso e o prefixo permanece elegível. Isso não transforma o modelo em memória e não garante desconto entre produtos. Estado conversacional também não deve ser presumido: verifique se a API exige reenviar mensagens ou oferece um identificador de continuidade.

Elegibilidade e cobrança são práticas voláteis; confirme a versão usada no guia oficial de prompt caching da OpenAI ou na documentação equivalente do seu provedor.

Orçamento explícito

type Budget = {
  maxSteps: number;
  maxInputTokens: number;
  maxOutputTokens: number;
  maxToolCalls: number;
  deadlineMs: number;
};

function mayContinue(b: Budget, used: Budget) {
  return used.maxSteps < b.maxSteps &&
    used.maxToolCalls < b.maxToolCalls &&
    used.deadlineMs < b.deadlineMs;
}

Em produção, nomes como usedSteps seriam mais claros; o exemplo destaca que cada dimensão tem limite próprio. Um teto monetário sem limite de passos ainda pode criar latência; um teto de tokens não controla uma ferramenta cara.

Falhas, segurança e medição

Contexto pode carregar segredo, dado pessoal e instrução maliciosa. Redija antes do envio, limite retenção e trate conteúdo recuperado como não confiável. Resuma resultados grandes no código quando possível. Não peça ao modelo para “ignorar dados sensíveis” depois de já enviá-los.

Meça por caso de uso: taxa de sucesso, entrada, saída, cache, número/duração das ferramentas, custo estimado e intervenção humana. P50 esconde cauda; acompanhe P95. Compare configurações com o mesmo conjunto de casos. Uma versão mais barata que duplica retrabalho pode ter custo total maior.

Antes e agora

Antes, a recomendação comum era preencher a maior janela disponível. Hoje, engenharia de contexto privilegia seleção, ponteiros, recuperação sob demanda e compactação com rastreabilidade. Contexto grande continua útil para análise de um documento extenso ou migração transversal, desde que a tarefa e as avaliações mostrem benefício.

Laboratório

Rode três versões do mesmo ticket: repositório inteiro, quatro arquivos selecionados e contexto mínimo com busca. Registre sucesso, tokens, chamadas e tempo. O aceite exige dataset idêntico, versão registrada, nenhum segredo, pelo menos um caso adversarial e uma conclusão baseada nos dados — não no prompt preferido.

Perguntas: janela grande elimina degradação de atenção? Qual custo uma contagem de tokens não captura? Quando limpar contexto é melhor que compactar?

Composição em camadas: o que entra agora e o que fica consultável

Use quatro perguntas. Primeiro, o que é obrigatório para decidir: objetivo, aceite, restrições e instruções do escopo. Segundo, onde está a fonte de verdade: spec, contrato, teste ou ADR. Terceiro, que pequena interface precisa estar presente agora. Quarto, o que pode ser buscado sob demanda com ferramenta de leitura.

Essa técnica é divulgação progressiva. Ela não esconde regra importante; evita transportar tudo em todos os turnos. Para T-014, AGENTS.md, ticket, spec e contrato de domínio formam o núcleo. O agente localiza controller e testes quando precisar. Se a regra de unidade decide autorização, ela deve estar no núcleo ou numa fonte obrigatória explicitamente apontada.

Depois da descoberta, registre evidências com caminho e conclusão. Na troca de fase, faça clearing: preserve spec, decisões e provas; retire logs duplicados, hipóteses descartadas e conversas que não alteram mais o trabalho. Um resumo sem ponteiro pode apagar nuance. Um ponteiro sem síntese exige redescoberta. Use os dois.

Cache de prefixo é otimização, não memória. Elegibilidade, desconto e retenção variam por produto e versão. Estado conversacional também não deve ser presumido: confirme se a API reenvia mensagens, usa identificador de continuidade ou mantém estado externo.

Medidor executável de orçamento

O exemplo TypeScript abaixo demonstra enforcement de passos, ferramentas e prazo. Ele não estima tokens do provedor; obtenha essa contagem da resposta da API ou do tokenizer recomendado para o modelo específico.

type Usage = { steps: number; toolCalls: number; elapsedMs: number };
type Limit = { steps: number; toolCalls: number; deadlineMs: number };

export function assertBudget(used: Usage, limit: Limit) {
  if (used.steps >= limit.steps) throw new Error("budget:steps");
  if (used.toolCalls >= limit.toolCalls) throw new Error("budget:tools");
  if (used.elapsedMs >= limit.deadlineMs) throw new Error("budget:deadline");
}

assertBudget(
  { steps: 1, toolCalls: 0, elapsedMs: 120 },
  { steps: 4, toolCalls: 2, deadlineMs: 5_000 },
);

Teste cada limite isoladamente. Um teto de saída não limita busca cara; um teto monetário não impede latência; um prazo sem cancelamento pode deixar processo filho ativo. Em produção, registre parada como estado, não como “erro desconhecido”.

Medição que conecta custo a valor

Uma chamada HTTP pode devolver mil ordens; isso continua uma chamada, embora bytes, banco e memória aumentem. Um clique pode provocar várias chamadas ao modelo. Um texto curto pode depender de ferramenta lenta. Meça dimensões separadas:

Dimensão	Unidade	Pergunta
entrada/saída	tokens	quanto texto foi processado?
ferramentas	chamadas e duração	quais capacidades foram consumidas?
execução	passos e tempo	houve progresso ou loop?
qualidade	casos aceitos	o resultado passou na rubrica?
operação	intervenção e retrabalho	qual custo humano permaneceu?
dinheiro	custo por caso aceito	a solução é sustentável?

P50 descreve o centro. P95 expõe a cauda: 95% das observações estão abaixo daquele valor. Ambos exigem janela, população e amostra. Compare configurações com o mesmo dataset e critérios; do contrário, a conclusão não é causal.

Dez ou mil ordens: o que realmente muda

Considere duas chamadas à mesma API: GET /ordens?limit=10 e GET /ordens?limit=1000. Para o contador HTTP, ambas podem ser uma requisição. Isso não significa que custam o mesmo. A segunda consulta pode ler mais linhas e índices no banco, transferir mais bytes, ocupar mais memória, demorar mais e aumentar a chance de timeout. Se todo o JSON for enviado ao modelo, também produzirá mais tokens de entrada. Registro, requisição, byte e token são unidades diferentes.

Não existe conversão fixa “uma ordem = tantos tokens”. Uma OS com descrição longa, histórico e anexos textualizados custa mais que outra com três campos curtos; o tokenizer também varia por modelo. Meça o corpo real ou use a telemetria fornecida pelo provedor. Antes do modelo, aplique paginação, filtros e seleção de campos na API. Se a tarefa pede “quais ordens críticas estão atrasadas?”, o banco pode filtrar status e data; a aplicação pode calcular totais; o modelo recebe somente os casos que exigem interpretação.

Um fluxo seguro separa as decisões:

API pagina e autoriza os registros
  → código valida e reduz os campos
  → cálculo determinístico produz totais
  → modelo interpreta apenas a evidência necessária
  → resposta cita os identificadores usados

Evite truncar silenciosamente a milésima ordem porque a janela acabou. Registre quantos itens existiam, quantos foram examinados e qual regra escolheu a amostra. Se a cobertura completa é necessária, processe lotes com estado e reconciliação ou use uma consulta agregada adequada. Se uma amostra é suficiente, declare o método e a limitação. Assim, o orçamento reduz custo sem transformar ausência de contexto em falsa certeza.

Esse registro também permite repetir a análise quando novas ordens chegarem, sem fingir que duas fotografias diferentes são comparáveis.

Falha guiada e diagnóstico

Sintoma: após dez turnos, o agente ignora “não alterar identidade”, repete buscas e custa quatro vezes mais.

Hipóteses: regra enterrada no histórico; resultados duplicados competem por atenção; fonte relevante não foi apontada; clearing não ocorreu; tool calls não têm limite.

Verificação	Evidência	Correção
inspecionar entrada efetiva	regra presente e sem conflito	mover regra estável ao escopo correto
listar tool calls	consultas repetidas sem evidência nova	preservar resultado e ponteiro
comparar fases	exploração abandonada permanece	clearing com handoff curto
forçar orçamento	loop não para	corrigir enforcement no harness

Enviar ainda mais texto tende a agravar o sintoma. Corrija composição, fonte ou limite.

Segurança e privacidade

Classifique dados como públicos, internos, confidenciais, pessoais ou segredos. Um modelo não precisa receber senha para revisar autenticação. Use fixtures sintéticas, redaction e minimização. Verifique política de retenção e região do provedor. Conteúdo recuperado é não confiável: uma frase dentro de um PDF não pode ganhar autoridade para enviar e-mail ou ler credencial. Schema, allowlist e policy bloqueiam o efeito.

Exercício guiado, aceite e desafio

1. Congele três tickets e a rubrica de sucesso.
2. Rode versões com repositório inteiro, quatro arquivos e núcleo com busca.
3. Mantenha modelo, configuração, limites e dataset iguais.
4. Registre tokens, cache, tools, duração, sucesso e intervenção.
5. Inclua arquivo irrelevante com instrução maliciosa e prove negação pela policy.
6. Calcule custo por caso aceito, não somente por chamada.

Entregável: dataset, configuração, trace redigido, tabela e decisão com limitações. O aceite exige reprodução por outra pessoa e conclusão sustentada pelos números.

Desafio: projete contexto para um incidente de pagamento. Diferencie evidência presente, fonte consultável, dado redigido e artefato que sobrevive ao clearing.

Transição

Orçamento define quanto o sistema observa e faz. O próximo capítulo transforma essa capacidade em contrato operacional: resultado, fontes, restrições, formato, verificação e parada. Prompting deixa de ser palavras mágicas e vira definição de trabalho.

Fontes

• OpenAI — Tokens
• OpenAI — Prompt caching
• Anthropic — Context windows