Analisei 300 Logs de Falha de Agentes. O Problema Nunca Foi o Prompt.

Trezentos logs de falha de agentes. Passei duas semanas analisando cada um, marcando a causa raiz. O resultado me surpreendeu: problemas de prompt representaram talvez 12%. O restante? O contexto estava contaminado, estourando ou simplesmente ausente. Trocar de modelo não resolveu. Trocar de ferramenta também não. O padrão se repetiu todas as vezes.

Já mergulhei fundo em context engineering há um tempo, então quando um projeto open-source chamado Agent Skills for Context Engineering apareceu e rapidamente cruzou 10.000 estrelas no GitHub, prestei atenção. É licenciado MIT, criado por um engenheiro de contexto chamado Muratcan Koylan, e citado em um artigo de um laboratório de IA da Universidade de Pequim. Essa última parte foi o que me fez clonar de verdade.

Janelas de contexto menores são mais precisas

Eu achava que enfiar mais tokens no contexto sempre ajudaria. Estava errado. O primeiro princípio que esse conjunto de habilidades ensina é “densidade de informação, não volume de informação.”

Conforme o contexto cresce, os modelos perdem o fio do que está no meio. Esse é o efeito da curva em U: o modelo lê bem o começo e o fim, mas passa rápido por tudo que está entre eles. Testei isso preenchendo o contexto com 128K tokens e depois comprimindo as mesmas informações para 32K. A versão comprimida pontuou melhor em precisão.

O custo de processamento não escala linearmente com a contagem de tokens; ele sobe de forma exponencial. Cortar o contexto pela metade reduziu a latência de resposta em 40 a 60 por cento. Mesmo com prefix caching, entradas longas continuam caras. O resumo em uma linha: o que importa é quanto de informação útil você empacota em um determinado orçamento de tokens.

As descrições das ferramentas determinam 80% da performance do agente

Você pode escrever um prompt perfeito, mas se as descrições das suas ferramentas forem desleixadas, o agente escolhe a ferramenta errada. Esse conjunto de habilidades coloca bem: “Ferramentas são contratos lidos por LLMs, não por humanos.” Quando meu time criou um servidor MCP, reescrevemos as descrições das ferramentas seguindo esse guia. As falhas de seleção de ferramentas caíram visivelmente.

Cada descrição de ferramenta precisa especificar quando usá-la e o que ela retorna. Quando duas ferramentas têm funções sobrepostas, humanos ficam confusos, e agentes ficam ainda mais. Uma ferramenta abrangente geralmente supera várias ferramentas específicas. E mensagens de erro precisam dizer ao agente o que fazer a seguir, não apenas o que deu errado.

Sistemas multi-agente precisam de arquitetura antes dos agentes

Subir vários agentes esperando que eles colaborem automaticamente é pensamento mágico. O repositório define três padrões claramente: um orquestrador direcionando agentes subordinados, um modelo peer-to-peer onde os agentes se comunicam como iguais, e uma cadeia hierárquica de delegação.

Depois de testar os três em produção, o padrão de orquestrador foi o mais previsível e o mais fácil de debugar. Os agentes subordinados passavam resultados pelo sistema de arquivos. O modelo peer-to-peer funcionou melhor para tarefas criativas, mas arriscava loops infinitos. Para consultas estruturadas, arquivos compartilhados superaram a busca vetorial. Na prática, descobri que três agentes são o teto de estabilidade.

Busca vetorial sozinha não consegue lidar com memória

A busca vetorial encontra “O cliente X comprou o produto Y na data Z” com facilidade. Ela não consegue responder “O que mais os clientes que compraram o produto Y também compraram?” Informações relacionais se perdem nos embeddings.

O conjunto de habilidades propõe uma arquitetura de memória em quatro camadas: memória de trabalho dentro da janela de contexto, memória de curto prazo dentro de uma sessão, memória de longo prazo entre sessões, e memória permanente como arquivos. O padrão de sistema de arquivos como memória foi o mais prático que testei. Você navega pelo contexto com ls e grep em vez de consultas de embedding. Despejar resultados de ferramentas em um arquivo de rascunho economizou um espaço significativo na janela de contexto.

Avaliação é a habilidade mais subestimada de agentes

Essa foi a seção que quase pulei, e acabou sendo a mais valiosa. O repositório inclui um framework de avaliação em TypeScript que usa LLMs como juízes. Ele até gera automaticamente rubricas de pontuação.

O que me impressionou foi a mitigação de viés por posição. Ao comparar duas respostas lado a lado, o framework avalia duas vezes com a ordem invertida. Isso combate a tendência de avaliar melhor a resposta que aparece primeiro. Ele suporta tanto pontuação direta quanto comparação pareada. Montar um pipeline de avaliação significou que finalmente consegui medir se mudanças de prompt realmente melhoravam a performance, em vez de ficar chutando.

Uma coisa que o repositório não resolve: as rubricas de avaliação ainda precisam de calibração humana. As rubricas geradas automaticamente deram pontos de partida razoáveis, mas tive que ajustar os pesos de pontuação para o meu domínio específico antes que os resultados se tornassem confiáveis.

Quando seu agente erra algo, verifique o contexto antes de culpar o modelo. O repositório está aqui.