Engenharia de contexto: o que o modelo vê e por quê

Engenharia de contexto (context engineering) é a prática de decidir tudo o que um modelo de linguagem vê quando responde: não só a pergunta que você digita, mas as instruções em volta dela, os documentos e resultados de ferramentas inseridos, a memória salva sobre o usuário e a conversa até ali. Tudo isso divide uma única janela de contexto, e o modelo responde a partir desse texto e de nada mais. O termo se espalhou em 2025, conforme mais produtos de IA viraram agentes que montam a maior parte do próprio contexto de forma automática.

A engenharia de prompt trata principalmente de como redigir um pedido. A engenharia de contexto trata do que o modelo deve ter à frente em cada chamada, e em que ordem.

De um prompt a um contexto

Em um app de chat, você escreve a maior parte do contexto: o app acrescenta um prompt de sistema e o histórico, e você acrescenta o resto. Em uma aplicação, a balança se inverte. Um usuário digita uma frase, e o código em volta do modelo acrescenta instruções, um perfil do usuário, três artigos de ajuda encontrados por busca, a lista de ferramentas disponíveis e a saída da última chamada de ferramenta. A frase do usuário pode ser uma pequena fração do que o modelo lê.

Quando um sistema assim responde mal, a solução raramente está na redação. A causa comum é o modelo ter recebido o material errado: um fato que faltou, um resultado de ferramenta desatualizado, um documento irrelevante que pareceu relevante para a busca.

O que entra na janela de contexto

Uma chamada típica em uma aplicação de IA contém algumas ou todas estas partes, mais ou menos nesta ordem:

• Instruções de sistema: o papel, as regras e o formato de saída, normalmente fixos para o app inteiro. Veja prompt de sistema.
• Definições de ferramentas: nomes, descrições e parâmetros das ferramentas que o modelo pode chamar.
• Exemplos: algumas entradas e saídas de exemplo que mostram o comportamento esperado.
• Memória: fatos salvos de sessões anteriores, como o plano, o idioma ou as preferências do usuário.
• Documentos recuperados: trechos encontrados ao buscar esta pergunta em uma base de conhecimento (geração aumentada por recuperação, ou RAG).
• Histórico da conversa: as mensagens anteriores, na íntegra ou resumidas.
• Resultados de ferramentas: saídas de buscas, execuções de código ou chamadas de API feitas durante esta tarefa, como em um loop ReAct.
• A mensagem atual: o que o usuário acabou de perguntar.

O bloco abaixo é um contexto montado para um assistente de suporte. Desligue as partes uma por vez. Sem a parte de contexto, o modelo não tem como saber o plano da cliente; sem a parte de entrada, ele não tem fatos sobre o produto, e as restrições mandam que ele diga isso em vez de adivinhar.

Contexto de um assistente de suporte

EditCopy

PartsRoleConstraintsContextInputFormatTask

Role

Você é o assistente de suporte do Acme Notes, um app de anotações.

Constraints

Responda só a partir dos documentos abaixo. Se eles não cobrirem a pergunta, diga isso e ofereça colocar o cliente em contato com uma pessoa. Nunca chute sobre recursos ou preços.

Context

Memória da cliente: nome Dana, plano Free, usa o app Android.

Input

<document source="help/offline-mode"> O modo offline está disponível no plano Pro. As notas criadas offline são sincronizadas quando o aparelho volta a se conectar. Anexos com mais de 20 MB não ficam disponíveis offline. </document> <document source="help/plans"> Plano Free: até 3 aparelhos. Plano Pro: aparelhos ilimitados, modo offline, 30 dias de histórico de versões. </document>

Format

De duas a quatro frases em linguagem simples. Chame a cliente pelo nome.

Task

Pergunta da cliente: Posso usar o app no avião, sem internet?

Try it

Example replyReplies vary between models and runs.

Oi, Dana! O modo offline faz parte do plano Pro, e a sua conta está no plano Free, então no momento ele não está disponível para você. Com o Pro, as notas que você criar durante o voo são sincronizadas automaticamente quando o celular voltar a se conectar. Um limite para saber: anexos com mais de 20 MB não ficam disponíveis offline.

Repare que a resposta correta depende de juntar duas fontes: a memória (plano Free) e um documento (o modo offline é só do Pro). Nenhuma das duas basta sozinha, o que é típico. Boa parte da engenharia de contexto é garantir que as peças que dependem umas das outras cheguem juntas.

Quatro jeitos de um contexto dar errado

1. Informação faltando. O modelo preenche lacunas com palpites plausíveis, que é de onde vêm muitas alucinações. Acrescente o fato ou diga ao modelo o que fazer quando um fato faltar.
2. Material demais. Cada parágrafo irrelevante custa tokens e disputa a atenção. Liu et al. 2023, "Lost in the Middle: How Language Models Use Long Contexts", descobriram que os modelos testados usavam informações do começo ou do fim de uma entrada longa de forma mais confiável do que informações do meio. Os modelos mais novos lidam melhor com entradas longas, mas enviar os poucos trechos que respondem à pergunta continua mais barato, e mais fácil para o modelo usar, do que colar o manual inteiro.
3. Informação desatualizada. Um resultado de ferramenta de dez passos atrás pode descrever um arquivo ou um saldo que já mudou. Se o modelo vê as duas versões, pode usar a antiga.
4. Conflitos. Dois documentos discordam, ou a memória diz uma coisa e o usuário outra. Diga ao modelo qual fonte vale mais, por exemplo "a última mensagem do usuário prevalece sobre a memória salva".

Como ordenar o contexto

