2025-10-05 · Atualizado 2026-07-15

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

Context Engineering para AI Agentes: Janelas de Contexto, Memória, Ferramentas e Restrições

Context engineering é o pipeline responsável por determinar o que um modelo processa antes de tomar cada decisão: instruções, exemplos, conhecimento, memória, definições de ferramentas, observações e restrições. Um agente não age com base em todo o conhecimento disponível no sistema; ele atua apenas com o conjunto de dados preparado para a próxima chamada do modelo.

É nessa seleção que muitas falhas começam. Uma preferência desatualizada passa a parecer atual. O texto recuperado contém uma instrução. Um tool result muito longo oculta a precondição que falhou. Um resumo guarda a decisão tomada, mas perde o registro de qual ficheiro foi alterado.

A tarefa prática consiste em montar o conjunto de trabalho mínimo e suficiente para cada decisão, preservando simultaneamente o escopo, a proveniência e as permissões. Este artigo explica os padrões que utilizo e os limites que garantem a sua fiabilidade.

TL;DR. Trate o contexto como um artefato tipado e com informação de proveniência runtime. Selecione-o passo a passo, aplique restrições de tenant e escopo de permissões antes da recuperação, distinga instruções confiáveis de dados não confiáveis, defina um orçamento com base na utilidade, valide as ações fora do modelo e avalie os resultados da tarefa, em vez de se focar apenas no comprimento do contexto.

O contexto funciona como entrada para decisões, e não como memória

A janela de contexto é a entrada atual do modelo, acrescida dos tokens gerados. Pode conter turnos de conversação, mas não constitui um sistema de memória duradouro. A memória de longo prazo, os índices de documentos, as bases de dados e os repositórios de artefatos existem fora desta janela; é o contexto pipeline que decide quais elementos serão copiados para dentro dela.

O tamanho da janela representa um limite de capacidade, e não uma garantia de qualidade. Pesquisas com contexto longo, como Perdido no Meio e REGULADOR

Utilize um manifesto de contexto para cada chamada ao 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 manifesto torna a reprodução de falhas possível. A afirmação “O modelo gerou alucinações” transforma‑se numa questão passível de teste: que evidências, versão, escopo de permissões e tool schema foram efetivamente recebidos?

O ciclo de vida da montagem

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

1. Resolver o contexto da solicitação confiável. Autenticar o ator, o inquilino, a localização, a hora e o estado atual da tarefa fora do modelo.
2. Escolher a próxima decisão. Um passo de planeamento, busca de evidências, seleção de ferramentas e resposta final exigem contextos diferentes.
3. Recuperar dentro do escopo. Aplicar filtros de autorização e de inquilino antes da classificação semântica, e não após os documentos entrarem no conjunto de candidatos.
4. Classificar e orçamentar. Selecionar itens com base em utilidade, atualidade, autoridade e diversidade, respeitando um orçamento definido.
5. Montar com limites de confiança. Manter as políticas nos canais de instrução e citar o conteúdo recuperado como dado; as instruções obtidas não se tornam políticas do sistema.
6. Gerar uma proposta estruturada. Uma saída restrita pode impor a sintaxe e a forma permitidas, mas não consegue corrigir os valores.
7. Validar e executar. O código da aplicação verifica a autorização, as regras de negócio, os argumentos das ferramentas e as condições pós-execução.
8. Registar a proveniência e o resultado. Salvar o manifesto, os IDs das fontes selecionadas, as referências tool result, o resultado da validação e o desfecho da tarefa.

O ciclo de vida é definido por decisão. Reutilizar um contexto amplo durante toda a execução de um agente gera evidências desatualizadas e permite que cada etapa aceda a informações de que não precisa.

Atribuir uma única tarefa a cada fonte de contexto

As instruções definem um comportamento duradouro

As instruções definem o papel, a política, o contrato de saída e o comportamento de escalonamento. Deve‑se manter o conteúdo estável para otimizar o cache de prefixos, mas não se deve congelar valores que sofrem alterações em runtime. O limiar de reembolso deve estar inserido num serviço de política ou num registo de dados versionado, e não copiado para um prompt de forma indefinida.

A hierarquia de instruções representa uma fronteira de controlo, e não uma medida de segurança sandbox. Um modelo ainda pode seguir texto malicioso presente num documento recuperado. É necessário delimitar o conteúdo não fidedigno, esclarecendo que se trata de evidência e não de instruções, restringir as ferramentas de forma independente e testar casos de injeção prompt.

