O agente pede um registro de cliente. Sua API retorna o cliente, mais seus últimos 200 pedidos, mais cada item de linha nesses pedidos, mais timestamps em três formatos e um bloco _links para cada um. Quarenta mil tokens caem na janela de contexto. O agente precisava do endereço de e-mail.
Faça isso quatro vezes em uma execução e o agente terá gasto a maior parte de seu orçamento lendo JSON que não pediu. Então as falhas interessantes começam: ele esquece a instrução original, resume a tarefa em vez de finalizá-la, e o custo por execução sobe enquanto a qualidade cai.
Este é um problema de design na camada da API, não um problema de prompt. Agentes consomem respostas através de uma janela fixa, e cada campo que você retorna compete com as instruções, a conversa e o plano. Este guia cobre de onde vem o inchaço, os padrões de seleção de campo e paginação que o corrigem, como fazer o corte dentro da camada de ferramentas quando você não controla a API, e como medir a diferença. Nosso pilar sobre por que agentes de IA falham em produção trata o esgotamento do contexto como um dos modos de falha centrais, e esta é a metade prática disso.
Apidog ajuda no lado da medição: você pode ver o tamanho real da resposta para cada endpoint antes que um agente o chame, e simular o formato reduzido que você deseja antes que a equipe da API o implemente.
Onde os tokens vão
Respostas projetadas para navegadores e painéis carregam muita carga que custa dinheiro real a um agente.
Envelopes verbosos. Um wrapper data, meta, links, included em torno de um objeto de cinco campos pode dobrar o payload. Links de hipermídia são úteis para um cliente que os segue. Agentes quase nunca fazem isso, e cada URL são tokens.
Chaves repetidas. JSON repete cada nome de campo em cada elemento do array. Uma lista de 200 itens com 15 campos por item paga por 3.000 strings de chave. É por isso que os endpoints de lista dominam o uso do contexto.
Expansão aninhada por padrão. Endpoints que incorporam recursos relacionados são convenientes até que um agente os acesse. Um cliente mais seus pedidos mais itens é uma árvore, e árvores crescem rápido.
Formatos redundantes. created_at, created_at_unix, e created_at_human no mesmo objeto é custo triplo para um valor.
Nulos e vazios. Muitos serializadores emitem todos os campos mesmo quando não definidos. Vinte nulls por registro é puro desperdício.
Uma maneira útil de ver: o custo do token acompanha o tamanho do texto serializado, não o número de registros. Duzentos registros com cinco campos cada podem ser mais baratos do que um objeto aninhado profundamente.
Regra um: retorne campos, não recursos
A única mudança de maior valor é permitir que o chamador peça o que precisa.
GET /v1/customers/8812?fields=id,email,plan,status
{ "id": "8812", "email": "dana@example.com", "plan": "pro", "status": "active" }
Isso representa um corte de 90 por cento em relação a um registro completo na maioria das APIs, e leva uma tarde para adicionar. O guia de design de API do Google documenta o padrão de máscara de campo se você quiser uma versão com precedente, e GraphQL resolve o mesmo problema tornando a seleção obrigatória.
Duas notas de implementação. Valide a lista de campos em relação ao esquema e rejeite nomes desconhecidos, para que um campo alucinado produza um erro claro em vez de um objeto silenciosamente truncado. E mantenha um pequeno conjunto padrão para chamadores que não enviam nada, em vez de padronizar para tudo.
Então, exponha o parâmetro ao modelo na descrição da ferramenta, com os campos detalhados:
{
"name": "getCustomer",
"description": "Busca um cliente por ID. Sempre passe `fields` apenas com o que você precisa. Disponível: id, email, name, plan, status, created_at, billing_address, order_count.",
"input_schema": {
"type": "object",
"required": ["customerId", "fields"],
"properties": {
"customerId": { "type": "string" },
"fields": {
"type": "array",
"items": { "type": "string" },
"description": "Nomes dos campos a retornar. Mantenha esta lista mínima."
}
}
}
}
As descrições são o único lugar onde o modelo aprende essas regras, e tanto o guia de chamada de função do OpenAI quanto a documentação de uso de ferramentas da Anthropic dão a mesma importância a elas. Tornar fields obrigatório é o truque. Um parâmetro opcional é ignorado; um obrigatório força o modelo a pensar no que ele realmente precisa.
Regra dois: limite a lista, sempre
Endpoints de lista ilimitados são a segunda grande fonte de estouros. Um agente pede "pedidos recentes" e recebe tudo desde 2019.
Defina um limite máximo rígido no lado do servidor, não apenas um padrão. Se o agente enviar limit=5000, retorne 100 e avise. Nossos guias sobre paginação de API REST e como projetar paginação para milhões de registros cobrem a mecânica; as regras específicas do agente são mais restritas:
- Limite a página para algo que um modelo possa ler, na faixa de 20 a 50 itens para registros típicos.
- Retorne uma contagem total para que o agente possa saber se viu tudo sem precisar paginar para descobrir.
- Use paginação por cursor. Deslocamentos podem mudar quando os dados são alterados durante a execução, e um agente que pagina lentamente será afetado por isso.
- Inclua uma declaração simples na resposta, como
"truncated": true, para que o modelo saiba que há mais. Modelos costumam julgar erroneamente a completude apenas pelo comprimento de um array.
Também dê ao agente uma maneira de evitar a paginação. Um endpoint count, uma busca filtrada com uma janela estreita, ou um objeto de resumo frequentemente responderá à pergunta sem retornar nenhum registro. A resposta mais barata é aquela que não contém os dados.
Regra três: corte na camada de ferramentas quando a API não for sua
APIs de terceiros não adicionarão seleção de campo porque você pediu. Em vez disso, faça o corte em seu executor, entre a resposta HTTP e o modelo.
KEEP = {
"getCustomer": ["id", "email", "plan", "status"],
"listOrders": ["id", "total", "status", "created_at"],
}
def project(tool_name, payload):
keep = KEEP.get(tool_name)
if keep is None:
return payload
if isinstance(payload, list):
return [{k: item.get(k) for k in keep if k in item} for item in payload]
return {k: payload.get(k) for k in keep if k in payload}
Três refinamentos fazem isso se sustentar na prática.
Armazene a resposta completa e entregue ao modelo a projeção. Mantenha o payload não cortado em seu log de execução para que a depuração ainda seja possível. Nossa postagem sobre rastreamento de chamadas de ferramentas do agente de IA cobre o que registrar.
Diga ao modelo o que você removeu. Uma linha como "_omitted": ["billing_address", "notes", "metadata"] permite que ele peça o registro completo quando realmente precisar, em vez de concluir que os dados não existem.
Converta listas para um formato compacto. Para resultados tabulares, CSV ou uma tabela markdown custa muito menos tokens que JSON porque os nomes dos campos aparecem uma vez em vez de por linha. Modelos leem ambos perfeitamente.
id,total,status,created_at
ord_91,4900,paid,2026-08-21
ord_92,1200,refunded,2026-08-22
Regra quatro: sumarize no servidor para os casos pesados
Algumas perguntas não precisam de registros. "Este cliente teve algum pagamento falho este mês?" é um booleano. Retornar 40 objetos de pagamento para que o modelo possa descobrir é a maneira cara de responder.
Onde uma pergunta se repete, adicione o endpoint que a responde diretamente. Um resumo da saúde da conta, um rollup de status, uma pequena agregação. Isso parece um trabalho comum de design de API porque é, e é a versão mais valiosa de tudo acima: em vez de cortar uma resposta grande, você evita produzi-la.
Duas salvaguardas. Mantenha os resumos com formato estável para que os agentes possam confiar neles, e os versionem, porque o prompt de um agente é escrito contra um formato e uma mudança silenciosa o quebra. Nossa postagem sobre o que acontece quando a API muda por baixo de um agente cobre esse risco, e melhor estratégia de versionamento de API cobre a mecânica.
Meça antes e depois
Nada disso vale a pena ser feito às cegas. Três números dizem onde está o problema.
Bytes por resposta, por endpoint. Envie uma requisição realista para cada ferramenta que seu agente pode chamar e registre o tamanho do payload. Qualquer coisa acima de alguns kilobytes é um candidato. No Apidog você pode executar cada endpoint uma vez e ler o tamanho diretamente da resposta, então salvar a requisição para que a verificação se repita quando a API mudar.
Tokens por chamada de ferramenta. Bytes são um proxy; tokens são a conta. Execute os payloads através do tokenizador do seu provedor, como tiktoken para modelos OpenAI, e classifique os endpoints. A classificação geralmente é desequilibrada, com um ou dois endpoints sendo responsáveis pela maior parte do custo.
Contexto usado por execução. Registre o total acumulado em toda a tarefa do agente. Se uma tarefa termina perto do limite, o corte lhe rende execuções completas, não apenas mais baratas.
Então projete o formato que você deseja e simule-o antes que a equipe da API o construa. Um servidor mock retornando a resposta reduzida permite que você meça a melhoria e verifique se o agente ainda é bem-sucedido com menos dados, que é a questão que realmente importa. Nossa postagem sobre executar agentes contra mocks em vez de produção cobre o fluxo de trabalho.
Como uma boa resposta se parece
{
"customer": { "id": "8812", "email": "dana@example.com", "plan": "pro" },
"recent_orders": [
{ "id": "ord_91", "total_cents": 4900, "status": "paid" },
{ "id": "ord_92", "total_cents": 1200, "status": "refunded" }
],
"recent_orders_total": 47,
"truncated": true,
"_omitted": ["billing_address", "metadata", "order_line_items"]
}
Menos de 200 tokens. Ela responde à pergunta comum, diz que há 47 pedidos em vez de implicar que há dois, e informa ao modelo o que ele pode perguntar em seguida.
Comece com seu endpoint mais "barulhento". Meça-o, adicione seleção de campo, limite a lista e execute o agente novamente. A diferença entre os dois números geralmente é grande o suficiente para justificar o resto do trabalho. Baixe o Apidog se você quiser a medição e o mock no mesmo projeto.
Três lugares onde isso aparece
Triagem de suporte. Um agente lê um ticket, busca o cliente e decide se deve escalar. A versão ingênua busca o objeto completo do cliente e os últimos 50 tickets, queimando 30.000 tokens antes de ler a reclamação real. A versão corrigida chama um endpoint de resumo retornando plano, status, contagem de tickets abertos e data do último contato. Cerca de 80 tokens, e a decisão de escalonamento melhora porque os fatos relevantes não estão escondidos.
Agentes de operações internas. Um agente de deploy verifica a saúde do serviço em 40 serviços. Objetos de status completos estouram a janela no serviço 12. Um rollup que retorna uma linha por serviço, nome mais estado mais taxa de erro, encaixa todos os 40 em algumas centenas de tokens e permite que o agente raciocine sobre a frota em vez de esquecer a primeira metade.
Entrada e conciliação de dados. Um agente associa faturas a pagamentos. Retornar documentos de fatura completos faz com que ele falhe após algumas dezenas de registros. Retornar id, amount_cents, date e reference como CSV permite que ele processe várias centenas em uma única passagem, porque a comparação usou apenas quatro campos.
O padrão em todos os três: o agente precisava de uma superfície de decisão, e a API lhe deu um documento.
Você precisa do histórico de execuções para ver o padrão
Uma única execução informa que uma resposta foi grande. O padrão, qual endpoint estoura o orçamento e com que frequência, só aparece ao longo de múltiplas execuções.
Isso significa que os números precisam sobreviver à sessão. Para um serviço que você implementou, essa é a sua própria telemetria. Para agentes de codificação que executam trabalho atribuído, é a plataforma que os executa: Sharkly mantém o rastreamento de execução e o resultado de cada execução na Tarefa de onde veio, então a comparação entre execuções é uma questão de ler o histórico da tarefa em vez de reconstruir sessões de terminal. De qualquer forma, a aplicação do orçamento sem histórico informa que algo é muito grande, mas não o que consertar primeiro.
Defina um orçamento por ferramenta, não apenas por execução
A maioria das equipes limita o contexto total e para por aí. Um orçamento por ferramenta é mais útil, porque transforma um problema vago em um problema específico.
Dê a cada ferramenta um limite, por exemplo, 1.500 tokens. Quando uma resposta o excede, o executor corta para a projeção, anexa o marcador de campo omitido e registra o estouro. Agora você tem uma lista de endpoints que regularmente excedem o orçamento, classificados pela frequência com que o agente os chama, que é sua fila de trabalho.
O orçamento também o protege do endpoint que é pequeno em testes e enorme para um cliente real. As distribuições têm caudas, e a conta com 4.000 pedidos é a que quebrará uma execução às 2 da manhã. Um limite rígido transforma isso em uma resposta reduzida em vez de uma tarefa falha.
Perguntas frequentes
É arriscado truncar respostas se o agente precisar dos dados que faltam? Apenas se você ocultar o truncamento. Inclua um marcador explícito e uma lista de campos omitidos para que o modelo possa solicitá-los. O truncamento silencioso é o que causa respostas erradas, não o corte em si.
Devo usar GraphQL para agentes? GraphQL torna a seleção de campos obrigatória, o que resolve isso de forma limpa, mas transfere a complexidade para a construção da query e os modelos escrevem queries inválidas com mais frequência do que usam indevidamente uma lista de campos. Adicionar fields aos endpoints REST geralmente é a mudança menor.
Qual o tamanho ideal para uma resposta de ferramenta? Procure ficar abaixo de 1.000 tokens para uma leitura de registro único e abaixo de 2.000 para uma lista. Além disso, pergunte se o agente precisa de registros ou de uma resposta.
O cache de prompt resolve isso? Ele reduz o custo do contexto repetido, não o espaço que ocupa. Uma resposta em cache de 40.000 tokens ainda preenche a janela, então o cache ajuda na conta, mas deixa o problema de confiabilidade intacto.
E as respostas binárias e de arquivos? Nunca as coloque no contexto. Armazene o arquivo, dê ao agente uma referência e uma breve descrição, e forneça-lhe uma ferramenta separada para extrair apenas o que ele precisa.
Onde deve ser feito o corte, na API ou no wrapper da ferramenta? Na API quando você a possui, porque todo chamador se beneficia e os bytes nunca cruzam a rede. No wrapper quando você não a possui. Fazer os dois está bom.