A ordem muda tanto os resultados quanto o custo.

• Partes estáveis primeiro. As instruções de sistema, as definições de ferramentas e o material de referência fixo raramente mudam entre chamadas. Vários fornecedores de API oferecem cache de prompt (prompt caching), que reaproveita o processamento de um início idêntico da entrada, então um prefixo que não muda deixa as chamadas repetidas mais baratas e mais rápidas.
• Material longo antes da pergunta. Para um documento longo ou um grande conjunto de trechos, coloque o material primeiro e a pergunta e as instruções finais depois. O guia de prompts da Anthropic, por exemplo, recomenda essa ordem para entradas longas, com a pergunta logo antes de o modelo começar a escrever.
• Rotule cada peça. Envolva cada fonte em tags como <document>, <memory> ou <tool_result>, com o nome da fonte. Os rótulos permitem que o modelo separe dados de instruções e que você peça a ele que cite de onde veio uma resposta. Delimitadores e tags XML mostra os formatos.

Como enxugar um contexto longo

Cada mensagem de um chat reenvia o histórico inteiro, então sessões longas crescem até que algo precise sair. Dependendo do app, ele pode resumir ou descartar mensagens antigas, ou pedir que você abra um chat novo. Você tem resultados melhores enxugando de propósito.

• Mantenha as últimas mensagens palavra por palavra e troque as mais antigas por um resumo.
• Depois que um resultado de ferramenta foi usado, troque-o por uma nota de uma linha dizendo o que ele mostrou.
• Mantenha os identificadores exatos em todo resumo: nomes de arquivos, nomes de funções, IDs, mensagens de erro e números. Um resumo que diz "o arquivo de configuração" onde o histórico dizia settings.prod.yaml perde justamente o detalhe que importava.
• Em um app de chat, quando a conversa se desviar, comece um chat novo com uma nota de passagem. O prompt abaixo escreve uma.

Comprimir um chat longo para recomeçar

EditCopy

Fill inprojetopalavras

Esta conversa está ficando longa. Escreva uma nota de passagem que eu possa colar em um chat novo para que ele continue o trabalho sem o histórico. Inclua: 1. O objetivo de a refatoração do formulário de cadastro, em uma frase. 2. As decisões que tomamos e o motivo de cada uma. 3. O estado atual: o que funciona e o que está inacabado. 4. Os nomes exatos que importam: arquivos, funções, mensagens de erro, números. Copie-os exatamente. 5. As perguntas em aberto e o próximo passo. Deixe de fora os becos sem saída, a menos que expliquem uma decisão. No máximo 200 palavras.

Try it

Example replyReplies vary between models and runs.

Objetivo: substituir as validações escritas à mão do formulário de cadastro por um único esquema de validação compartilhado, usado pelo navegador e pelo servidor.

Decisões

1. Um único arquivo de esquema, signupSchema.ts, importado por SignupForm.tsx e por api/signup.ts, para que os dois conjuntos de regras não se distanciem.
2. As mensagens de erro ficam palavra por palavra, porque a central de ajuda as cita.

Estado atual

1. A validação no navegador usa o esquema, e o SignupForm.test.tsx passa.
2. O servidor ainda chama a antiga validateSignup() em api/signup.ts.

Detalhes exatos: as senhas precisam de pelo menos 8 caracteres e um número. Texto do erro de e-mail: "Informe um endereço de e-mail válido."

Próximo passo: trocar validateSignup() pelo esquema e rodar os testes da API.

Pergunta em aberto: um e-mail já cadastrado deve retornar 409 ou 400?

Memória entre sessões

Memória é o contexto que sobrevive a uma conversa: fatos gravados no fim de uma sessão e carregados na seguinte. Os apps de chat oferecem versões disso, como memórias salvas ou instruções de projeto acrescentadas a todo chat de um projeto. Na sua própria aplicação, a memória é uma tabela ou um arquivo de notas que o seu código lê e insere. Duas regras a mantêm útil: guarde fatos que continuam verdadeiros (plano, idioma, stack preferida), não transcrições; e carregue só o que é relevante para a tarefa atual, porque a memória disputa o mesmo espaço que todo o resto.

Montando o contexto no código

Em uma aplicação, a engenharia de contexto é código comum. Este esboço com o SDK Python da Anthropic coloca as regras fixas e a memória no prompt de sistema, mantém só o histórico recente e coloca os documentos rotulados antes da pergunta.

import anthropic

client = anthropic.Anthropic()
MODEL = "your-model-id"  # e.g. from your provider's model list

def build_context(question, docs, history, memory, max_messages=6):
    documents = "\n".join(
        f'<document source="{d["source"]}">\n{d["text"]}\n</document>' for d in docs
    )
    system = (
        "You are the support assistant for Acme Notes. Answer only from the documents. "
        "If they do not cover the question, say so.\n"
        f"<memory>\n{memory}\n</memory>"
    )
    # history holds complete user/assistant pairs, so an even slice starts with a user turn
    recent = history[-max_messages:]
    user = f"<documents>\n{documents}\n</documents>\n\n{question}"
    return system, recent + [{"role": "user", "content": user}]

# question, docs, history and memory come from your application
system, messages = build_context(question, docs, history, memory)
response = client.messages.create(model=MODEL, max_tokens=1024, system=system, messages=messages)
print(response.content[0].text)

Cada decisão dessa função (quais documentos, quantas mensagens, onde fica a memória) é uma escolha de engenharia de contexto, e cada uma merece ser testada com perguntas reais, do mesmo jeito que você testaria uma mudança na redação.