Engenharia de Contexto: O Que É e Como Uso para Construir Melhores Agentes de IA

Índice

Publicado em julho de 2026.

TL;DR: Engenharia de prompts é sobre escolha de palavras; engenharia de contexto é sobre arquitetura de informação. Você tem uma janela de contexto finita e cada token é uma troca. Estruturo o contexto do agente em quatro camadas — prompt de sistema, histórico de conversa, conteúdo recuperado e saídas de ferramentas — e trato a janela como um orçamento, não como uma tela em branco.

[Nota do operador] Gerencio mais de 30 agentes em produção. A melhoria que mais fez a diferença no último ano não é um modelo melhor nem um framework mais sofisticado — é ser mais deliberado sobre o que entra na janela de contexto e o que fica de fora. A engenharia de contexto é agora a habilidade principal que busco ao avaliar trabalho com agentes.

A maioria das pessoas ainda fala de “engenharia de prompts” como a habilidade crítica para trabalhar com IA. A engenharia de prompts é real e importa. Mas é um subconjunto de uma disciplina maior — e tratá-la como o trabalho completo explica por que muitos agentes que parecem bons em demos desmoronam em produção.

Por que a “engenharia de prompts” se tornou o enquadramento errado

“Engenharia de prompts” implica que a alavanca-chave é o texto que você escreve no prompt de sistema ou na mensagem do usuário. Passe tempo suficiente elaborando as instruções certas, a redação certa, o formato certo, e o modelo fará o que você precisa.

Isso é verdade até certo ponto. Um prompt de sistema bem escrito é necessário. Mas o comportamento do modelo é determinado por tudo o que está na janela de contexto — não apenas pelo seu prompt de sistema. É moldado por:

• O histórico de conversa (o que aconteceu em turnos anteriores)
• Os documentos ou dados que você recuperou e injetou
• Os resultados de chamadas de ferramentas que o modelo viu até agora
• A contagem de tokens e a posição de cada pedaço de informação

Se você está pensando apenas na redação do prompt e ignorando o resto do que preenche a janela de contexto, está otimizando uma entrada enquanto deixa as outras sem gerenciamento. É por isso que “engenharia de contexto” é o enquadramento mais preciso para trabalho sério com agentes.

O que é realmente a engenharia de contexto

A engenharia de contexto é a disciplina de decidir quais informações entram na janela de contexto do modelo, em que ordem, em que ponto da conversa.

A janela de contexto é a memória de trabalho do modelo. É finita. Cada token que você coloca dentro desloca outra coisa — ou aumenta o custo. E ao contrário da memória de trabalho humana, o modelo não tem como “buscar algo” fora do que está na janela (a menos que você lhe dê ferramentas para isso). O que ele vê é tudo o que ele tem.

A engenharia de contexto é a prática de tratar essa janela como um recurso a ser gerenciado deliberadamente:

• O que o modelo precisa saber para completar este passo?
• O que ele precisava saber em um passo anterior, mas não precisa mais?
• O que é estável entre execuções vs. dinâmico por solicitação?
• Onde na janela cada pedaço de informação deve aparecer?

Essas não são questões de redação de prompt. São questões de arquitetura de informação. E as respostas determinam a confiabilidade do agente tanto quanto a seleção do modelo.

As quatro camadas que projeto

Cada agente que construo tem quatro camadas de contexto distintas. Penso em cada uma delas separadamente.

Camada 1: O prompt de sistema

Esta é a fundação estável e independente do turno. Define quem é o agente, o que ele pode fazer, o que não pode fazer e como deve lidar com casos extremos.

O erro que a maioria das pessoas comete aqui é escrever o prompt de sistema uma vez e tratá-lo como terminado. Na prática, o prompt de sistema precisa responder explicitamente a três perguntas:

1. Para que serve este agente? (O modelo precisa de um escopo preciso, não de uma missão vaga.)
2. O que deve fazer quando a entrada é ambígua ou incompleta?
3. O que nunca deve fazer? (Restrições negativas importam.)

Mantenha o prompt de sistema mínimo. Cada frase desnecessária é overhead que compete com o conteúdo dinâmico onde o raciocínio real acontece.

Uma dica prática: se você está usando Claude com a API, use cache_control no seu prompt de sistema. Um prompt de sistema grande e estável em cache custa aproximadamente 10% do que custaria sem cache por turno.

Camada 2: Histórico de conversa

Em um agente multi-turno, o histórico de conversa é dinâmico e cresce a cada turno. Sem gerenciamento, torna-se o maior driver de inflação de contexto.

O problema: turnos anteriores contêm informações que o modelo não precisa mais. Manter tudo isso desperdiça tokens e pode confundir o modelo, dando-lhe contexto desatualizado para raciocinar.

