Context Engineering
Contexto é tudo o que o modelo recebe para produzir a próxima saída: instruções, pedido, histórico, documentos e resultados de ferramentas. Engenharia de contexto escolhe esse conjunto de forma deliberada. A pergunta deixa de ser “qual frase devo escrever?” e passa a ser “qual informação precisa estar disponível agora?”.
Vamos acompanhar um atendimento longo que muda de objetivo. O cliente começou com cobrança, depois pediu acesso e por fim corrigiu o número do pedido. Um sistema útil precisa preservar correções, buscar dados atuais e descartar detalhes irrelevantes sem transformar resumos em fatos incontestáveis.
JavaScriptAo terminar esta aula
- Contexto útil combina conteúdo, origem e finalidade.
- Compactação precisa preservar decisões e exceções.
- Estado, memória e cache resolvem problemas diferentes.
Antes de continuar: Laboratório: Prompt Engineering + testes
Seleção de contexto e relevância
FundamentosSelecionar contexto é decidir quais informações ajudam a tarefa atual e quais apenas aumentam ruído. Uma conversa completa pode conter dados desatualizados, instruções abandonadas e resultados de consultas antigas. Enviar tudo não resolve automaticamente essas contradições. Para atender ao pedido de acesso, inclua a identificação corrigida, a política vigente e o estado autorizado da matrícula. A antiga discussão sobre outro pagamento pode ser desnecessária. A seleção deve preservar relações causais e exceções que alteram a decisão.
↗ Effective context engineering for AI agents↗ OpenAI Retrieval
Uma boa unidade de contexto possui conteúdo, origem e finalidade. “Pedido 72” sem indicar que substitui o pedido 27 é ambíguo. Um resultado de consulta deve carregar data e escopo da conta. Essa organização permite remover redundância sem remover significado. A documentação de engenharia de contexto descreve estratégias como recuperar dados quando necessários e manter notas úteis. São orientações de desenho, não uma fórmula universal para relevância. A melhor seleção precisa ser avaliada com casos em que detalhes aparentemente pequenos mudam a resposta.
↗ Effective context engineering for AI agents↗ OpenAI Retrieval
Context budgeting e reserva para saída
FundamentosOrçamento de contexto distribui a capacidade disponível entre categorias de informação. Reserve espaço para instrução, tarefa atual, evidências e resposta. A contagem depende do tokenizador e do endpoint; não use número de palavras como limite exato. Se o histórico ocupa todo o orçamento, documentos atuais podem ser excluídos. Se a evidência ocupa tudo, a resposta pode ser truncada. O sistema precisa de uma política explícita para esse conflito antes de encontrar o limite em produção.
↗ Effective context engineering for AI agents↗ Conversation state
Comece com prioridades: política essencial, pedido vigente e evidência necessária. Depois adicione histórico útil. Quando houver excesso, selecione, compacte ou consulte por referência, em vez de remover o final silenciosamente. Documente o que foi excluído. Um orçamento estático simples é um ponto inicial, mas tarefas diferentes precisam de proporções diferentes. Um resumo de muitos documentos não deve receber a mesma política de um pedido curto de suporte. Meça o desempenho dos casos limite e o custo do contexto efetivamente enviado.
↗ Effective context engineering for AI agents↗ Conversation state
Poluição, rot e contradições
FundamentosContext pollution é uma forma de descrever informação irrelevante, enganosa ou conflitante acumulada no contexto. Context rot descreve degradação observada no uso de grandes volumes ou longas interações, não um prazo universal após o qual um modelo deixa de funcionar. O efeito depende da tarefa e do sistema. O problema prático é que mais texto pode dificultar a seleção da evidência certa, mesmo quando cabe na janela.
↗ Effective context engineering for AI agents↗ Conversation state
No atendimento, uma nota antiga dizendo “pagamento pendente” não deve vencer uma consulta atual dizendo “pagamento confirmado”. Explicite versão, tempo e precedência factual. Diferencie instrução de usuário, resultado externo e anotação inferida. Se o modelo recebe várias cópias de uma hipótese antiga, a repetição pode dar aparência de certeza sem fornecer evidência adicional. Remova duplicatas e registre correções. Não resolva conflitos apenas escolhendo a frase mais recente se ela vier de fonte sem autoridade para aquele fato.
↗ Effective context engineering for AI agents↗ Conversation state
Compactação, sumarização e recuperação dinâmica
FundamentosCompactação reduz o volume preservando informação necessária para continuar. Sumarização produz uma representação textual menor, mas pode perder condições e referências. Um bom resumo operacional preserva objetivo vigente, decisões, identificadores, fatos com origem, pendências e restrições. Não grave “cliente aprovado” se a consulta apenas iniciou. Guarde o identificador do artefato original para recuperar detalhes quando a tarefa exigir. O resumo é uma representação de trabalho sujeita a verificação.
↗ Effective context engineering for AI agents↗ OpenAI Retrieval↗ LangGraph Memory
Recuperação dinâmica busca documentos ou estado quando a tarefa precisa deles. Ela evita carregar toda a base em cada chamada, mas introduz dependência de consulta, filtros e disponibilidade. Recuperar um documento relacionado não significa que ele pertence à conta correta ou está vigente. A aplicação deve filtrar escopo e versão antes de montar o contexto. Compare compactação com recuperação: uma preserva continuidade resumida, a outra encontra evidência externa. Frequentemente as duas se complementam, desde que o sistema saiba qual informação foi resumida e qual foi consultada agora.
↗ Effective context engineering for AI agents↗ OpenAI Retrieval↗ LangGraph Memory
Estado, memória, cache e handoff
FundamentosSession state registra a continuidade de uma execução ou conversa. Memória curta costuma acompanhar a interação atual; memória longa persiste informação entre interações segundo regras da aplicação. Nem todo histórico merece persistência durável. Uma preferência de idioma pode ser útil depois; um número corrigido de pedido pertence a um caso específico. Misturar escopos pode reaplicar dados antigos a uma pessoa ou atendimento diferente. Use identificadores, origem e política de atualização.
↗ Conversation state↗ LangChain Memory overview↗ LangGraph Persistence↗ Prompt caching↗ Effective context engineering for AI agents
Context caching reutiliza processamento de prefixos conforme as regras do provedor. Ele pode afetar custo e latência, mas não é memória semântica nem autorização para recuperar fatos de sessões anteriores. Handoff transfere trabalho para outra etapa ou agente. Um pacote útil inclui objetivo, estado, evidências referenciadas, decisões e próximos passos, evitando despejar todo o histórico. O receptor verifica o que está concluído e o que continua pendente. Transferir um resumo sem origem pode propagar erros; transferir credenciais ou dados fora do escopo amplia exposição sem necessidade.
↗ Conversation state↗ LangChain Memory overview↗ LangGraph Persistence↗ Prompt caching↗ Effective context engineering for AI agents
Exemplo comentado e limites
FundamentosO código consolida versões por chave em um conjunto fictício de escopo único. Ele ilustra atualização explícita: a correção de pedido não é tratada como mais uma frase solta. A confirmação de pagamento tem origem distinta da declaração do usuário. Em produção, versões precisam estar vinculadas ao mesmo objeto e à mesma autoridade; comparar qualquer número de versão globalmente seria incorreto.
const fatos = [
{chave:"pedido",valor:"27",versao:1,origem:"usuario"},
{chave:"pedido",valor:"72",versao:2,origem:"correcao-usuario"},
{chave:"pagamento",valor:"confirmado",versao:1,origem:"consulta-autorizada"}
];
const atual = new Map();
for (const fato of fatos) {
const anterior = atual.get(fato.chave);
if (!anterior || fato.versao > anterior.versao) atual.set(fato.chave,fato);
}
console.log({objetivo:"verificar acesso",fatos:[...atual.values()],
pendencias:["consultar matricula para o pedido 72"]});A pendência mostra que pagamento confirmado não equivale a acesso ativado. O handoff transfere apenas o objetivo atual e fatos relevantes, mantendo o próximo passo separado do que já foi feito. Um receptor pode verificar a origem antes de agir. O programa não conta tokens, não executa cache e não implementa persistência externa.
Exercício aplicado
Um atendimento corrigiu o pedido e a política mudou. Prepare um pacote de continuidade que preserve correção, origem e pendências.
- Execute e inspecione a consolidação.
- Vincule fatos a atendimento, origem e versão comparável.
- Escreva resumo com objetivo, fatos, evidências, restrições e pendências.
- Teste perda de exceção e recuperação de artefato original; documente orçamento e política de descarte.
Abrir resolução comentada
A solução preserva a correção, busca a política vigente e consulta a matrícula para o pedido atual. O resumo registra a mudança em vez de ocultá-la. Se o orçamento é insuficiente, referências aos artefatos originais permitem recuperar detalhes; uma nota compactada não deve substituir uma consulta obrigatória.
A avaliação inclui um caso em que remover uma exceção produz decisão errada. Compare o pacote compactado com o histórico completo e o resultado autorizado. Registre quais fatos o resumo perdeu, corrigindo a política de compactação. Economia de tokens sem preservação de decisão é uma redução inadequada.
Uma boa entrega mantém correções explícitas e permite voltar à evidência original. A memória durável armazena apenas informação com finalidade e escopo definidos. O cache aparece como otimização de infraestrutura, não como solução para conservar fatos da conversa.
A solução usa atendimento junto da chave factual, preserva versões comparáveis e separa pendências de ações concluídas. Ela detecta um resumo que perdeu a exceção e recupera o original por referência. montarContexto aplica reserva de saída, prioridade e descarte explícito, rejeitando excesso essencial. As contagens são fixtures fornecidas, não contagem de palavras apresentada como tokens reais; o chat integrado usa o tokenizador do modelo.
import assert from "node:assert/strict";
const originais=new Map([["politica-v2","Acesso após confirmação; pode exigir análise manual."]]);
const fatos=[
{atendimento:"a1",chave:"pedido",valor:"27",versao:1,origem:"usuario"},
{atendimento:"a1",chave:"pedido",valor:"72",versao:2,origem:"correcao-usuario"},
{atendimento:"a2",chave:"pedido",valor:"99",versao:1,origem:"usuario"},
{atendimento:"a1",chave:"pagamento",valor:"confirmado",versao:1,origem:"consulta-autorizada"}
];
const atuais=new Map();
for(const fato of fatos){const id=JSON.stringify([fato.atendimento,fato.chave]);const antigo=atuais.get(id);
if(!antigo||fato.versao>antigo.versao)atuais.set(id,fato);}
function handoff(atendimento){return {atendimento,objetivo:"verificar acesso",
fatos:[...atuais.values()].filter(x=>x.atendimento===atendimento),
evidencias:["politica-v2"],restricoes:["Não afirmar ativação sem consulta à matrícula"],
pendencias:["consultar matrícula"],acoesConcluidas:[...atuais.values()].some(x=>x.atendimento===atendimento&&x.chave==="pagamento")?["consultar pagamento"]:[]};}
function verificarResumo(resumo){
const original=originais.get(resumo.origem);
return !!original&&resumo.texto.includes("análise manual");
}
const resumoRuim={origem:"politica-v2",texto:"Acesso após confirmação."};
assert.equal(verificarResumo(resumoRuim),false);
const recuperado=originais.get(resumoRuim.origem);
assert.ok(recuperado.includes("análise manual"));
const resumoBom={origem:"politica-v2",texto:recuperado};assert.ok(verificarResumo(resumoBom));
const a1=handoff("a1"),a2=handoff("a2");
assert.equal(a1.fatos.find(x=>x.chave==="pedido").valor,"72");
assert.equal(a2.fatos.find(x=>x.chave==="pedido").valor,"99");
assert.ok(!a1.acoesConcluidas.includes("consultar matrícula"));
// Contagens fictícias já fornecidas: não representam tokenização de texto.
function montarContexto(itens,limite,reservaSaida){
const disponivel=limite-reservaSaida;
const essenciais=itens.filter(x=>x.essencial),opcionais=itens.filter(x=>!x.essencial);
let usado=essenciais.reduce((s,x)=>s+x.tokensMedidos,0);
if(usado>disponivel)throw new Error("ESSENCIAIS_EXCEDEM_ORCAMENTO");
const incluidos=[...essenciais],excluidos=[];
for(const item of opcionais){if(usado+item.tokensMedidos<=disponivel){incluidos.push(item);usado+=item.tokensMedidos;}
else excluidos.push(item.id);}
return {incluidos,excluidos,usado,reservaSaida};
}
const itens=[{id:"pedido-atual",essencial:true,tokensMedidos:20},
{id:"politica-com-excecao",essencial:true,tokensMedidos:30},
{id:"historico-irrelevante",essencial:false,tokensMedidos:100}];
const contexto=montarContexto(itens,100,20);
assert.deepEqual(contexto.excluidos,["historico-irrelevante"]);assert.equal(contexto.usado,50);
assert.throws(()=>montarContexto(itens,40,10),/ESSENCIAIS_EXCEDEM_ORCAMENTO/);
console.log({status:"aprovado",a1,a2,contexto,contagem:"fictícia; substituir por tokenizador do modelo"});Como conferir seu resultado
- Pedido corrigido é preservado.
- Escopos diferentes não se sobrescrevem.
- Pendências não aparecem como ações concluídas.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Comparar versões no mesmo namespace.
- Somar orçamento com reserva de saída.
Janela 120, saída 30, política 40, pedido 25, opcional 50. Pedido 18 foi corrigido para 81; outra sessão usa 18. Monte pacote.
Conferir raciocínio e critérios de domínio
Disponível 90; essenciais 65; opcional 50 não cabe.
Sessão corrigida usa 81; outra permanece 18 com origem/versionamento.
Conservar exceção, referências e consulta pendente; não marcar matrícula concluída.
Evidências para autoavaliação ou revisão por pares
- Orçamento: Disponível 90; essenciais 65; opcional 50 não cabe.
- Correção: Sessão corrigida usa 81; outra permanece 18 com origem/versionamento.
- Handoff: Conservar exceção, referências e consulta pendente; não marcar matrícula concluída.
Um erro frequente
Compactar permite apagar exceções.
Exceções decisivas precisam ser preservadas ou recuperadas.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Cache de prefixo é memória longa?
Não.
Cache reutiliza processamento segundo regras do serviço; memória tem persistência e recuperação definidas pela aplicação.
2. Mais contexto sempre melhora a resposta?
Não.
Ruído, conflitos e orçamento podem prejudicar uso de evidência.
3. Resumo elimina a necessidade de origem?
Não.
A representação pode perder detalhes; origem e referências permitem verificar e recuperar.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Effective context engineering for AI agents
Anthropic • consulta: 2026-10-06
AgentesIA & MLSeleção de contexto, orçamento de attention, context rot, recuperação just-in-time, compactação, notas e handoffs.
Limites: Context rot descreve efeito empírico, sem limite universal; compactação pode perder detalhes necessários.
- Conversation state
OpenAI • consulta: 2026-10-06
OpenAIEstado conversacional, histórico, continuidade e limites de contexto.
Limites: Estado da API não equivale automaticamente a memória longa; regras de persistência e cobrança são específicas da API.
- LangGraph Memory
LangChain • consulta: 2026-10-06
LangGraphAgentesPersistência de memória por thread/namespace, trimming, delete e summarization.
Limites: Memória deve ter identidade/tenant; apagamento efetivo precisa incluir índices, backups e traces conforme política da aplicação.
- OpenAI Retrieval
OpenAI • consulta: 2026-10-06
OpenAIIngestion, chunking/overlap, metadata/filtros, ranking e reescrita de consultas em vector stores.
Limites: Implementação gerenciada OpenAI; defaults não são melhores escolhas universais para pgvector.
- LangGraph Persistence
LangChain • consulta: 2026-10-06
LangGraphAgentesEstado, checkpoints, retomada e execução durável.
Limites: Reexecutar nós pode repetir efeitos; combinar persistência com idempotência e versões do estado.
- LangChain Memory overview
LangChain • consulta: 2026-10-06
FundamentosMemória curta e longa, semântica e episódica, perfis/coleções, atualizações e recuperação.
Limites: Taxonomia funcional, não equivalência com cognição humana; consolidar apenas fatos com proveniência e política definida.
- Prompt caching
OpenAI • consulta: 2026-10-06
OpenAICache de prefixos e impacto em custo/latência.
Limites: Cache depende de prefixo, modelo, política e prazo; não confundir cache com memória do agente.