Engenharia de Contexto para Agentes de IA: Lições da Construção do Manus
sábado, julho 19
Tecnologia
2025/7/18 --Yichao 'Peak' Ji
No início do projeto Manus, minha equipe e eu enfrentamos uma decisão crucial: deveríamos treinar um modelo agêntico de ponta a ponta usando fundações de código aberto, ou construir um agente baseado nas habilidades de aprendizado em contexto dos modelos de fronteira?
Na minha primeira década em PLN, não tínhamos o luxo dessa escolha. Nos distantes dias do BERT (sim, já se passaram sete anos), os modelos precisavam ser ajustados—e avaliados—antes que pudessem ser transferidos para uma nova tarefa. Esse processo frequentemente levava semanas por iteração, mesmo que os modelos fossem minúsculos em comparação com os LLMs atuais. Para aplicações de rápida evolução, especialmente pré-PMF, esses ciclos de feedback lentos são um obstáculo decisivo. Essa foi uma lição amarga do meu último startup, onde treinei modelos do zero para extração de informações abertas e busca semântica. Então vieram o GPT-3 e o Flan-T5, e meus modelos internos tornaram-se irrelevantes da noite para o dia. Ironicamente, esses mesmos modelos marcaram o início da aprendizagem em contexto—e um caminho totalmente novo à frente.
Essa lição duramente aprendida tornou a escolha clara: Manus apostaria na engenharia de contexto. Isso nos permite implementar melhorias em horas em vez de semanas, e manteve nosso produto ortogonal aos modelos subjacentes: Se o progresso do modelo é a maré crescente, queremos que o Manus seja o barco, não o pilar preso ao fundo do mar.
Ainda assim, a engenharia de contexto revelou-se tudo menos simples. É uma ciência experimental—e reconstruímos nosso framework de agente quatro vezes, cada vez após descobrir uma maneira melhor de moldar o contexto. Nós carinhosamente nos referimos a este processo manual de busca de arquitetura, ajuste de prompts e adivinhação empírica como "**Descida Estocástica de Pós-Graduação". Não é elegante, mas funciona.
Este post compartilha os ótimos locais que alcançamos através do nosso próprio "SGD". Se você está construindo seu próprio agente de IA, espero que esses princípios ajudem você a convergir mais rapidamente.
Design em Torno do KV-Cache
Se eu tivesse que escolher apenas uma métrica, eu argumentaria que a taxa de acerto do KV-cache é a métrica mais importante para um agente de IA em estágio de produção. Ela afeta diretamente tanto a latência quanto o custo. Para entender o motivo, vamos analisar como um agente típico opera:
Após receber uma entrada do usuário, o agente passa por uma cadeia de usos de ferramentas para completar a tarefa. Em cada iteração, o modelo seleciona uma ação de um espaço de ações predefinido com base no contexto atual. Essa ação é então executada no ambiente (por exemplo, o sandbox de máquina virtual da Manus) para produzir uma observação. A ação e a observação são anexadas ao contexto, formando a entrada para a próxima iteração. Este ciclo continua até que a tarefa seja concluída.
Como você pode imaginar, o contexto cresce a cada etapa, enquanto a saída—geralmente uma chamada de função estruturada—permanece relativamente curta. Isso torna a proporção entre prefilling e decoding altamente desbalanceada em agentes em comparação com chatbots. No Manus, por exemplo, a proporção média entre tokens de entrada e saída é de aproximadamente 100:1.
Felizmente, contextos com prefixos idênticos podem aproveitar o KV-cache, que reduz drasticamente o time-to-first-token (TTFT) e o custo de inferência—seja você usando um modelo auto-hospedado ou chamando uma API de inferência. E não estamos falando de pequenas economias: com o Claude Sonnet, por exemplo, tokens de entrada em cache custam 0.30 USD/MTok, enquanto os não armazenados em cache custam 3 USD/MTok—uma diferença de 10 vezes.
1.Mantenha seu prefixo de prompt estável. Devido à natureza autorregressiva dos LLMs, mesmo uma diferença de um único token pode invalidar o cache a partir desse token. Um erro comum é incluir um timestamp—especialmente um preciso ao segundo—no início do prompt do sistema. Sim, isso permite que o modelo lhe diga a hora atual, mas também destrói sua taxa de acerto do cache.
2.Faça seu contexto apenas de anexação. Evite modificar ações ou observações anteriores. Garanta que sua serialização seja determinística. Muitas linguagens de programação e bibliotecas não garantem ordenação estável de chaves ao serializar objetos JSON, o que pode silenciosamente quebrar o cache.
3.Marque pontos de interrupção de cache explicitamente quando necessário. Alguns provedores de modelos ou frameworks de inferência não suportam cache de prefixo incremental automático e, em vez disso, exigem inserção manual de pontos de interrupção de cache no contexto. Ao atribuir esses pontos, considere a potencial expiração do cache e, no mínimo, garanta que o ponto de interrupção inclua o final do prompt do sistema.
Além disso, se você estiver hospedando modelos por conta própria usando frameworks como vLLM, certifique-se de que o cache de prefixo/prompt esteja habilitado e que você esteja usando técnicas como IDs de sessão para rotear solicitações de forma consistente entre os workers distribuídos.
Mascare, Não Remova
À medida que seu agente adquire mais capacidades, seu espaço de ação naturalmente se torna mais complexo—em termos simples, o número de ferramentas explode. A recente popularidade do MCP apenas adiciona combustível ao fogo. Se você permitir ferramentas configuráveis pelo usuário, acredite: alguém inevitavelmente conectará centenas de ferramentas misteriosas ao seu espaço de ação cuidadosamente curado. Como resultado, o modelo tem mais probabilidade de selecionar a ação errada ou seguir um caminho ineficiente. Em resumo, seu agente fortemente armado fica mais burro.
Uma reação natural é projetar um espaço de ação dinâmico—talvez carregando ferramentas sob demanda usando algo semelhante ao RAG. Nós também tentamos isso no Manus. Mas nossos experimentos sugerem uma regra clara: a menos que seja absolutamente necessário, evite adicionar ou remover ferramentas dinamicamente durante a iteração. Existem duas razões principais para isso:
1.Na maioria dos LLMs, as definições de ferramentas ficam próximas ao início do contexto após a serialização, geralmente antes ou depois do prompt do sistema. Então, qualquer alteração invalidará o KV-cache para todas as ações e observações subsequentes.
2.Quando ações e observações anteriores ainda se referem a ferramentas que não estão mais definidas no contexto atual, o modelo fica confuso. Sem decodificação restrita, isso frequentemente leva a violações de esquema ou ações alucinadas.
Para resolver isso enquanto ainda melhora a seleção de ações, o Manus usa uma máquina de estados sensível ao contexto para gerenciar a disponibilidade de ferramentas. Em vez de remover ferramentas, ele mascara os logits dos tokens durante a decodificação para impedir (ou forçar) a seleção de certas ações com base no contexto atual.
•Auto – O modelo pode escolher chamar uma função ou não. Implementado pré-preenchendo apenas o prefixo de resposta: <|im_start|>assistant
•Obrigatório – O modelo deve chamar uma função, mas a escolha não é restrita. Implementado pré-preenchendo até o token de chamada de ferramenta: <|im_start|>assistant<tool_call>
•Especificado – O modelo deve chamar uma função de um subconjunto específico. Implementado pré-preenchendo até o início do nome da função: <|im_start|>assistant<tool_call>{"name": "browser_
Usando isso, restringimos a seleção de ações mascarando diretamente os logits dos tokens. Por exemplo, quando o usuário fornece uma nova entrada, o Manus deve responder imediatamente em vez de executar uma ação. Também projetamos deliberadamente nomes de ações com prefixos consistentes—por exemplo, todas as ferramentas relacionadas ao navegador começam com browser_, e ferramentas de linha de comando com shell_. Isso nos permite impor facilmente que o agente escolha apenas de um determinado grupo de ferramentas em um estado específico sem usar processadores de logits com estado.
Esses designs ajudam a garantir que o loop do agente Manus permaneça estável—mesmo sob uma arquitetura orientada por modelo.
Use o Sistema de Arquivos como Contexto
Os LLMs de fronteira modernos agora oferecem janelas de contexto de 128 mil tokens ou mais. Mas em cenários reais de agentes, isso frequentemente não é suficiente, e às vezes até mesmo uma limitação. Existem três pontos problemáticos comuns:
1.Observações podem ser enormes, especialmente quando agentes interagem com dados não estruturados como páginas web ou PDFs. É fácil ultrapassar o limite de contexto.
2.O desempenho do modelo tende a degradar além de um certo comprimento de contexto, mesmo que a janela tecnicamente o suporte.
3.Entradas longas são caras, mesmo com cache de prefixo. Você ainda está pagando para transmitir e preencher previamente cada token.
Para lidar com isso, muitos sistemas de agentes implementam estratégias de truncamento ou compressão de contexto. Mas a compressão excessivamente agressiva inevitavelmente leva à perda de informações. O problema é fundamental: um agente, por natureza, deve prever a próxima ação com base em todo o estado anterior—e você não pode prever confiavelmente qual observação pode se tornar crítica dez passos depois. De um ponto de vista lógico, qualquer compressão irreversível traz riscos.
É por isso que tratamos o sistema de arquivos como o contexto final no Manus: ilimitado em tamanho, persistente por natureza e diretamente operável pelo próprio agente. O modelo aprende a escrever e ler arquivos sob demanda—usando o sistema de arquivos não apenas como armazenamento, mas como memória estruturada e externalizada.
Nossas estratégias de compressão são sempre projetadas para serem restauráveis. Por exemplo, o conteúdo de uma página web pode ser removido do contexto desde que a URL seja preservada, e o conteúdo de um documento pode ser omitido se seu caminho permanecer disponível na sandbox. Isso permite que o Manus reduza o tamanho do contexto sem perder informações permanentemente.
Durante o desenvolvimento deste recurso, me vi imaginando o que seria necessário para um Modelo de Espaço de Estados (SSM) funcionar efetivamente em um ambiente de agente. Diferentemente dos Transformers, os SSMs não possuem atenção completa e têm dificuldades com dependências retrógradas de longo alcance. Mas se eles pudessem dominar a memória baseada em arquivos—externalizando o estado de longo prazo em vez de mantê-lo no contexto—então sua velocidade e eficiência poderiam desbloquear uma nova classe de agentes. SSMs de agentes poderiam ser os verdadeiros sucessores das Máquinas de Turing Neurais.
Manipule a Atenção Através da Recitação
Se você já trabalhou com Manus, provavelmente notou algo curioso: ao lidar com tarefas complexas, ele tende a criar um arquivo todo.md—e atualizá-lo passo a passo conforme a tarefa progride, marcando itens concluídos.
Esse não é apenas um comportamento fofo—é um mecanismo deliberado para manipular a atenção.
Uma tarefa típica no Manus requer em média cerca de 50 chamadas de ferramentas. Isso é um longo ciclo—e como o Manus depende de LLMs para tomada de decisões, ele é vulnerável a desvios do tópico ou esquecimento de objetivos anteriores, especialmente em contextos longos ou tarefas complicadas.
Ao reescrever constantemente a lista de tarefas, o Manus está recitando seus objetivos no final do contexto. Isso coloca o plano global no alcance recente da atenção do modelo, evitando problemas de "perdido-no-meio" e reduzindo o desalinhamento de objetivos. Em efeito, está usando linguagem natural para direcionar seu próprio foco para o objetivo da tarefa—sem necessitar de mudanças arquiteturais especiais.
Mantenha as Coisas Erradas Dentro
Agentes cometem erros. Isso não é um bug—é a realidade. Modelos de linguagem alucinam, ambientes retornam erros, ferramentas externas se comportam mal, e casos extremos inesperados aparecem o tempo todo. Em tarefas de múltiplas etapas, falha não é a exceção; é parte do ciclo.
E ainda assim, um impulso comum é esconder esses erros: limpar o rastro, tentar a ação novamente, ou redefinir o estado do modelo e deixar para a mágica "temperature". Isso parece mais seguro, mais controlado. Mas tem um custo: Apagar falhas remove evidências. E sem evidências, o modelo não pode se adaptar.
Não Seja Few-Shotted
Few-shot prompting é uma técnica comum para melhorar as saídas de LLM. Mas em sistemas de agentes, isso pode ter consequências sutis.
Modelos de linguagem são excelentes imitadores; eles imitam o padrão de comportamento no contexto. Se seu contexto estiver cheio de pares de ação-observação semelhantes do passado, o modelo tenderá a seguir esse padrão, mesmo quando não for mais ideal.
Isso pode ser perigoso em tarefas que envolvem decisões ou ações repetitivas. Por exemplo, ao usar o Manus para ajudar a revisar um lote de 20 currículos, o agente frequentemente cai em um ritmo—repetindo ações similares simplesmente porque é isso que ele vê no contexto. Isso leva à deriva, supergeneralização ou às vezes alucinação.
A solução é aumentar a diversidade. O Manus introduz pequenas quantidades de variação estruturada em ações e observações—diferentes modelos de serialização, fraseado alternativo, pequenos ruídos na ordem ou formatação. Essa aleatoriedade controlada ajuda a quebrar o padrão e ajusta a atenção do modelo.
Em outras palavras, não se limite a poucos exemplos e caia numa rotina. Quanto mais uniforme for seu contexto, mais frágil seu agente se torna.
Conclusão
A engenharia de contexto ainda é uma ciência emergente—mas para sistemas de agentes, já é essencial. Os modelos podem estar ficando mais fortes, mais rápidos e mais baratos, mas nenhuma quantidade de capacidade bruta substitui a necessidade de memória, ambiente e feedback. Como você molda o contexto define, em última análise, como seu agente se comporta: quão rápido ele funciona, quão bem ele se recupera e até onde ele escala.
Na Manus, aprendemos essas lições através de reescritas repetidas, becos sem saída e testes no mundo real com milhões de usuários. Nada do que compartilhamos aqui é uma verdade universal—mas esses são os padrões que funcionaram para nós. Se eles ajudarem você a evitar até mesmo uma iteração dolorosa, então este post cumpriu seu trabalho.
O futuro dos agentes será construído um contexto de cada vez. Projete-os bem.
Menos estrutura, mais inteligência.