Projetar agentes ainda é difícil

• O processo de construir agentes continua complexo, e há problemas em que as abstrações de SDK frequentemente se quebram na etapa real de uso de ferramentas
• O gerenciamento de cache varia de plataforma para plataforma; o controle manual é mais previsível e eficiente, e a abordagem de pontos de cache explícitos do SDK da Anthropic é a preferida
• O loop de reforço (reinforcement loop) desempenha um papel central no rastreamento do estado das tarefas e na recuperação de falhas, e as falhas precisam ser isoladas separadamente para evitar o colapso do loop
• O gerenciamento de estado compartilhado exige uma hierarquia semelhante a um sistema de arquivos, usada como estrutura-base para troca de dados entre ferramentas de execução de código e de inferência
• A ferramenta de saída e a escolha do modelo continuam sendo difíceis, com modelos como Haiku, Sonnet e Gemini permanecendo como principais opções, o que mantém a complexidade do projeto de agentes

---

Escolha do SDK de agentes

• Ao construir agentes, é preciso escolher entre usar diretamente SDKs básicos como os da OpenAI e Anthropic, ou usar camadas de abstração de alto nível como Vercel AI SDK ou Pydantic
  • O autor menciona que no passado usou apenas a abstração de provider do Vercel AI SDK, mas que hoje não repetiria essa escolha
• Como as diferenças entre modelos são grandes, é preciso construir diretamente a própria camada de abstração de agentes, e a abstração dos SDKs existentes não é adequada
  • Existem diferenças sutis em controle de cache, requisitos de reforço e prompts de ferramentas
• O Vercel SDK apresenta problemas no processamento de ferramentas no lado do provider
  • Há casos em que a ferramenta de busca na web da Anthropic corrompe o histórico de mensagens
  • Ao usar diretamente o SDK da Anthropic, o gerenciamento de cache e as mensagens de erro ficam mais claros
• Em conclusão, neste momento a abordagem de usar diretamente os SDKs sem camada de abstração é considerada mais vantajosa

Lições sobre gerenciamento de cache

• A abordagem de cache difere entre plataformas, e a Anthropic cobra pelo cache e exige gerenciamento explícito
  • O controle manual é preferido por tornar mais previsíveis o custo e o aproveitamento do cache
• O cache explícito permite executar ramificações da conversa ou editar o contexto
  • É possível definir vários pontos de cache, como após o prompt de sistema e no começo da conversa
• Para manter o cache, o prompt de sistema e a seleção de ferramentas devem permanecer estáticos, enquanto informações dinâmicas, como horário, devem ser passadas em mensagens posteriores
• O loop de reforço é usado ativamente junto com o cache para melhorar a previsibilidade de custos e o controle

Reforço dentro do loop do agente

• Ao executar ferramentas, além de retornar apenas o resultado, é possível reinjetar no loop informações como objetivo, estado da tarefa e causa da falha
• Ferramentas de auto-reforço (self-reinforcement), como a todo write do Claude Code, ajudam no andamento do loop
• Em mudanças de ambiente ou momentos de recuperação de falhas, a estabilidade do loop é garantida ao injetar informações de mudança de estado
  • Ex.: ao tentar novamente com base em dados corrompidos, insere-se uma mensagem para voltar à etapa anterior

Isolar falhas (Isolate Failures)

• Tarefas com expectativa de falhas repetidas são executadas separadamente em um subagente (subagent), e apenas os resultados bem-sucedidos são reportados ao loop superior
  • Resumos das tentativas fracassadas podem ser usados como material de aprendizado para a próxima tarefa
• No SDK da Anthropic, é possível remover o registro de falhas com o recurso de edição de contexto (context editing)
  • Em vez de manter todas as informações de falha, preservam-se apenas as partes necessárias
  • Porém, a edição de contexto pode invalidar o cache e aumentar os custos

Subagentes e sistema de arquivos compartilhado

• A maioria dos agentes é baseada em execução e geração de código, por isso precisa de um repositório de dados comum
  • Para isso, usa-se um sistema de arquivos virtual (VFS)
• Ferramentas diversas, como geração de imagem, compressão e inferência, precisam compartilhar o mesmo caminho de arquivo
  • As ferramentas ExecuteCode e RunInference precisam poder acessar o mesmo sistema de arquivos
• Essa estrutura é essencial para eliminar gargalos na troca de dados e processar tarefas contínuas dentro do loop

Ferramenta de saída (Output Tool)

• O agente opera não como uma sessão de chat, mas como um loop interno privado de mensagens, e a comunicação com o exterior é feita por meio de uma ferramenta de saída
  • A ferramenta de saída é responsável por comunicações externas, como envio de e-mail
• É difícil controlar o tom e o estilo da ferramenta de saída, e ao usar um LLM auxiliar (Gemini 2.5 Flash) surgem queda de qualidade e latência
  • Como a ferramenta subordinada não recebe contexto suficiente, ela gera resultados imprecisos
