Janela de Contexto para Agentes de IA: Otimizando Respostas de API Volumosas

Como reduzir o consumo de tokens de agentes com APIs mais enxutas

Um agente pede um cliente. Sua API devolve o cliente, seus últimos 200 pedidos, todos os itens desses pedidos, timestamps em três formatos e um bloco _links para cada objeto. Quarenta mil tokens entram na janela de contexto — quando o agente só precisava do e-mail.

Experimente o Apidog hoje

Repita isso algumas vezes na mesma execução e o agente gasta a maior parte do orçamento lendo JSON irrelevante. Em seguida, surgem falhas previsíveis: esquece a instrução original, resume em vez de concluir a tarefa e fica mais caro enquanto perde qualidade.

Esse é um problema de design da API, não de prompt. Cada campo retornado compete por espaço com instruções, conversa e plano de execução do agente. Este guia mostra como reduzir respostas, aplicar paginação, cortar payloads no wrapper da ferramenta e medir o impacto.

Por que agentes de IA falham em produção aborda o esgotamento de contexto como uma falha central; aqui está a parte prática.

O Apidog ajuda a medir o tamanho real das respostas e a simular payloads reduzidos antes de alterar a API.

Para onde vão os tokens

APIs feitas para navegadores e dashboards costumam carregar dados que custam caro para agentes:

• Envelopes verbosos: wrappers como data, meta, links e included podem dobrar o payload.
• Chaves repetidas: uma lista com 200 objetos e 15 campos repete 3.000 nomes de campos.
• Expansão aninhada padrão: cliente + pedidos + itens de pedido vira uma árvore grande rapidamente.
• Formatos redundantes: created_at, created_at_unix e created_at_human representam o mesmo valor três vezes.
• Nulos e valores vazios: serializar dezenas de campos null por registro é desperdício puro.

O custo acompanha o texto serializado, não o número de registros. Duzentos registros pequenos podem custar menos que um único objeto profundamente aninhado.

Regra 1: retorne campos, não recursos completos

Permita que o chamador selecione apenas o que precisa:

GET /v1/customers/8812?fields=id,email,plan,status

{ "id": "8812", "email": "[e-mail]", "plan": "pro", "status": "active" }

Isso pode reduzir cerca de 90% de um registro completo. O guia de design de APIs do Google documenta o padrão de máscara de campos; GraphQL resolve o mesmo problema tornando a seleção obrigatória.

Implemente duas proteções:

1. Valide fields contra o esquema e rejeite campos desconhecidos.
2. Use um conjunto padrão pequeno quando o parâmetro não for enviado — nunca retorne tudo por padrão.

Também exponha a seleção de campos na descrição da ferramenta:

{
  "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 das ferramentas ensinam o modelo a usá-las. Tanto o guia de chamadas de função da OpenAI quanto a documentação de uso de ferramentas da Anthropic enfatizam isso.

Tornar fields obrigatório é importante: campos opcionais tendem a ser ignorados.

Regra 2: limite listas sempre

Endpoints de lista sem limite são uma fonte comum de estouro de contexto. Um agente pede “pedidos recentes” e recebe tudo desde 2019.

Defina um limite máximo no servidor. Se o agente pedir limit=5000, devolva no máximo 100 itens e informe que houve corte.

Para agentes, siga estas regras:

• Limite páginas a aproximadamente 20–50 registros.
• Retorne a contagem total.
• Prefira paginação por cursor a offsets.
• Inclua um marcador explícito, como "truncated": true.

Os guias sobre paginação de APIs REST e paginação para milhões de registros explicam a mecânica.

Também ofereça formas de evitar paginação: endpoints de contagem, filtros por intervalo curto e respostas resumidas. A resposta mais barata é aquela que não retorna registros desnecessários.

Regra 3: corte dados no wrapper quando a API não é sua

APIs de terceiros talvez não suportem seleção de campos. Nesse caso, projete a resposta entre a chamada 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}

Para tornar isso sustentável:

• Armazene o payload completo: entregue a projeção ao modelo, mas mantenha a resposta original nos logs de execução. Veja práticas de rastreamento de chamadas de ferramentas de agentes.
• Informe os campos removidos: inclua algo como "_omitted": ["billing_address", "notes", "metadata"].
• Use formatos compactos para tabelas: CSV e tabelas Markdown repetem cabeçalhos apenas uma vez.

id,total,status,created_at
ord_91,4900,paid,2026-08-21
ord_92,1200,refunded,2026-08-22

Regra 4: crie respostas resumidas para perguntas recorrentes

Algumas perguntas não exigem registros. “Este cliente teve algum pagamento falho neste mês?” precisa de um booleano, não de 40 objetos de pagamento.

Quando uma pergunta se repete, crie um endpoint que responda diretamente:

• resumo de saúde da conta;
• agregação de status;
• contagem por período;
• indicador booleano de exceção.

