Context Engineering para AI Agents: Memória e Tools

Viacheslav Dubrov

2025-10-05 · Atualizado 2026-08-16 · 17 min · Agentes de IA

Tradução automática Este artigo foi traduzido automaticamente a partir da versão original em inglês.

Context engineering é o pipeline que seleciona aquilo que um modelo vê antes de cada decisão: instruções, exemplos, conhecimento, memória, definições de tools, observações e guardrails. Um agent não atua sobre tudo o que o sistema conhece. Atua sobre o working set reunido para a próxima chamada ao modelo.

É nessa seleção que começam muitas falhas. Uma preferência obsoleta parece atual. O texto obtido por retrieval contém uma instrução. Um resultado extenso de uma tool esconde a precondição que falhou. Um resumo retém a decisão, mas perde a informação sobre o ficheiro que foi alterado.

Para os engenheiros que desenvolvem ou operam AI agents, sistemas de retrieval e aplicações que utilizam tools, o trabalho prático consiste em reunir o menor working set suficiente para cada decisão do agent, preservando simultaneamente o âmbito, a proveniência e as permissões. Este artigo mostra como conceber um pipeline de contexto por decisão, identificar os seus limites de confiança, testar se o seu working set suporta a tarefa e tornar as falhas observáveis, em vez de culpar um modelo que apenas vê o input reunido.

TL;DR. Trate o contexto como um artefacto de runtime tipado e com proveniência. Selecione-o por etapa, aplique o âmbito do tenant e das permissões antes do retrieval e separe instruções fidedignas de dados não fidedignos. Faça o orçamento com base na utilidade, valide as ações fora do modelo e avalie os resultados da tarefa, não apenas o tamanho do contexto.

O contexto é um input da decisão, não memória

A context window é o input atual do modelo mais os tokens gerados. Pode conter turnos da conversa, mas não é um sistema de memória persistente. A memória de longo prazo, os índices de documentos, as bases de dados e os repositórios de artefactos vivem fora da window. Um pipeline de contexto escolhe o que deve copiar para dentro.

O tamanho da window é um limite de capacidade, não uma garantia de qualidade. Lost in the Middle e RULER mostram que o retrieval e o reasoning podem variar consoante a posição, a tarefa, o modelo e o comprimento da sequência. A lição operacional não é que os tokens no meio sejam sempre ignorados. É que adicionar tokens aparentemente relevantes pode ainda assim reduzir o desempenho da tarefa.

O diagrama mostra o resultado qualitativo do estudo, não uma curva universal de attention. Liu et al. testaram question answering sobre múltiplos documentos e retrieval de pares chave-valor. Observaram frequentemente melhor desempenho quando o item relevante aparecia perto do início ou do fim. A dimensão e a forma do efeito variaram entre modelos, tarefas e comprimentos de contexto. Teste a posição como variável no seu próprio conjunto de avaliação, em vez de assumir uma penalização fixa para o meio.

O seguinte é um schema Pydantic ilustrativo, não uma implementação testada num repositório. Valida apenas tipos de campos e valores literais. Não autoriza o tenant, não mantém total_input_tokens consistente com items, não persiste o manifest nem impõe o comportamento do modelo.

from datetime import datetime
from typing import Literal

from pydantic import BaseModel

class ContextItem(BaseModel):
    item_id: str
    kind: Literal["instruction", "task_state", "evidence", "memory", "tool"]
    source: str
    trust: Literal["trusted", "untrusted"]
    retrieved_at: datetime | None = None
    version: str | None = None
    token_count: int

class ContextManifest(BaseModel):
    request_id: str
    tenant_id: str
    items: list[ContextItem]
    total_input_tokens: int

O manifest torna uma falha reproduzível. «O modelo alucinou» passa a ser uma pergunta testável: que evidência, versão, âmbito de permissões e tool schema recebeu efetivamente?

O ciclo de assembly

Um pipeline fiável executa estas operações pela seguinte ordem:

1. Resolver o contexto fidedigno do pedido. Autentique o actor, o tenant, o locale, a hora e o estado atual da tarefa fora do modelo.
2. Escolher a próxima decisão. Uma etapa de planeamento, uma consulta de evidência, a seleção de uma tool e uma resposta final requerem contextos diferentes.
3. Fazer retrieval dentro do âmbito. Aplique os filtros de autorização e de tenant antes do ranking semântico, e não depois de os documentos entrarem no conjunto de candidatos.
4. Ordenar e orçamentar. Selecione itens com base na utilidade, atualidade, autoridade e diversidade, dentro de um orçamento de input.
5. Fazer o assembly com limites de confiança. Mantenha a policy nos canais de instruções e apresente o conteúdo obtido por retrieval como dados entre aspas. As instruções obtidas por retrieval não se tornam policy do sistema.
6. Gerar uma proposta tipada. O structured output pode impor sintaxe e formato suportados. Não pode tornar os valores corretos.
7. Validar e executar. O código da aplicação verifica a autorização, as regras de negócio, os argumentos da tool e as pós-condições.
8. Registar a proveniência e o resultado. Guarde o manifest, os IDs das fontes selecionadas, as referências para os resultados das tools, o resultado da validação e o resultado da tarefa.

O ciclo é executado por decisão. Reutilizar um contexto grande para toda a execução de um agent cria evidência obsoleta e dá a cada etapa acesso a material de que não necessita.

Dê a cada fonte de contexto uma função

As instruções definem o comportamento duradouro

As instruções especificam o papel, a policy, o contrato de output e o comportamento de escalamento. Mantenha o conteúdo estável estável para melhorar o prefix caching, mas não congele valores que mudam em runtime. Um limiar de reembolso pertence a um serviço de policy ou a um registo de dados versionado, e não a um prompt copiado indefinidamente.

A hierarquia de instruções é um limite de controlo, não uma sandbox de segurança. Um modelo pode continuar a seguir texto malicioso num documento obtido por retrieval. Delimite o conteúdo não fidedigno, indique que é evidência e não instrução, restrinja as tools de forma independente e teste casos de prompt injection.

Não copie os nomes de roles de um provider para uma hierarquia universal. O OpenAI Model Spec define níveis de autoridade para instruções da plataforma ou do sistema, do developer e do utilizador. A Anthropic Messages API utiliza um parâmetro de topo system e mensagens user e assistant. Essa API não expõe uma role developer equivalente. Outros runtimes fazem escolhas diferentes. Mapeie a sua policy para os canais documentados pelo provider e imponha depois as permissões e os efeitos secundários no código da aplicação.

O estado da tarefa regista compromissos

A prosa da conversa é uma fonte de verdade fraca para trabalho em várias etapas. Mantenha um estado explícito para o objetivo, a fase atual, as ações concluídas, as aprovações pendentes, as referências para artefactos e o estado dos testes. O modelo pode resumir esse estado para fins de narração. O código da aplicação é responsável pela versão canónica.

Os exemplos demonstram decisões de fronteira

Os exemplos few-shot são úteis quando clarificam um limite difícil, não quando se limitam a repetir o schema. Selecione exemplos que correspondam à decisão atual e incluam casos de fronteira consequentes. Avalie o retrieval de exemplos como avalia o retrieval de documentos: um exemplo superficialmente semelhante mas incompatível com a policy pode ser pior do que nenhum exemplo.

O conhecimento fornece evidência

O retrieval é apropriado para factos recentes, privados ou citáveis. Não existe um top_k, tamanho de chunk, peso híbrido ou cutoff de reranker universalmente melhor. Ajuste o percurso completo com base em perguntas cuja evidência de suporte seja conhecida.

Um item de evidência útil inclui:

• fonte e identificador estável do documento
• versão ou data de entrada em vigor
• âmbito das permissões
• excerto citado e localização
• scores de retrieval e reranking para debugging

Não peça ao modelo para citar um URL que nunca recebeu. Não registe documentos privados completos apenas para fazer debugging da seleção.

A memória fornece continuidade com âmbito

A memória é um dado obtido por retrieval com riscos adicionais de ciclo de vida. Enquanto metadados de conceção, acompanhe o sujeito, a proveniência, a finalidade, a decisão aplicável de consentimento ou base jurídica, a data de criação, a policy de expiração ou revisão e o percurso de eliminação. A legislação de privacidade aplicável e o aconselhamento jurídico do produto determinam a base jurídica de um produto e dos seus dados, não esta checklist.

Regras fixas como «as preferências permanecem 365 dias» não são policy portável. A retenção segue a necessidade do produto, as expectativas do utilizador e a lei. Antes de carregar uma memória, verifique:

1. É relativa a este sujeito autenticado e a este tenant?
2. A finalidade é relevante para esta decisão?
3. Está suficientemente atualizada para ser utilizada?
4. A sua fonte é autoritativa ou foi apenas inferida pelo modelo?

Trate as memórias inferidas como hipóteses. Não transforme silenciosamente uma resposta de um modelo num facto permanente sobre o utilizador.

Os contratos de tools expõem capacidades