• Se a ferramenta de saída não for chamada ao final do loop, injeta-se uma mensagem de reforço para induzir sua chamada

Escolha de modelos

• Haiku e Sonnet têm bom desempenho em chamadas de ferramentas e são usados como modelos principais do loop
• Gemini 2.5 é adequado para resumir documentos grandes, processar PDFs e extrair informações de imagens
  • O modelo Sonnet tem a desvantagem de frequentemente ser barrado por filtros de segurança
• Modelos da linha GPT não tiveram grande desempenho no loop principal
• Não dá para avaliar o custo total apenas pelo preço de tokens
  • Um modelo melhor em chamadas de ferramentas pode executar a mesma tarefa com menos tokens

Testes e avaliação (Evals)

• A automação de testes e avaliação de agentes é apontada como o problema mais difícil
  • Ao contrário de prompts, não é possível fazer uma avaliação simples a partir de um sistema externo
  • É necessário ter observabilidade (observability) ou instrumentação (instrumentation) com base em dados reais de execução
• O autor menciona que até agora não encontrou um método de avaliação satisfatório

Atualização sobre agentes de programação

• Não houve grandes mudanças relacionadas a agentes de programação
  • Recentemente, ele vem testando o agente Amp e avalia muito bem a estrutura de interação entre o subagente Oracle e o loop principal
• Amp e Claude Code passam a impressão de terem sido projetados por desenvolvedores que realmente usam suas próprias ferramentas

[GN⁺]

Opinião no Hacker News

• Há cerca de 2 anos fundei uma empresa nessa área. Hoje ela está indo bem
  O que aprendi nesses 2 anos é que muitas técnicas são otimizações temporárias para compensar as limitações atuais dos LLMs. Como a tecnologia evolui rápido, o problema de hoje pode desaparecer amanhã
  Antigamente, quando a AWS não tinha criptografia de disco, a equipe gastou 3 meses implementando isso por conta própria, mas logo depois a AWS lançou criptografia padrão com um clique. No fim, foi tempo desperdiçado
  Então a lição foi que, às vezes, não fazer nada é a melhor opção

  • Acho que esse é o insight principal. Hoje em dia, colegas da empresa fazem workshops de IA dizendo que “inventaram” novos padrões, mas a maioria fica obsoleta na semana seguinte
    A era de aprender padrões como uma linguagem comum, como antigamente, acabou, e agora a meia-vida dos padrões de IA é de cerca de uma semana. Se você perguntar a 10 especialistas o que é um “agent”, vai receber 10 respostas diferentes
  • Vendo a velocidade do avanço da IA, se esperar o suficiente, talvez no fim tudo acabe virando uso direto do OpenAI
  • Fiquei curioso se vocês têm uma estrutura lucrativa, em que a receita supera os custos operacionais. Sempre achei difícil imaginar agentes gerando lucro. Queria saber qual é o segredo
  • Saber bem quando “não fazer nada” está ligado à capacidade de avaliar se o problema que a equipe está lidando é central ou periférico
  • Concordo. Hoje, esperar também pode ser uma estratégia. Mas, se esperar demais, dá para cair na armadilha de não fazer nada até sair AGI

• Nos últimos 2 anos usei vários SDKs de agent, e ao tentar montar algo por conta própria descobri que é muito mais complexo do que parece
  O Claude Code SDK (hoje Agent SDK) é excelente, mas ainda não está totalmente desacoplado do Claude Code. Por exemplo, as skills precisam ser colocadas diretamente no sistema de arquivos
  O SDK da OpenAI permite rastreamento e avaliação automáticos no dashboard graças ao forte acoplamento com a plataforma, mas é difícil integrar modelos de terceiros
  O Google Agent Kit ainda não tem SDK para Typescript, e o Mastra é incômodo porque exige subir um servidor
  Agora estou testando o SDK da SmythOS, que dá bastante liberdade na escolha do provedor de modelo e na definição da arquitetura
  Fiquei curioso se a estrutura que vocês usam hoje é Agent → SubAgents → SubSubAgents ou algo no estilo Planner-Executor

  • A maioria dos SDKs vira um pesadelo quando você sai do básico. Então implementei tudo por conta própria usando a biblioteca cliente do OpenRouter
    O volume de código aumenta, mas o modelo mental é simples, então fica muito mais fácil de entender. Rodo um loop no estilo ReAct, repetindo reasoning e chamadas de ferramentas
    No fim, dá para implementar handoff de agent e workflows manualmente, sem SDK
  • Acho que o termo “sub-agent” quase não serve para nada. No fim, é só uma abstração de chamada de ferramenta; fora do loop principal, o que importa é apenas o contrato de entrada e saída
  • Disseram que o Claude Code só suporta modelos da Anthropic, mas com o Claude Code Router também dá para integrar outros modelos
  • Estou usando a versão em Go do Google ADK; ainda é imatura, mas estou satisfeito porque a composição de workflows e a compatibilidade entre vendors são boas
  • Também usei o Strands Agents SDK da AWS; mesmo sem Bedrock ele suporta APIs dos principais vendors e o design da API é bem flexível (sou funcionário da AWS, mas essa é uma opinião pessoal)