Mantenha esses resumos estáveis e versionados. O prompt de um agente depende do formato da resposta, e uma mudança silenciosa pode quebrá-lo. Veja o que acontece quando uma API muda sob um agente e a melhor estratégia de versionamento de API.

Meça antes e depois

Acompanhe três métricas:

1. Bytes por resposta e endpoint: qualquer resposta acima de alguns KB merece revisão.
2. Tokens por chamada de ferramenta: use um tokenizador, como tiktoken, para classificar endpoints pelo custo.
3. Contexto acumulado por execução: se a tarefa termina perto do limite, a redução de payload melhora a confiabilidade — não apenas o custo.

Use um servidor mock para testar o formato reduzido antes de alterar a API. O Apidog permite executar endpoints, observar o tamanho das respostas e salvar requisições para repetir as medições. Veja também como executar agentes contra mocks em vez de produção.

Exemplo de uma boa resposta

{
  "customer": { "id": "8812", "email": "[e-mail]", "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"]
}

Com menos de 200 tokens, ela:

• responde à necessidade comum;
• informa que existem 47 pedidos, não apenas dois;
• deixa claro que houve truncamento;
• indica o que o agente pode solicitar depois.

Comece pelo endpoint mais barulhento: meça, adicione seleção de campos, limite a lista e execute o agente novamente. A diferença normalmente justifica o restante do trabalho.

Baixe o Apidog para medir e criar mocks no mesmo projeto.

Três casos comuns

Triagem de suporte

Um agente lê um ticket, busca o cliente e decide se deve escalar. A implementação ingênua retorna o cliente completo e 50 tickets anteriores, consumindo 30.000 tokens antes de analisar a reclamação.

A versão correta retorna apenas plano, status, contagem de tickets abertos e data do último contato. Cerca de 80 tokens e uma decisão melhor.

Operações internas

Um agente de deploy verifica 40 serviços. Objetos completos de status podem estourar a janela no décimo segundo serviço.

Um rollup com nome, estado e taxa_de_erro por serviço permite analisar toda a frota em algumas centenas de tokens.

Conciliação de dados

Um agente associa faturas a pagamentos. Retornar documentos completos faz a execução falhar após poucas dezenas de registros.

Retornar id, amount_cents, date e reference em CSV permite processar centenas de itens de uma vez.

O padrão é simples: o agente precisa de uma superfície de decisão; a API não deve entregar um documento inteiro.

Use histórico de execuções

Uma execução mostra que uma resposta foi grande. Apenas o histórico revela qual endpoint estoura o orçamento, com que frequência e para quais dados.

Essas métricas precisam sobreviver à sessão:

• em serviços próprios, use sua telemetria;
• em agentes que executam tarefas, use a plataforma de execução.

O Sharkly mantém o rastreamento e o resultado de cada execução na tarefa de origem, facilitando comparar execuções sem reconstruir sessões de terminal.

Defina um orçamento por ferramenta

Não limite apenas o contexto total. Defina também um teto por ferramenta — por exemplo, 1.500 tokens.

Quando uma resposta exceder o teto:

1. aplique uma projeção de campos;
2. inclua o marcador de campos omitidos;
3. registre o estouro;
4. classifique endpoints por frequência de chamadas e estouros.

Isso transforma um problema vago em uma fila objetiva de melhorias.

O orçamento também protege contra casos extremos: um endpoint pequeno nos testes pode se tornar enorme para um cliente com 4.000 pedidos. Um limite rígido converte esse cenário em uma resposta reduzida, não em uma tarefa falha.

Perguntas frequentes

É arriscado truncar respostas?

Só se o truncamento for silencioso. Informe explicitamente que dados foram omitidos para que o agente possa pedi-los quando necessário.

Devo usar GraphQL para agentes?

GraphQL torna a seleção de campos obrigatória, mas adiciona a complexidade de gerar queries válidas. Em muitas APIs, adicionar fields a endpoints REST é a mudança menor e mais confiável.

Qual é o tamanho ideal de uma resposta de ferramenta?

Procure ficar abaixo de 1.000 tokens para uma leitura de registro único e abaixo de 2.000 tokens para listas. Acima disso, avalie se o agente realmente precisa dos registros ou apenas de uma resposta resumida.

Cache de prompt resolve o problema?

Ele reduz o custo financeiro de contexto repetido, mas não libera espaço na janela. Uma resposta em cache com 40.000 tokens ainda ocupa 40.000 tokens.

E arquivos ou respostas binárias?

Nunca os coloque diretamente no contexto. Armazene o arquivo, forneça uma referência e uma descrição curta, e exponha uma ferramenta para extrair somente o conteúdo necessário.

Onde cortar: API ou wrapper?

Corte na API quando você a controla: todos os consumidores se beneficiam e os bytes nem chegam à rede. Corte no wrapper quando a API é de terceiros. Usar ambos também é válido.