Registos de estado da tarefa e compromissos

O texto de uma conversa é uma fonte pouco fiável de informação para tarefas com vários passos. É necessário manter um estado explícito que indique o objetivo, a fase atual, as ações concluídas, as aprovações pendentes, as referências aos artefatos e o status dos testes. O modelo pode resumir esse estado para fins narrativos; no entanto, o código da aplicação detém a versão canônica dessas informações.

Os exemplos ilustram as decisões de borda

Os exemplos de few-shot são úteis quando ajudam a esclarecer uma fronteira complexa, em vez de se limitarem a repetir o esquema. Selecione exemplos que correspondam à decisão atual e inclua casos limítrofes relevantes. Avalie a recuperação de exemplos da mesma forma que a recuperação de documentos: um exemplo aparentemente semelhante, mas incompatível com as políticas definidas, pode ser pior do que não haver nenhum exemplo disponível.

O conhecimento fornece evidências

A recuperação de informação é adequada para factos atuais, privados ou citáveis. Não existe uma solução ótima universal. top_ko tamanho do bloco, o peso híbrido ou o limite definido por reranker. Ajuste todo este conjunto de parâmetros em função de questões que dispõem de evidências de suporte conhecidas.

Um elemento de evidência útil inclui:

• identificador de documento de origem e estável
• versão ou data de entrada em vigor
• âmbito das permissões
• intervalo citado e localização
• pontuações de recuperação e reranking para depuração

Não peça ao modelo que cite uma URL que nunca recebeu. Não registe documentos privados completos apenas para depurar a seleção.

Fornecimento de memória que assegura continuidade no escopo definido

A memória representa dados recuperados que apresentam riscos adicionais ao longo do seu ciclo de vida. Cada registo exige indicação do sujeito em questão, da proveniência, do propósito, do consentimento ou da base legal aplicável, da data de criação, de uma política de expiração ou revisão, bem como de um procedimento para a sua eliminação.

Regras fixas, como “as preferências permanecem válidas por 365 dias”, não constituem uma política de portabilidade. A retenção de dados depende das necessidades do produto, das expectativas dos utilizadores e da legislação em vigor. Antes de carregar uma memória, verifique:

1. Destina‑se a este sujeito e inquilino autenticados?
2. A sua finalidade é relevante para esta decisão?
3. Está atualizado o suficiente para ser utilizado?
4. A sua fonte é fidedigna ou resulta apenas de inferência por modelo?

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

Os contratos de ferramenta expõem as capacidades disponíveis

As descrições das ferramentas devem esclarecer as pré-condições, os efeitos, o âmbito de autorização, o esquema de entrada, o esquema de saída, a idempotência e os cenários de falha com significado. Uma chamada que esteja em conformidade com o esquema ainda pode ser considerada não autorizada ou insegura.

Após a execução, substitua a saída bruta e verbosa por uma observação formatada que preserve o resultado relevante para a decisão e faça referência ao artefato 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"
}

MCP padroniza a forma como os clientes descobrem ferramentas, recursos e prompts; no entanto, não autoriza a sua utilização nem garante que o conteúdo retornado seja fidedigno. É necessário manter as verificações relativas a gateways, credenciais e políticas fora da descrição do modelo e do protocolo.

Como o contexto se degrada

Um contexto deficiente não causa falhas de apenas uma forma. A versão original deste guia separou vários padrões que continuam a ser úteis durante a depuração:

• 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 circundante. Avaliações em contexto longo mostram que isto varia consoante o modelo e a tarefa; não existe uma gama universal de “meio ruim”.
• Envenenamento: uma memória incorreta, um documento desatualizado, uma instrução maliciosa ou uma observação de ferramenta inadequada entra no conjunto de trabalho e influencia decisões posteriores.
• Distração: evidências relevantes competem com material recente ou semanticamente semelhante, mas desnecessário para o passo atual.
• Confusão: instruções, exemplos ou descrições de ferramentas sobrepostos deixam o modelo com várias interpretações plausíveis da tarefa.
• Conflito: dois itens que parecem ser autoritativos discordam sobre um valor, uma política ou a próxima ação, e o montador não exibe as suas versões nem a sua precedência.

Estes falhas exigem soluções diferentes. Uma classificação mais eficaz pode ajudar a reduzir a distração, mas não consegue corrigir uma fonte desatualizada. Delimitadores podem auxiliar na separação de dados de instruções, mas não conseguem autorizar a utilização de uma ferramenta. Uma janela de contexto maior permite manter mais informações conflituosas sem resolver esses conflitos.

