Guia de campo dos frameworks de agentes em Python de código aberto

Por que o framework importa mais que o modelo

É fácil ficar obcecado com qual modelo usar. Mas o modelo é cada vez mais uma commodity. Os laboratórios de fronteira lançam capacidades comparáveis com poucas semanas de diferença, e trocar um pelo outro costuma ser uma mudança de uma única linha. O que realmente determina se o seu agente funciona em produção é o framework: o código ao redor do modelo que cuida do planejamento, das chamadas de ferramentas, da memória, das novas tentativas e do fluxo de controle.

O framework é onde mora a sua verdadeira engenharia. Ele decide como uma tarefa é decomposta, o que o agente tem permissão de fazer, como o estado sobrevive entre os passos e o que acontece quando algo falha. Dois times usando exatamente o mesmo modelo podem lançar produtos muito diferentes dependendo do framework que constroem.

A boa notícia é que você não precisa mais escrever um do zero. Um conjunto saudável de frameworks de Python de código aberto cobre hoje tudo, desde um runtime básico até um agente totalmente montado. Cada um faz apostas diferentes, e este guia percorre os principais sem coroar um vencedor.

O que esses frameworks têm em comum

Todas as opções abaixo compartilham dois traços: são escritas em Python e são de código aberto.

Python importa porque é onde o ecossistema vive. Os SDKs dos modelos, as ferramentas de avaliação, os bancos vetoriais, as bibliotecas de dados e os fluxos de trabalho em notebooks que o seu time já usa são Python primeiro. Um framework na mesma linguagem se conecta direto a eles.

Código aberto importa porque um framework de agentes é infraestrutura que você vai precisar depurar. Quando um agente entra em um laço infinito, escolhe a ferramenta errada ou perde contexto em uma passagem, poder abrir o código-fonte e rastrear o fluxo de controle é a diferença entre uma correção e um chamado de suporte. Você também pode fazer um fork quando uma abstração vaza.

A contrapartida honesta: com um framework de código aberto você assume mais manutenção, mais atualizações e mais trabalho operacional do que teria com uma plataforma totalmente gerenciada. Isso é um custo real. Se vale a pena pagar depende de quanto você espera personalizar e de quanto valoriza enxergar por dentro. Este guia não assume uma resposta. Ele mapeia as opções para você decidir.

A lista curta

Um punhado de frameworks de Python de código aberto se tornou as opções sérias. Eles diferem menos em capacidade bruta do que em quanto decidem por você. Alguns entregam um runtime de baixo nível e deixam você montar tudo. Outros trazem um agente com opinião pronto para usar. É mais ou menos assim que eles se posicionam:

deepagents (LangChain)