• Quero compartilhar alguns princípios de design de agent que aprendemos

  1. Se houver muita geração de código, Claude Code / Agent SDK é o mais eficiente
  2. Um risco maior do que dependência de vendor é criar um produto pior que o ChatGPT
  3. O Claude Code tem forte autoconsciência, então responde de forma imediata e precisa a perguntas sobre ele mesmo
  4. Se você der um computador real ao agent, ele fica muito mais poderoso. Nós usamos e2b.dev, mas o Modal também é bom
     Para referência, nossa empresa Definite é uma plataforma de dados operada por engenheiros de dados de IA, como se fosse um Heroku
  • O Claude é criativo, mas em codebases complexas ele às vezes alucina e faz reward hacking. Nesses casos, o Codex é mais estável
  • Acho problemático que muitos produtos sejam lançados com qualidade inferior à da interface web do ChatGPT
  • Em vez de necessariamente construir um sistema próprio de agent, faz mais sentido usar uma ferramenta pronta como o Claude Code e focar em gerar valor de verdade
  • Claro, deixar “tudo nas mãos das big techs” também é arriscado. O processo de construir, aprender e compartilhar por conta própria é importante. Eu mesmo estou evoluindo rápido com ADK e extensões do VS Code

• Trabalho com agents há alguns anos, e a melhor decisão que tomei foi construir meu próprio framework
  Várias camadas de abstração open source ficam impossíveis de manter conforme os SDKs mudam, e no fim desmoronam

  • Penso o mesmo. O núcleo de um agent é saída estruturada, registro de ferramentas e loop de chamadas, além de delegação entre agents
    Criei o OpusAgents, baseado em PydanticAI; é um framework open source simples e expansível, mais simples que um servidor MCP
  • Concordo como autor do texto. Organizei essas ideias neste post
  • Nós também, ao criar um chatbot de suporte ao cliente, adotamos uma arquitetura baseada em chatroom em vez da estrutura anterior. O frontend só envia mensagens, e o backend vai expandindo as funcionalidades gradualmente
  • Ainda assim, construir um framework completo por conta própria é um trabalho enorme. No longo prazo, é possível que plataformas de agent se padronizem como engines de jogo

• Hoje estamos repetindo o mesmo padrão de abstração excessiva e complexidade do começo do LangChain/RAG
  No fim, dá para pensar em agent como uma estrutura simples de REPL (Read, Eval, Print, Loop).
  Uma versão leve que implementei com esse conceito foi muito mais estável do que SDKs pesados

  • Mas, em casos de uso realmente complexos, subagents especializados e uma estrutura de compartilhamento de dados acabam sendo necessários. Um loop simples tem seus limites

• A parte mais difícil em agent é teste e avaliação (evals).
  Há entradas demais para avaliar com sistemas externos, e é preciso observar os dados durante a execução
  Ainda não tenho certeza de qual abordagem funciona melhor

  • Me preocupa que a maioria das implantações de AI agent pareça depender de intuição, sem testes formais
  • Se você olhar a documentação de avaliação do ADK, eles dizem que o resultado muda a cada execução, então é difícil definir um critério de aprovação/reprovação. No fim, avaliam com outro LLM

• Mesmo o básico no desenvolvimento de agent ainda sofre com falta de diretrizes claras
  Por exemplo, no tratamento dos tipos de entrada e saída de ferramentas de função, ao passar IDs numéricos podem ocorrer erros de serialização ou perda de precisão
  No fim, resolvi convertendo para string
  Se olhar a documentação da OpenAI (link) e a issue do Google ADK (link),
  dizem que “o resultado deve ser uma string”, mas os exemplos reais retornam dicts ou números. Esse tipo de inconsistência gera confusão

• Estou usando o produto de uma certa empresa de agentic coding (prefiro não dizer o nome)
  Estou satisfeito porque eles cuidam de tudo — releases de modelo, avaliações, gerenciamento de subagentes, cobrança — e eu posso simplesmente focar no meu trabalho

  • Provavelmente essa empresa é a Amp, da Sourcegraph. No começo era meio bruta, mas agora está bem madura

• Nos últimos dois meses implementei vários agents para tarefas diferentes. No começo usei o Claude Code, mas por causa da dependência de vendor e dos limites de uso acabei criando meu próprio runtime
  Hoje ele só suporta OpenAI, mas foi desenhado para permitir adicionar Claude ou Gemini depois
  Está em open source, então fica como referência → agent-composer

• Minha dica é simples: não use SDK; faça você mesmo um loop while e lide com JSON diretamente
  Você precisa controlar tamanho de contexto e erros por conta própria para criar um agent realmente flexível