Quando uma execução falhar, inspecione o manifesto e verifique qual padrão ocorreu antes de alterar o prompt ou adicionar outra fase de recuperação de dados.

Orçamento por serviço, e não por quota de componente

Um orçamento de contexto reserva espaço para a saída e, em seguida, aloca a entrada à decisão atual. Comece com o intervalo suportado pelo modelo, subtraia o tamanho máximo da saída e as despesas de protocolo, e organize os candidatos no espaço que resta.

Avalie os candidatos com características que as suas avaliações possam questionar:

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

A fórmula representa um prompt de projeto, e não uma teoria matemática universal. Nas respostas baseadas em regras, a autoridade pode ter maior peso na determinação da semelhança semântica. Durante a depuração, um registo de erro recente pode ter prioridade sobre a documentação geral.

A ordem também é importante. Mantenha primeiro as instruções estáveis e de confiança, sempre que a semântica de cache do fornecedor se beneficie de um prefixo partilhado. Coloque a tarefa e a decisão atuais perto das evidências a que se referem. Evite timestamps ou IDs de pedido nos prefixos estáveis quando não forem necessários nesses locais.

Comprimir sem perder o estado

A compressão é com perda, a menos que o original continue acessível. Otimize os tokens por tarefa concluída, e não os tokens por pedido: um resumo excessivamente agressivo que obrigue à recuperação de dados ou resulte num tool call incorreto não é mais económico.

Utilize mecanismos distintos para materiais diferentes:

• Conversa: resumir decisões, questões por resolver e compromissos.
• Observações de ferramentas: manter os resultados digitados e as referências aos artefatos; remover texto genérico e dados repetidos.
• Evidências recuperadas: conservar os IDs de origem, os trechos de suporte e as datas de validade para que o sistema possa recuperá-las novamente.
• Estado da tarefa: armazenar de forma padronizada fora do resumo.
• Registo de ficheiros ou artefatos: manter um índice explícito de leituras, escritas, hashes e resultados de teste.

Acionar a compactação devido à degradação medida ou a um limiar orçamental definido para o modelo e a tarefa. Não se deve publicar uma regra genérica como “comprimir a 70%”, como se todos os modelos falhassem no mesmo ponto.

Avalie a compressão com sondagens que exigem continuação, e não sobreposição lexical:

• Qual é o objetivo atual e a próxima ação a ser executada?
• Quais ficheiros ou registos foram alterados?
• Qual decisão foi rejeitada e porquê?
• Qual fonte suporta a afirmação atual?
• Que aprovações ainda estão pendentes?

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

Otimizar o caminho de contexto

A otimização deve preservar o contrato de decisão. Quatro técnicas do guia original continuam a ser úteis quando aplicadas a um gargalo identificado:

Histórico completo compactado

Substitua as conversas anteriores por uma transferência estruturada que registe as decisões tomadas, as questões ainda sem resposta, os artefatos modificados e o estado dos testes. Assegure que a transcrição original ou os artefatos permaneçam acessíveis sempre que for necessário efetuar uma revisão ou recuperação de informações.

Ocultar observações verbosas

Uma ferramenta pode retornar páginas de registos sempre que o passo seguinte necessitar de um estado, código de erro e referência de artefato. Após validá-lo, converta o resultado bruto numa observação tipada, mantendo todo o conteúdo adicional fora do prompt. Não permita que o modelo elimine a única evidência da falha.

Preservar prefixos cacheáveis

Os fornecedores e ambientes de execução podem reutilizar trabalho sempre que o início de uma solicitação se mantiver estável. Mantenha as instruções duradouras e tool schemas numa ordem consistente, transferindo os timestamps, IDs de solicitação, evidências recuperadas e o estado atual para o sufixo dinâmico. Confirme as semânticas de cache do fornecedor antes de projetar soluções à sua volta.

Partição por decisão

Proteger a cadeia de fornecimento de contexto

O envenenamento de contexto pode ocorrer através de documentos, memórias, tool results, competências ou mensagens anteriores do assistente. Marcar o texto como “não confiável” ajuda o modelo, mas a sua aplicação efetiva deve ser garantida a nível arquitetónico.

Utilize estes limites:

1. Autorize antes da recuperação de dados e da execução de ferramentas.
2. Separe os dados dos canais de instruções e delimite o texto externo.
3. Defina uma lista de permissões para as ferramentas por etapa e ator; o padrão deve ser a ausência de capacidade de efeitos colaterais.
4. Valide os identificadores de recursos em vez de permitir que o modelo crie chaves de utilizador ou caminhos de ficheiro.
5. Exija confirmação para operações de alto impacto com base nas políticas estabelecidas, e não na confiança do modelo.
6. Analise e revise as competências ou conectores executáveis antes da sua instalação.
7. Impida que segredos e conteúdos sensíveis brutos sejam registados nos logs ou na memória de longo prazo.

A “reparação” automática é adequada apenas para alterações que preservam o significado, como a análise de um formato de data conhecido. Preencher argumentos de ferramenta em falta com “valores padrão sensatos” pode alterar a operação. Peça esclarecimentos ou recuse a operação quando o significado for incerto.

Exemplo prático: um pedido de suporte para uma chave API

Para a pergunta “Porque é que a minha chave API não está a funcionar?”, a próxima etapa consiste na recolha de evidências diagnósticas — e não na geração de uma resposta definitiva. O montador pode incluir:

• política de suporte confiável e contrato de resposta
• ID da conta autenticada e plano obtidos a partir do estado da aplicação
• objetivo atual do ticket e ações já tentadas
• dois intervalos atuais do runbook selecionados no âmbito do produto/versão
• uma memória delimitada que indica que a chave foi criada há três dias, com informação sobre sua origem check_api_key_status e search_incidents, mas não as ferramentas de eliminação ou rotação de chaves

O modelo propõe uma verificação de estado somente de leitura. O código da aplicação autoriza a conta, chama a ferramenta e regista uma observação digitada. Uma segunda chamada ao modelo recebe os trechos relevantes do manual de operações, juntamente com essa observação. A resposta final indica a versão do manual de operações, nunca exibe a chave e oferece a rotação apenas como uma ação autorizada separadamente.

Repare no que é excluído: histórico de tickets não relacionados, todos os exemplos de suporte, extratos brutos de contas, ferramentas de mutação e registos de outros inquilinos.

Anti-padrões a testar explicitamente

• Preencher a janela: carregar todos os documentos recuperados, o histórico, as “memórias” e as ferramentas, desde que haja capacidade disponível.
• RAG em todo o lado: utilizar recuperação semântica para valores que pertencem a uma base de dados, a um serviço de políticas ou ao estado de uma aplicação autenticada.
• Memória ilimitada: reter factos inferidos sem qualquer restrição relativa a prazos de validade, possibilidade de correção ou eliminação.
• Uma chamada por cada fase: solicitar a um prompt que realize tarefas como recuperação, raciocínio, autorização, mutação e explicação, sem limites visíveis.
• Esquema igual a correção: considerar JSON válidos como prova de que valores, permissões ou decisões de negócio são corretos.
• Sem avaliação de componentes: avaliar apenas o texto final, ignorando falhas na recuperação de dados, na seleção de contexto ou no uso de ferramentas.

Transforme cada anti-padrão num contraexemplo no conjunto de avaliação. Uma diretriz que nunca é aplicada por uma tarefa ou registo é facilmente violada sem que se perceba.

Avalie o montador, e não apenas a resposta

Crie um conjunto de tarefas fixo com etiquetas de evidência, limites de permissão, tool calls obrigatórios e ações proibidas. Para cada alteração na política de contexto, meça:

Utilize ablações para determinar o valor causal: remova a memória, 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. Ele não preenche uma janela ampla, pois existe capacidade disponível. Ele constrói um conjunto de trabalho específico para cada etapa a partir de instruções fidedignas, estado de tarefa canónico, evidências delimitadas, memória revista e ferramentas autorizadas.

O ciclo duradouro é simples: montar, manifestar, propor, validar, executar e avaliar. Quando uma decisão falha, esse ciclo indica se o elemento em falta foi evidência, atualidade, autoridade, estado ou política — e fornece um teste para a próxima alteração.

Referências

• Perdido no Meio — utilização dependente da posição de contexto longo REGULADOR — avaliação multi-tarefa do comprimento efetivo de contexto
• Especificação do Protocolo de Contexto do Modelo — Conceitos de protocolo e especificações atuais Avaliação da compressão de contexto para agentes AI — estruturação por tokens por tarefa e avaliação baseada em sondagens Prompt injection ataques e defesas em LLMaplicações integradas — taxonomia de ameaças e mecanismos de defesa