As descrições das tools devem explicar precondições, efeitos, âmbito de autorização, input schema, output schema, idempotência e falhas significativas. Uma chamada que respeite o schema pode ainda assim não estar autorizada ou ser insegura.

Depois da execução, substitua o output bruto e extenso por uma observação tipada que preserve o resultado relevante para a decisão e uma referência para o artefacto completo:

{
    "tool": "check_api_key_status",
    "status": "revoked",
    "checked_at": "2026-07-15T09:30:00Z",
    "account_id": "A-123",
    "artifact_ref": "toolrun://req-42/step-3"
}

A especificação MCP normaliza a forma como os clientes interagem com tools, resources e prompts. Não autoriza a sua utilização nem torna fidedigno o conteúdo devolvido. Mantenha as verificações do gateway, das credenciais e da policy fora do modelo e da descrição do protocolo.

Carregue detalhe quando uma decisão dele necessita

A divulgação progressiva é um padrão de assembly de contexto: mantenha identificadores e o estado fidedigno da tarefa disponíveis e obtenha depois os detalhes necessários para a decisão atual. Não é uma promessa de que um orçamento específico de tokens funcionará para todos os modelos.

O router tem de aplicar a autorização e o âmbito do tenant antes do retrieval. Deve devolver excertos de evidência, registos de memória e tool schemas que sirvam a decisão atual. O modelo propõe então uma ação. O código da aplicação valida essa proposta antes da execução. A orientação da Anthropic sobre contexto de tools utiliza o mesmo princípio seletivo para conjuntos de tools grandes. A pesquisa de tools mantém as definições fora da context window até o modelo as solicitar. Meça se a etapa adicional de routing melhora o sucesso da tarefa, a latência e o número de tokens por tarefa bem-sucedida no seu sistema.

Como o contexto se degrada

Um contexto inadequado não falha de uma única forma. O seguinte modelo de degradação em cinco padrões é a minha síntese para debugging, informada pelas avaliações de contexto longo acima e pela investigação sobre prompt injection:

• Perda de posição: a evidência necessária está presente, mas o modelo utiliza-a de forma inconsistente devido à sua posição e à sequência envolvente. As avaliações de contexto longo mostram que o efeito varia consoante o modelo e a tarefa. Não existe um intervalo universal «problemático no meio».
• Poisoning: uma memória incorreta, um documento obsoleto, uma instrução maliciosa ou uma observação errada de uma tool entra no working set e influencia decisões posteriores.
• Distração: a evidência relevante compete com material recente ou semanticamente semelhante, mas desnecessário para a etapa atual.
• Confusão: instruções, exemplos ou tool descriptions sobrepostos deixam o modelo perante várias interpretações plausíveis da tarefa.
• Conflito: dois itens com aparência de autoridade discordam sobre um valor, uma policy ou a próxima ação, e o assembler não expõe as respetivas versões ou precedência.

Estas falhas exigem correções diferentes. Um ranking melhor pode ajudar na distração, mas não corrige uma fonte obsoleta. Delimitadores podem ajudar a separar dados de instruções, mas não podem autorizar uma tool. Uma context window maior pode preservar mais material em conflito sem resolver o conflito.

Quando uma execução falhar, inspecione o manifest e determine primeiro qual foi o padrão, antes de alterar o prompt ou adicionar outra etapa de retrieval.

Faça o orçamento com base na utilidade, não numa quota por componente

Um orçamento de contexto reserva primeiro espaço para o output e, depois, distribui o input pela decisão atual. Comece pela window suportada pelo modelo, subtraia o output máximo e o overhead do protocolo e reúna os candidatos no espaço restante.

Atribua scores aos candidatos com features que as suas avaliações possam pôr à prova:

utility = relevance × authority × freshness × scope_match
          − redundancy_penalty − injection_risk

Trate a fórmula como um ponto de partida para a conceção. Numa resposta sobre policy, a autoridade pode ter mais peso do que a semelhança semântica. Em debugging, um log recente de uma falha pode superar a documentação geral.

A ordem também importa. Mantenha as instruções fidedignas e estáveis no início quando a semântica de cache do provider beneficia de um prefixo partilhado. Coloque a tarefa e a decisão atuais perto da evidência a que se referem. Evite timestamps ou IDs de pedidos em prefixos estáveis quando não forem necessários nesse local.

Comprima sem perder o estado