O que faço:

• Truncar ou resumir turnos antigos quando o histórico excede um limiar.
• Manter apenas resultados de chamadas de ferramentas ainda relevantes.
• Nunca deixar o histórico crescer ilimitadamente em um agente de longa duração.

Camada 3: Conteúdo recuperado

Esta é a camada que separa agentes mediocres de bons. A maioria dos agentes precisa extrair dados externos em tempo de execução.

Dois princípios que aplico:

Recuperar apenas o que é relevante para o passo atual. Não injete um documento de 50 páginas quando o passo atual precisa apenas de uma seção.

A posição importa. Informações no início e no fim do contexto recebem mais peso do que informações no meio. Se há um trecho recuperado que o modelo absolutamente deve usar, não o enterre no meio de uma injeção longa.

Camada 4: Saídas de ferramentas

Em um loop agêntico, o modelo chama ferramentas e recebe resultados. Esses resultados se acumulam. E ao contrário do histórico de conversa, as pessoas raramente pensam em gerenciá-los.

A solução é a mesma: depois que um resultado de ferramenta cumpriu seu propósito, você não precisa mantê-lo na janela. Em um agente multi-passo, levo adiante um resumo estruturado do “que estabelecemos até agora” em vez da saída bruta de cada passo anterior.

O orçamento de contexto: o que incluir e o que cortar

Uso um modelo mental simples: a janela de contexto é um orçamento e cada token é um gasto. Antes de cada turno do agente, pergunto:

• O que o modelo precisa saber agora para fazer este passo?
• O que posso deixar de fora ou resumir sem perder nada importante?
• O que está duplicado entre camadas?

O objetivo é embalar a janela com as informações de maior sinal possível a cada passo, não ser exaustivo.

Três erros de engenharia de contexto que cometi em produção

1. Timestamps flutuantes no prefixo estável. Eu colocava Data atual: {{data}} no topo do meu prompt de sistema. Essa string muda todo dia, o que invalidava silenciosamente meu cache de prompts a cada 24 horas. Mova informações voláteis — timestamps, IDs de usuário — para o final do contexto, após o prefixo estável.

2. Tratar saídas de ferramentas como apenas-append. Eu executava loops agênticos onde cada resultado de chamada de ferramenta permanecia no contexto. No turno 8, o modelo estava raciocinando a partir de um contexto que era 80% saídas de ferramentas desatualizadas.

3. Ignorar a avaliação em mudanças de contexto. Mudanças de contexto são mudanças de comportamento do modelo. Agora executo o mesmo arnês de avaliação em mudanças de contexto que executo em mudanças de prompt.

Meu fluxo de trabalho de engenharia de contexto na prática

Antes de escrever uma única linha de código de agente, esboço as camadas de contexto:

Prompt de sistema:      ~500 tokens, estável, em cache
Orçamento de histórico: ~2000 tokens máx., resumido após cada passo
Contexto recuperado:    ~1000-3000 tokens por passo, apenas fragmentos relevantes
Orçamento de saídas:   apenas passo atual, resumido adiante

A questão de seleção do modelo vem depois. Uma vez que sei qual engenharia de contexto preciso fazer, escolho o modelo mais barato que mantém o padrão de confiabilidade sob a configuração de contexto correta.

FAQ

Qual é a diferença entre engenharia de prompts e engenharia de contexto?

A engenharia de prompts foca na redação do seu prompt de sistema e nas mensagens do usuário. A engenharia de contexto é a disciplina mais ampla: decidir quais informações entram na janela de contexto completa — incluindo histórico de conversa, dados recuperados e saídas de ferramentas — em que ordem e a que custo de tokens.

Qual deve ser o tamanho do meu prompt de sistema?

O menor possível enquanto for específico. Miro em menos de 800 tokens para a maioria dos agentes. Um prompt de sistema que tenta antecipar cada cenário acaba sendo longo demais para ser lido de forma confiável pelo modelo.

A engenharia de contexto importa mais para alguns modelos do que para outros?

Importa para todos eles, mas as apostas são mais altas com modelos menores. Um grande modelo frontier às vezes pode se recuperar de um contexto mal estruturado; um modelo menor com orçamento mais apertado não pode.

Como sei se minha engenharia de contexto está funcionando?

Acompanhe as mesmas métricas que você acompanharia para qualquer mudança de confiabilidade: taxa de sucesso no seu conjunto de avaliação, custo por resultado bem-sucedido e distribuição de erros por passo.

Devo sempre comprimir ou resumir o histórico?

Para agentes transacionais curtos: não. Para agentes multi-turno que executam mais de 5-6 trocas: sim, sempre. A regra geral que uso — uma vez que o orçamento de histórico excede 30% do meu orçamento total de contexto, começo a resumir.