deepagents empacota o padrão "deep agent": uma ferramenta de planejamento, subagentes com contexto isolado e um sistema de arquivos virtual como memória de trabalho, tudo sobre o LangGraph. É quase um agente pronto para uso capaz de executar tarefas longas de vários passos sem que você mesmo monte o laço. Criar um é propositalmente simples:

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Obtem o clima de uma cidade."""
    return f"Sempre faz sol em {city}!"

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[get_weather],
    system_prompt="Voce e um assistente prestativo.",
)

agent.invoke({"messages": [{"role": "user", "content": "Como esta o tempo em SF?"}]})

Forte em pesquisa, relatórios com várias fontes e qualquer coisa que se beneficie de um planejador e de subtarefas delegadas. Cuidado com uma API jovem e ainda em evolução, então fixe a sua versão, e um modelo com opinião própria contra o qual você pode acabar brigando em fluxos incomuns.

LangGraph

LangGraph é o runtime de grafos de baixo nível sobre o qual o deepagents é construído. Você define os agentes como máquinas de estado explícitas: nós, arestas e um objeto de estado tipado que flui entre eles, com execução durável e pontos de checagem com humano no laço. Forte em determinismo e controle total do fluxo. Cuidado com o código repetitivo: para um agente simples você monta mais por conta própria do que as opções de mais alto nível pedem.

Claude Agent SDK (Anthropic)

Claude Agent SDK é o framework de código aberto por trás do Claude Code, disponível em Python e TypeScript. Ele conduz um agente Claude por um laço testado em produção com ferramentas embutidas (edição de arquivos, shell, busca), suporte a MCP, subagentes, modos de permissão e limites de orçamento por execução. O ponto de entrada em Python é assíncrono:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        system_prompt="Voce e um assistente de pesquisa.",
        max_turns=4,
        max_budget_usd=0.50,
    )
    async for message in query(prompt="Resuma o estado dos frameworks de agentes.", options=options):
        print(message)

asyncio.run(main())

Forte em um laço de agente testado em batalha com permissões de ferramentas reais e controles de custo nativos como max_budget_usd. Cuidado com a sua orientação para os modelos Claude e o modelo de ferramentas MCP, o que o torna a opção com mais opinião sobre o runtime que espera.

AutoGen (Microsoft)

AutoGen modela um problema como uma conversa entre agentes que trocam mensagens entre si até o trabalho ficar pronto. É forte em colaboração multiagente e em agentes que escrevem e executam código enquanto criticam a saída uns dos outros, e é mantido pela Microsoft Research. Cuidado com o modelo conversacional, que pode ser mais difícil de tornar determinístico, e uma API que mudou bastante na reescrita da v0.4.

CrewAI

CrewAI modela um problema como uma equipe (crew) de agentes com papéis: um pesquisador, um redator, um editor, cada um com um objetivo e uma história, colaborando em tarefas. Forte em prototipagem rápida; se lê quase como descrever um time. Cuidado com a metáfora de papéis obscurecendo o fluxo de controle quando você precisa de uma orquestração precisa e de grão fino.

Agno

Agno é um framework completo para construir agentes com memória, conhecimento e ferramentas embutidos, com forte foco em velocidade e baixo custo em tempo de execução. Ele escala de um único agente até equipes de agentes e trata a entrada multimodal como prioridade de primeira classe. Forte em agentes com tudo incluso, com memória e recuperação prontas para uso. Cuidado com uma superfície maior e mais convenções a aprender do que as opções minimalistas.

PydanticAI

PydanticAI traz segurança de tipos para os agentes. Ferramentas e saídas são definidas como modelos do Pydantic, então você ganha E/S validada e estruturada e autocompletar no editor, com uma ergonomia que lembra o FastAPI. Forte em agentes únicos tipados, estruturados e confiáveis. Cuidado com a orquestração multiagente, que não é o seu foco principal.

smolagents (Hugging Face)

smolagents é um framework minimalista construído em torno de agentes que agem por código, escrevendo e executando Python para cumprir tarefas. Forte em se manter pequeno e não atrapalhar. Cuidado com a necessidade de isolar a execução de código em um ambiente seguro, e com ter menos elementos embutidos do que os frameworks mais pesados.

Em um relance

Como escolher

Os padrões não são mutuamente exclusivos, e as bibliotecas também não. deepagents e o Claude Agent SDK rodam um laço de agente sob o qual você pode descer quando precisar. Um guia aproximado:

• Quer um deep agent que planeja e delega com configuração mínima? Comece com deepagents.
• Quer um laço testado em produção com ferramentas, permissões e limites de orçamento? Use o Claude Agent SDK.
• Quer orquestração explícita e durável que você controla por completo? Use LangGraph.
• Quer agentes que colaboram conversando? Recorra ao AutoGen.
• Quer uma equipe multiagente definida por papéis, rápido? Experimente CrewAI.
• Quer agentes com tudo incluso, com memória e velocidade? Use Agno.
• Quer confiabilidade tipada e estruturada de um único agente? Use PydanticAI.
• Quer o menor agente que age por código possível? Olhe o smolagents.

Algumas regras gerais que valem para todos eles:

• Comece com o menor framework que serve. Recorra à camada inferior só quando a superior atrapalhar.
• Prefira o framework cujos primitivos coincidem com o formato do seu problema. Uma tarefa de pesquisa quer um planejador; uma tarefa de extração estruturada quer tipos; uma decisão em disputa quer uma conversa.
• Valorize a saída de emergência. A vantagem compartilhada de todas as opções aqui é que você pode lê-las e mudá-las. Aproveite isso.

Onde o AIFlow se encaixa

Esses frameworks dão a você o agente. O que eles não dão, por design, é a camada que uma empresa precisa ao redor de cada agente: login único, acesso baseado em papéis, trilhas de auditoria, residência de dados, guardrails de modelo e controles de custo sobre a inferência. Se você acopla isso a cada projeto individualmente, cada novo agente vira a sua própria revisão de conformidade e o seu próprio exercício de orçamento.

O AIFlow é o perímetro de orquestração e governança dentro do qual esses frameworks rodam. Um agente de pesquisa em deepagents, um fluxo de LangGraph feito à mão, um laço do Claude Agent SDK e um crew de CrewAI podem todos rodar sobre o AIFlow sob os mesmos controles, com a mesma observabilidade, atrás da mesma fronteira de segurança. O gasto é rastreado e limitado por agente, por time e por modelo a partir de um só lugar, de modo que um laço descontrolado vira um alerta de orçamento em vez de uma fatura surpresa. Você mantém o framework de código aberto que se encaixa em cada problema, e para de reconstruir a governança e o controle de custos para cada um.

Conclusão

Não existe um único melhor framework. deepagents e o Claude Agent SDK entregam a você um laço de agente funcionando; LangGraph entrega o runtime para construir o seu; AutoGen e CrewAI organizam agentes em conversas e equipes; Agno empacota memória e velocidade; PydanticAI mantém tudo tipado; smolagents se mantém minimalista. A escolha certa depende do formato do seu problema: planejamento, papéis, diálogo, tipos ou controle puro. Escolha o framework cujos primitivos coincidem com o seu problema, e cujo código-fonte você ficaria à vontade para ler às 2 da manhã, porque cedo ou tarde você vai ler.