A compressão é uma operação com perdas, a menos que o original continue endereçável. A avaliação da Factory Research sobre três abordagens de compressão em sessões longas de agents enquadra o objetivo como tokens por tarefa, não tokens por pedido. Adapto isso para uma recomendação de engenharia: otimize tokens por tarefa bem-sucedida, e não tokens por pedido, em condições de tarefa comparáveis — não como uma lei universal. Avaliação da Factory Research

Utilize mecanismos separados para materiais separados:

• Conversa: resuma decisões, questões por resolver e compromissos.
• Observações de tools: retenha conclusões tipadas e referências para artefactos. Remova boilerplate e payloads repetidos.
• Evidência obtida por retrieval: mantenha IDs das fontes, excertos de suporte e datas de entrada em vigor para que o sistema possa voltar a obtê-la.
• Estado da tarefa: armazene-o de forma canónica fora do resumo.
• Rasto de ficheiros ou artefactos: mantenha um índice explícito de leituras, escritas, hashes e resultados de testes.

Acione a compactação com base numa degradação medida ou num limiar de orçamento escolhido para o modelo e a tarefa. Não publique uma regra genérica de «comprimir aos 70%» como se todos os modelos falhassem no mesmo ponto.

Avalie a compressão com probes que exijam continuação, e não sobreposição lexical:

• Qual é o objetivo atual e a próxima ação?
• Que ficheiros ou registos foram alterados?
• Que decisão foi rejeitada e porquê?
• Que fonte suporta a afirmação atual?
• Que aprovação continua pendente?

Execute a mesma tarefa com e sem compressão. Compare o sucesso, as ações incorretas, os novos retrievals, a latência e o total de tokens.

Otimize o percurso do contexto

A otimização deve preservar o contrato da decisão. Quatro técnicas são úteis quando já existe um bottleneck medido:

Estas técnicas resolvem problemas diferentes. A compactação e a edição de contexto podem reduzir o conteúdo enviado ao modelo. O carregamento seletivo de tools evita o envio de schemas não utilizados. O prompt caching pode reduzir o custo de prefixos repetidos, mas não reduz o número de tokens na context window. O particionamento altera as capacidades e a evidência que cada decisão recebe. O guia da Anthropic sobre contexto de tools explicita estas distinções, e a sua documentação sobre edição de contexto disponibiliza triggers configuráveis, em vez de um limiar universal.

Compacte o histórico concluído

Substitua turnos antigos da conversa por um handoff estruturado que registe decisões, questões por resolver, artefactos alterados e o estado dos testes. Mantenha o transcript ou os artefactos originais endereçáveis quando a revisão ou a recuperação o exigirem.

Oculte observações extensas

Uma tool pode devolver páginas de logs quando a etapa seguinte necessita apenas de um estado, um código de erro e uma referência para um artefacto. Converta o resultado bruto numa observação tipada depois de o validar e mantenha o payload completo fora do prompt. Não permita que o modelo resuma e elimine a única evidência da falha.

Preserve prefixos passíveis de cache

Os providers e runtimes podem reutilizar trabalho quando o início de um pedido permanece estável. Mantenha as instruções duradouras e os tool schemas numa ordem consistente e mova timestamps, IDs de pedidos, evidência obtida por retrieval e estado atual para o sufixo dinâmico. Confirme a semântica de cache do provider antes de conceber o sistema com base nela.

Particione por decisão

Um planner, um retriever, um tool caller e uma etapa de resposta final não necessitam do mesmo material. Dê a cada etapa apenas as instruções fidedignas, o estado, a evidência e as tools de que necessita. O particionamento reduz simultaneamente a utilização de tokens e a exposição de capacidades, mas apenas avaliações ao nível da tarefa podem mostrar se removeu informação necessária.

Proteja a cadeia de fornecimento do contexto

A investigação sobre prompt injection trata o conteúdo externo não fidedigno como uma superfície de ataque (artigo). No modelo operacional deste artigo, o poisoning do contexto pode chegar através de documentos, memórias, resultados de tools, skills ou mensagens anteriores do assistant. Marcar o texto como «não fidedigno» ajuda o modelo, mas o enforcement tem de ser arquitetural.

A seguinte checklist da cadeia de fornecimento é a minha recomendação de engenharia. Converte limites de protocolo e de threat model em controlos da aplicação. Nem a especificação MCP nem o artigo sobre prompt injection impõem esta checklist completa.

Utilize estes limites:

1. Autorize antes do retrieval e da execução de tools.
2. Separe dados dos canais de instruções e delimite o texto externo.
3. Permita tools numa allowlist por etapa e actor. Por predefinição, não conceda capacidades com efeitos secundários.
4. Valide identificadores de recursos, em vez de permitir que o modelo invente chaves de tenants ou caminhos de ficheiros.
5. Exija confirmação para operações de elevado impacto com base na policy, não na confiança do modelo.
6. Analise e reveja skills executáveis ou connectors antes da instalação.
7. Impeda que secrets e contexto sensível bruto entrem nos logs e na memória de longo prazo.

A «reparação» automática só é apropriada para alterações que preservem o significado, como analisar uma data num formato conhecido. Preencher argumentos em falta de uma tool com «predefinições sensatas» pode alterar a operação. Peça esclarecimentos ou rejeite quando o significado for incerto.

Exemplo prático: um pedido de suporte sobre uma API key

Para «Porque é que a minha API key não funciona?», a próxima decisão consiste em recolher evidência de diagnóstico, e não em gerar a resposta final. O assembler pode incluir:

• a policy de suporte fidedigna e o contrato de resposta
• o ID autenticado da conta e o plano, provenientes do estado da aplicação
• o objetivo atual do ticket e as ações já tentadas
• dois excertos atuais do runbook, selecionados dentro do âmbito do produto e da versão
• uma memória com âmbito que indica que a key foi criada há três dias, com proveniência
• check_api_key_status e search_incidents, mas não tools de eliminação ou rotação da key

O modelo propõe uma verificação de estado apenas de leitura. O código da aplicação autoriza a conta, chama a tool e regista uma observação tipada. Uma segunda chamada ao modelo recebe os excertos relevantes do runbook juntamente com essa observação. A resposta final cita a versão do runbook, nunca imprime a key e oferece a rotação apenas como uma ação autorizada separadamente.

Note o que fica de fora: histórico não relacionado do ticket, todos os exemplos de suporte, dumps brutos da conta, tools de mutação e memórias de outros tenants.

Anti-patterns a testar explicitamente

• Encher a window: carregar todos os documentos, histórico, memórias e tools obtidos por retrieval só porque ainda existe capacidade.
• RAG em todo o lado: utilizar retrieval semântico para valores que pertencem a uma base de dados, a um serviço de policy ou ao estado autenticado da aplicação.
• Memória sem limites: conservar factos inferidos sem semântica de âmbito, expiração, correção ou eliminação.
• Uma chamada para cada etapa: pedir a um único prompt que faça retrieval, reasoning, autorização, mutação e explicação sem limites observáveis.
• Schema igual a correção: tratar JSON válido como prova de que os valores, as permissões ou as decisões de negócio são válidos.
• Ausência de avaliações por componente: avaliar apenas a prosa final e ignorar falhas de retrieval, seleção de contexto ou tools.

Transforme cada anti-pattern num contraexemplo do conjunto de avaliação. Uma guideline que nunca seja exercitada por uma tarefa ou trace é fácil de violar sem que ninguém se aperceba.

Avalie o assembler, não apenas a resposta

Crie um conjunto fixo de tarefas com labels de evidência, limites de permissões, tool calls obrigatórias e ações proibidas. Para cada alteração da policy de contexto, meça:

Utilize ablations para encontrar o valor causal: remova a memória, o reranking, os exemplos ou a compressão, um de cada vez. Um componente que adiciona tokens sem melhorar a fatia relevante não deve ser carregado por predefinição.

Conclusão

Um bom context engineering é seletivo e responsável. Não preenche uma window grande apenas porque existe capacidade disponível. Constrói um working set específico para cada etapa a partir de instruções fidedignas, estado canónico da tarefa, evidência com âmbito, memória revista e tools permitidas.

O loop é curto: reunir, criar o manifest, propor, validar, executar e avaliar. Quando uma decisão falha, esse loop indica se faltava evidência, atualidade, autoridade, estado ou policy. Também fornece um teste para a próxima alteração.

Referências

• Lost in the Middle — utilização de contexto longo dependente da posição
• RULER — avaliação multitarefa do comprimento efetivo do contexto
• OpenAI Model Spec — níveis de autoridade das instruções específicos do provider
• Anthropic Messages API — parâmetro de sistema e estrutura das roles das mensagens
• Manage tool context — carregamento seletivo de tools, caching e edição de contexto
• Anthropic context editing — limpeza configurável de resultados de tools e compactação
• Model Context Protocol specification — conceitos do protocolo e especificação atual
• Evaluating Context Compression for AI Agents — enquadramento em tokens por tarefa e avaliação baseada em probes
• Formalizing and Benchmarking Prompt Injection Attacks and Defenses — taxonomia de ameaças e defesas