Engenharia de Contexto Baseada em Sistema de Arquivos

O sistema de arquivos fornece uma interface única através da qual os agentes podem armazenar, recuperar e atualizar de forma flexível uma quantidade efetivamente ilimitada de contexto. Este padrão aborda a restrição fundamental de que as janelas de contexto são limitadas, enquanto as tarefas frequentemente exigem mais informações do que cabem em uma única janela.

A ideia central é que os arquivos permitem a descoberta dinâmica de contexto: os agentes puxam o contexto relevante sob demanda, em vez de carregar tudo na janela de contexto. Isso contrasta com o contexto estático, que é sempre incluído, independentemente da relevância.

Quando Usar

Ative esta habilidade quando:

• As saídas de ferramentas estiverem inflando a janela de contexto
• Agentes precisarem persistir o estado em trajetórias longas
• Subagentes precisarem compartilhar informações sem passagem direta de mensagens
• Tarefas exigirem mais contexto do que cabe na janela
• Estiver construindo agentes que aprendem e atualizam suas próprias instruções
• Estiver implementando blocos de rascunho para resultados intermediários
• Saídas de terminal ou logs precisarem ser acessíveis aos agentes

Conceitos Principais

A engenharia de contexto pode falhar de quatro maneiras previsíveis. Primeiro, quando o contexto que um agente precisa não está no contexto total disponível. Segundo, quando o contexto recuperado falha em encapsular o contexto necessário. Terceiro, quando o contexto recuperado excede em muito o contexto necessário, desperdiçando tokens e degradando o desempenho. Quarto, quando os agentes não conseguem descobrir informações de nicho enterradas em muitos arquivos.

O sistema de arquivos aborda essas falhas fornecendo uma camada persistente onde os agentes escrevem uma vez e leem seletivamente, descarregando conteúdo em massa enquanto preservam a capacidade de recuperar informações específicas através de ferramentas de busca.

Tópicos Detalhados

O Trade-off entre Contexto Estático e Dinâmico

Contexto Estático O contexto estático é sempre incluído no prompt: instruções do sistema, definições de ferramentas e regras críticas. O contexto estático consome tokens independentemente da relevância da tarefa. À medida que os agentes acumulam mais capacidades (ferramentas, habilidades, instruções), o contexto estático cresce e abre espaço para informações dinâmicas.

Descoberta Dinâmica de Contexto O contexto dinâmico é carregado sob demanda quando relevante para a tarefa atual. O agente recebe ponteiros estáticos mínimos (nomes, descrições, caminhos de arquivo) e usa ferramentas de busca para carregar o conteúdo completo quando necessário.

A descoberta dinâmica é mais eficiente em termos de tokens, pois apenas os dados necessários entram na janela de contexto. Ela também pode melhorar a qualidade da resposta, reduzindo informações potencialmente confusas ou contraditórias.

O trade-off: a descoberta dinâmica requer que o modelo identifique corretamente quando carregar contexto adicional. Isso funciona bem com modelos de ponta atuais, mas pode falhar com modelos menos capazes que não reconhecem quando precisam de mais informações.

Padrão 1: Sistema de Arquivos como Bloco de Rascunho

O Problema Chamadas de ferramentas podem retornar saídas massivas. Uma busca na web pode retornar 10 mil tokens de conteúdo bruto. Uma consulta a banco de dados pode retornar centenas de linhas. Se esse conteúdo entrar no histórico da conversa, ele permanecerá por toda a conversa, inflando os custos de tokens e potencialmente degradando a atenção a informações mais relevantes.

A Solução Escreva saídas de ferramentas grandes em arquivos em vez de retorná-las diretamente para o contexto. O agente então usa recuperação direcionada (grep, leituras linha a linha) para extrair apenas as porções relevantes.

Implementação

def handle_tool_output(output: str, threshold: int = 2000) -> str:
    if len(output) < threshold:
        return output
    
    # Write to scratch pad
    file_path = f"scratch/{tool_name}_{timestamp}.txt"
    write_file(file_path, output)
    
    # Return reference instead of content
    key_summary = extract_summary(output, max_tokens=200)
    return f"[Output written to {file_path}. Summary: {key_summary}]"

O agente pode então usar grep para buscar padrões específicos ou read_file com intervalos de linhas para recuperar seções direcionadas.

Benefícios

• Reduz o acúmulo de tokens em conversas longas
• Preserva a saída completa para referência posterior
• Permite recuperação direcionada em vez de carregar tudo

Padrão 2: Persistência de Plano

O Problema Tarefas de longo alcance exigem que os agentes façam planos e os sigam. Mas à medida que as conversas se estendem, os planos podem sair de atenção ou serem perdidos pela sumarização. O agente perde o controle do que deveria fazer.

A Solução

…