Como construir agentes de IA eficazes
(anthropic.com)- Na experiência prática da Anthropic, agentes de LLM bem-sucedidos muitas vezes começam com padrões simples e combináveis, em vez de frameworks complexos
- Sistemas agênticos se dividem em workflows, que seguem caminhos de código predefinidos, e agentes, nos quais o LLM decide dinamicamente procedimentos e uso de ferramentas
- Muitas aplicações com LLM são suficientemente atendidas por uma única chamada ao LLM com recuperação e exemplos in-context adicionados; a complexidade só deve aumentar quando avaliações confirmarem ganho real
- Frameworks ajudam a começar mais rápido, mas podem dificultar o debug por causa de uma camada de abstração que esconde prompts e respostas
- Agentes autônomos são fortes em problemas abertos, mas trazem aumento de custo e risco de acúmulo de erros, exigindo testes em sandbox, guardrails e design claro de ferramentas
Distinção básica dos sistemas agênticos
- Sistemas agênticos é um termo amplo, usado desde sistemas totalmente autônomos que operam de forma independente por longos períodos até implementações que seguem workflows predefinidos
- A Anthropic considera todas essas variações como sistemas agênticos, mas as divide arquiteturalmente em dois tipos
- Workflow: o LLM e as ferramentas são orquestrados seguindo caminhos de código predefinidos
- Agente: o LLM instrui e controla dinamicamente como a tarefa será executada, quais procedimentos seguir e quais ferramentas usar
Critérios para decidir quando usar agentes
- Recomenda-se que aplicações com LLM comecem pela solução mais simples possível e só elevem a complexidade quando necessário
- Como sistemas agênticos trocam latência e custo por melhor desempenho na tarefa, é preciso primeiro verificar se esse compromisso é realmente necessário
- Mesmo quando complexidade é necessária, os critérios de escolha variam
- Para tarefas bem definidas, workflows oferecem previsibilidade e consistência
- Para tarefas que exigem grande flexibilidade e tomada de decisão orientada pelo modelo, agentes são mais adequados
- Muitas aplicações já funcionam bem apenas com a otimização de uma única chamada ao LLM usando recuperação e exemplos in-context
Critérios para uso de frameworks
- São apresentados como ferramentas para implementar sistemas agênticos o Claude Agent SDK, o Strands Agents SDK by AWS, o Rivet e o Vellum
- Esses frameworks simplificam tarefas padronizadas de baixo nível, como chamadas ao LLM, definição e parsing de ferramentas e encadeamento de chamadas, acelerando o início do desenvolvimento
- Porém, a camada de abstração adicional pode esconder os prompts e respostas reais, tornando o debug mais difícil
- Isso também pode induzir complexidade desnecessária mesmo em cenários onde uma configuração simples já basta
- Em geral, é melhor que desenvolvedores comecem usando diretamente a API do LLM
- Muitos padrões podem ser implementados com poucas linhas de código
- Mesmo usando frameworks, é preciso entender como o código interno funciona
- Suposições incorretas sobre o funcionamento interno são uma causa comum de erros para clientes
- Implementações de exemplo podem ser vistas no cookbook
Bloco fundamental: LLM aumentado
- O bloco fundamental dos sistemas agênticos é um LLM aumentado com recursos como recuperação, ferramentas e memória
- Os modelos atuais conseguem usar esses recursos de forma ativa, criando consultas de busca diretamente, escolhendo a ferramenta adequada e decidindo quais informações manter
- Na implementação, é preciso focar em dois pontos
- Ajustar os recursos ao caso de uso
- Fornecer interfaces documentadas que sejam fáceis para o LLM usar
- Como uma forma de implementação, é apresentado o Model Context Protocol
- Desenvolvedores podem se integrar ao ecossistema de ferramentas de terceiros com uma client implementation simples
Padrões de workflow
-
Encadeamento de prompts
- Encadeamento de prompts divide uma tarefa em etapas sequenciais, em que cada chamada ao LLM processa a saída da chamada anterior
- Verificações programáticas podem ser inseridas em cada etapa intermediária para confirmar que o processo está no caminho correto
- É adequado quando a tarefa pode ser decomposta de forma limpa em subtarefas fixas
- O principal trade-off é aceitar maior latência em troca de maior precisão, reduzindo a dificuldade de cada chamada ao LLM
- Exemplos
- Gerar texto de marketing e depois traduzi-lo para outro idioma
- Criar o esboço de um documento, verificar se atende aos critérios e então redigir o documento com base nesse esboço
-
Roteamento
- Roteamento classifica a entrada e depois a envia para um processamento especializado
- Isso permite separar responsabilidades e criar prompts mais especializados
- Sem essa estrutura, a otimização para um tipo de entrada pode prejudicar o desempenho em outros tipos
- Funciona bem quando categorias diferentes se beneficiam de processamento separado e quando o LLM ou modelos/algoritmos tradicionais de classificação conseguem classificar com precisão
- Exemplos
- Encaminhar consultas de atendimento ao cliente, como perguntas gerais, pedidos de reembolso e suporte técnico, para processos, prompts e ferramentas diferentes
- Roteiar perguntas fáceis e gerais para modelos menores e mais econômicos, como Claude Haiku 4.5, e perguntas difíceis ou incomuns para modelos mais potentes, como Claude Sonnet 4.5
-
Paralelização
- Paralelização é quando o LLM processa uma tarefa simultaneamente e as saídas são agregadas programaticamente
- Há duas variações principais
- Seccionamento: dividir a tarefa em subtarefas independentes e executá-las em paralelo
- Votação: executar a mesma tarefa várias vezes para obter saídas diversas
- É eficaz quando subtarefas podem ser divididas para ganhar velocidade ou quando são necessárias várias perspectivas ou tentativas para maior confiabilidade
- Em tarefas complexas, atribuir cada consideração a uma chamada separada do LLM pode aumentar o foco em aspectos específicos
- Exemplos
- Guardrails em que uma instância do modelo processa a consulta do usuário e outra verifica conteúdo ou solicitações inadequadas
- Em avaliação de desempenho de LLMs, cada chamada avalia um aspecto diferente da performance do modelo
- Vários prompts revisando vulnerabilidades de código e sinalizando quando encontram problemas
- Em avaliação de conteúdo impróprio, uso de vários prompts e um limiar de votação para equilibrar falsos positivos e falsos negativos
-
Orquestrador-trabalhador
- Orquestrador-trabalhador é um padrão em que um LLM central decompõe a tarefa dinamicamente, delega a LLMs trabalhadores e depois consolida os resultados
- É adequado para tarefas complexas em que não é possível prever antecipadamente quais subtarefas serão necessárias
- Pode parecer semelhante à paralelização, mas a diferença central é a flexibilidade
- Na paralelização, as subtarefas são predefinidas
- No padrão orquestrador-trabalhador, o orquestrador decide as subtarefas de acordo com a entrada
- Exemplos
- Produtos de coding que realizam alterações complexas em vários arquivos a cada execução
- Tarefas de busca que coletam e analisam informações potencialmente relevantes de várias fontes
-
Avaliador-otimizador
- Avaliador-otimizador é uma estrutura em loop em que uma chamada ao LLM gera uma resposta e outra chamada ao LLM fornece avaliação e feedback
- É especialmente eficaz quando há critérios claros de avaliação e quando a melhoria iterativa traz valor mensurável
- Dois sinais indicam boa adequação
- Quando humanos conseguem expressar feedback com clareza, a resposta do LLM realmente melhora
- O próprio LLM consegue fornecer esse tipo de feedback
- Isso é semelhante ao processo iterativo de escrita pelo qual autores humanos passam ao refinar um texto
- Exemplos
- Tradução literária, em que um LLM avaliador critica nuances que o LLM tradutor pode ter deixado passar inicialmente
- Tarefas complexas de busca, em que o avaliador decide se mais pesquisa é necessária
Agentes autônomos
- Agentes começaram a ser usados em produção à medida que os LLMs passaram a ter capacidade de entender entradas complexas, raciocinar e planejar, usar ferramentas de forma confiável e se recuperar de erros
- A tarefa começa com instruções ou conversa com uma pessoa
- Quando a tarefa fica clara, o agente cria um plano e opera de forma independente
- Se precisar de mais informações ou julgamento, pode voltar à pessoa
- Durante a execução, é importante obter sinais reais de verificação do ambiente em cada etapa
- Ex.: resultados de chamadas de ferramentas, resultados de execução de código
- Isso permite avaliar o progresso
- O agente pode parar em checkpoints ou bloqueios para obter feedback humano
- Muitas vezes a tarefa termina quando concluída, mas também é comum definir condições de parada, como um número máximo de iterações, para manter o controle
- A implementação em si costuma ser simples
- Em geral, um agente é um LLM usando ferramentas dentro de um loop com base no feedback do ambiente
- Por isso, o conjunto de ferramentas e sua documentação devem ser projetados de forma clara e cuidadosa
- Condições de uso
- Problemas abertos em que o número de etapas necessárias é difícil ou impossível de prever
- Tarefas em que não dá para codificar rigidamente um caminho fixo
- Situações em que o LLM precisa operar por vários turnos e é necessário um certo nível de confiança na tomada de decisão
- Restrições
- A autonomia vem com custo maior e possibilidade de acúmulo de erros
- Recomenda-se ampla testagem em ambiente sandbox e guardrails adequados
- Exemplos
- Agentes de coding que resolvem SWE-bench tasks que exigem edição de múltiplos arquivos
- A implementação de referência de “computer use”, na qual Claude usa um computador para executar tarefas
Combinação e customização de padrões
- Os blocos apresentados não são uma receita fixa, mas padrões comuns que desenvolvedores podem adaptar e combinar conforme o caso de uso
- Como em toda a área de LLMs, a chave do sucesso está em medir o desempenho e melhorar iterativamente a implementação
- A complexidade só deve ser adicionada quando os resultados realmente melhorarem
Princípios de implementação
- O sucesso na área de LLMs não está em construir o sistema mais sofisticado, mas sim o sistema certo para a necessidade
- A sequência recomendada é a seguinte
- Começar com prompts simples
- Otimizar os prompts com avaliação abrangente
- Adicionar sistemas agênticos de múltiplas etapas apenas quando a solução simples não for suficiente
- Ao implementar agentes, três princípios são importantes
- Manter a simplicidade do design
- Priorizar a transparência, mostrando explicitamente as etapas de planejamento do agente
- Projetar cuidadosamente a agent-computer interface, ou ACI, com documentação e testes rigorosos das ferramentas
- Frameworks ajudam a começar rápido, mas, ao migrar para produção, também pode ser necessário reduzir camadas de abstração e construir com componentes básicos
Áreas de aplicação prática
-
Suporte ao cliente
- O suporte ao cliente combina a interface familiar de chatbot com expansão de capacidades por meio da integração de ferramentas
- Há razões para que isso se encaixe naturalmente em agentes mais abertos
- Interações de suporte seguem um fluxo conversacional, mas exigem acesso a informações externas e execução de ações
- Ferramentas podem ser integradas para buscar dados do cliente, histórico de pedidos e documentos da base de conhecimento
- Tarefas como processar reembolsos ou atualizar tickets podem ser tratadas programaticamente
- O sucesso pode ser medido claramente pela resolução definida pelo usuário
- Várias empresas mostraram a viabilidade dessa abordagem com modelos de precificação por uso que cobram apenas por resoluções bem-sucedidas
-
Agentes de coding
- A área de desenvolvimento de software mostrou grande potencial à medida que as capacidades dos LLMs evoluíram de conclusão de código para resolução autônoma de problemas
- Há motivos para os agentes serem eficazes
- Soluções de código podem ser validadas com testes automatizados
- Agentes podem usar os resultados dos testes como feedback para melhorar iterativamente a solução
- O espaço do problema é bem definido e estruturado
- A qualidade da saída pode ser medida objetivamente
- Na implementação da Anthropic, agentes conseguem resolver problemas reais do GitHub no benchmark SWE-bench Verified apenas com a descrição do pull request
- Mesmo que testes automatizados ajudem a validar funcionalidades, a revisão humana continua importante para verificar se a solução atende aos requisitos mais amplos do sistema
Engenharia de prompt para ferramentas
- Em qualquer sistema agêntico, ferramentas têm grande chance de ser um componente essencial
- Tools permitem que Claude interaja com serviços externos e APIs
- A estrutura e as definições exatas são especificadas na API
- Quando Claude planeja uma chamada de ferramenta, a resposta da API inclui um tool use block
- Definições e especificações de ferramentas merecem tanta atenção de prompt engineering quanto o prompt completo
-
Escolha do formato da ferramenta
- A mesma tarefa pode ser especificada de várias formas
- Edição de arquivos pode ser expressa como diff ou como reescrita completa do arquivo
- Saída estruturada pode ser retornada como código dentro de Markdown ou como código dentro de JSON
- Do ponto de vista da engenharia de software, essas diferenças de formato podem ser convertidas sem perda, mas para o LLM alguns formatos são muito mais difíceis de usar
- Escrever diff exige saber quantas linhas mudam nos cabeçalhos dos chunks antes de escrever o novo código
- Escrever código dentro de JSON exige escapes adicionais de quebras de linha e aspas
- Ao escolher o formato da ferramenta, é importante evitar que o modelo fique preso a um peso desnecessário de formatação
- Fornecer tokens para pensar suficientes antes de entrar em um formato sem saída
- Manter o formato próximo daquele que o modelo viu naturalmente em textos da internet
- Eliminar overhead de formatação como contar exatamente o número de linhas em milhares de linhas de código ou escapar strings de código
- A mesma tarefa pode ser especificada de várias formas
-
Projeto de ACI
- Deve-se investir no design da agent-computer interface (ACI) tanto quanto se investe em HCI
- Boas definições de ferramentas geralmente incluem exemplos de uso, edge cases, requisitos de formato de entrada e fronteiras claras em relação a outras ferramentas
- Nomes de parâmetros e descrições devem ser ajustados para facilitar o entendimento do modelo
- É parecido com escrever um ótimo docstring para um desenvolvedor júnior da equipe
- Isso é especialmente importante quando há muitas ferramentas semelhantes
- O uso de ferramentas pelo modelo deve ser testado
- Ao construir um agente para SWE-bench, foi gasto mais tempo otimizando ferramentas do que o prompt inteiro
- Havia um problema em que o agente errava ao usar caminhos de arquivo relativos em uma ferramenta depois de sair do diretório raiz
- Quando a ferramenta passou a exigir sempre caminhos absolutos de arquivo, o modelo conseguiu usar esse padrão sem erros
1 comentários
Opiniões no Hacker News
Acho que este ainda é um dos bons textos sobre o tema. Gostei especialmente do fato de ele definir claramente, logo no início, em que sentido usa agentes de IA
Aqui, eles são definidos como “sistemas em que o LLM direciona dinamicamente seu próprio processo de processamento e uso de ferramentas, mantendo o controle sobre como a tarefa será realizada”
Também gostei da forma como diferencia “agentes” de “workflows” e explica vários padrões úteis de workflow
Quando o texto saiu, deixei algumas notas sobre ele: https://simonwillison.net/2024/Dec/20/building-effective-age...
Um texto mais recente da Anthropic é https://www.anthropic.com/engineering/built-multi-agent-rese... — “How we built our multi-agent research system”, que também é muito interessante, e organizei algumas notas sobre ele: https://simonwillison.net/2025/Jun/14/multi-agent-research-s...
Para fins de aprendizado, parece uma boa ideia, mas a primeira vantagem de um bom framework é permitir testar facilmente LLMs de diferentes provedores
Parece uma tentativa de redefinir workflow para criar uma distinção, mas a maioria dos agentes nada mais é do que workflows iterativos que chamam algo dinamicamente conforme a resposta do LLM. Motores de workflow modernos são muito dinâmicos
Considero o conselho de que “eles simplificam tarefas padrão de baixo nível, como chamadas a LLMs, definição e parsing de ferramentas e encadeamento de chamadas, facilitando o início, mas muitas vezes criam uma camada extra de abstração que oculta prompts e respostas básicos, dificultando a depuração. Eles também induzem a adicionar complexidade quando uma composição mais simples seria suficiente. Recomenda-se que desenvolvedores comecem usando diretamente a API do LLM” disparado o melhor do texto inteiro
Não faz sentido usar um framework enorme para algo que, em essência, é enviar um array de strings para um serviço web
Também removemos LangChain e LangGraph de um projeto da empresa; na prática, eles não agregavam valor e só aumentavam a complexidade. Era preciso lidar com o boilerplate do framework, então acabávamos escrevendo mais código do que sem usá-lo
Você pode executar todas as etapas de geração de imagem com Stable Diffusion ou escrever código de shader diretamente, mas, se houver mais de um fluxo ou tarefa e você estiver experimentando, usar comfy-UI ou um grafo de shaders deixa tudo muito mais organizado
Já se passou meio ano, o que parece bastante tempo na área de IA. Alguns meses atrás li este texto várias vezes, mas agora parece claro que o desenvolvimento de agentes chegou a um gargalo
Até o Gemini mais recente parece ter regredido
A orquestração multiagente é difícil de controlar e, quanto melhor fica o desempenho dos modelos, menor é a necessidade de multiagentes. Por outro lado, quanto pior o desempenho dos modelos, mais uma IA de escopo estreito faz sentido como negócio
Há exemplos de agentes que economizam dinheiro para empresas em ambientes reais de produção e fazem algo de valor de verdade? Refiro-me a casos que não sejam como escrever texto para preencher o espaço vazio de um pacote de batata chips
https://www.gbif.org/news/6aw2VFiEHYlqb48w86uKSf/chatipt-sys...
Ainda está em beta
Segundo o comunicado à imprensa, o chatbot de Rukaya Johaadien oferece suporte interativo a estudantes e pesquisadores que têm dados de biodiversidade, mas para quem a publicação de dados é algo novo ou raro. Ele ajuda a limpar e padronizar planilhas, criar metadados básicos e publicar datasets bem estruturados no GBIF.org como Darwin Core Archive
Até agora, era difícil publicar em larga escala dados de alta qualidade vindos de pesquisas de doutorado e mestrado ou de pequenos estudos de biodiversidade. Isso porque a padronização de dados normalmente exigia conhecimento de linguagens de programação, técnicas de gestão de dados e softwares especializados
O processo de acesso ao Integrated Publishing Toolkit(IPT), o principal app de compartilhamento de dados da rede GBIF, também é complicado para iniciantes. Como o tempo e os recursos dos responsáveis pelos nós são limitados, e usuários ocasionais tendem a esquecer todos os anos os procedimentos e detalhes corretos, diz-se que só treinamento não basta para superar barreiras logísticas e linguísticas
“A padronização de dados é difícil, e biólogos não se tornam biólogos porque gostam de programar ou de Excel, então muitos dados potencialmente valiosos acabam sendo descartados. Ao ver que modelos de linguagem grandes ficaram muito bons em geração de código e tarefas com dados, criei uma ferramenta que guia usuários não técnicos por perguntas comuns, processa dados bagunçados tanto quanto possível e os publica no GBIF de forma rápida e automática”, explicou
Para cada alerta ou ticket que chega, um agente faz uma investigação prévia em APIs, bancos de dados etc. relevantes para identificar falsos positivos e fornecer mais contexto sobre problemas reais. Isso reduz o tempo humano e aumenta a velocidade de processamento
Eles também usam o mesmo raciocínio agentic em tarefas de exploração; indo além de um simples text-to-SQL, o LLM investiga Splunk, Databricks etc. por 2 a 10 minutos no lugar do usuário
Internamente, têm ferramentas como uma camada semântica sobre bancos de dados e analisadores de logs, texto e dataframes em grande escala
Usei um workflow n8n que eu mesmo criei com uma configuração quase igual à descrita no texto. Custou 3 dólares e pelo menos 3 minutos para receber resposta a uma pergunta simples
Por enquanto, vou continuar usando busca comum
O texto lembra bem que se deve começar pela coisa mais simples que funcione e só adicionar complexidade quando ela for realmente necessária
Algumas chamadas LLM bem definidas e uma lógica leve de cola geralmente resultam em sistemas mais estáveis, mais fáceis de depurar e muito mais baratos de executar. Agentes sofisticados e cheios de recursos muitas vezes criam mais problemas do que resolvem
Falando como alguém que trabalha em uma empresa com agentes reais em produção, não workflows, discordo totalmente da primeira frase daqui, que diz para “usar um framework de agentes como LangGraph”
Nós fizemos exatamente isso e tivemos que jogar tudo fora depois de um mês; depois reconstruímos do zero e agora temos um sistema que escala bastante bem
Para ser justo, pode haver espaço para usar frameworks de agentes. Mas a área de agentes ainda é inicial demais para que exista um framework suficientemente bom
Até penso um pouco no sentido oposto: como a área de agentes se move rápido demais, acho que talvez um framework suficientemente bom nunca venha a existir
Frameworks facilitam o início, mas uma camada adicional de abstração pode esconder prompts e respostas, dificultando a depuração, e pode levar a adicionar complexidade mesmo quando uma configuração mais simples bastaria. Por isso, como muitos padrões podem ser implementados com poucas linhas de código, o texto recomenda começar usando diretamente a API de LLM
Vi muitos comentários dizendo que equipes pragmáticas em geral abandonaram LangChain, LangGraph, Haystack, Crew e afins e foram para código interno mais simples, mas ainda não tenho uma boa noção de como partes como chamadas de ferramentas são de fato implementadas na prática
Se você tiver links ou documentos que usou como base para o trabalho, poderia compartilhar?
É um texto de dezembro de 2024, mas, estranhamente, parece de muito tempo atrás
Foi o texto que me fez voltar a ver a Anthropic como uma “parceira pragmática” no desenvolvimento de ferramentas de IA
https://news.ycombinator.com/item?id=44260988
Parece que o hype dos agentes já deu uma esfriada
A frase “use padrões simples e combináveis” é estranhamente reconfortante
É bom ver que o ditado “faça uma coisa bem” continua válido mesmo depois de décadas. Composabilidade é o melhor