Frameworks para construção de agentes de IA: um guia prático

O que são agentes de IA e por que importam

Um agente de IA não é apenas um chatbot que responde perguntas. É um sistema que observa um objetivo, decide o que fazer, executa ações (via ferramentas externas) e ajusta o plano com base no resultado — em loop, até concluir a tarefa ou atingir um limite.

Essa diferença importa na prática. Um LLM isolado gera texto; um agente pode consultar APIs, ler arquivos, executar código, delegar subtarefas a outros agentes e manter contexto entre etapas. É o que separa uma demo de "pergunte ao GPT" de um assistente que realmente resolve um fluxo de trabalho.

O desafio é que esse loop — percepção, raciocínio, ação, memória — envolve muitas peças móveis. Frameworks de agentes existem para padronizar essas peças: orquestração, chamada de ferramentas, estado compartilhado, retries e observabilidade. Sem eles, você reimplementa o mesmo boilerplate a cada projeto.

Estrutura e conceitos básicos

Antes de comparar frameworks, vale alinhar o vocabulário. A maioria converge em quatro blocos:

1. Modelo (LLM) — o "cérebro" que interpreta instruções e decide próximos passos
2. Ferramentas (tools) — funções que o agente pode invocar (busca web, SQL, APIs, execução de código)
3. Memória e estado — histórico de mensagens, resultados intermediários e variáveis de sessão
4. Orquestração — o grafo ou loop que define quando chamar o modelo, quando executar uma tool e quando parar

Dois padrões aparecem com frequência:

• ReAct (Reason + Act) — o modelo alterna entre raciocinar em texto e chamar ferramentas, lendo o resultado antes de continuar
• Grafos de estado — o fluxo é modelado como nós (modelo, tool, validação) e arestas condicionais; ideal para fluxos com ramificações, human-in-the-loop ou múltiplos agentes

Entender esses blocos ajuda a escolher um framework: alguns otimizam protótipos rápidos, outros focam em controle fino de fluxo e deploy em produção.

Panorama dos principais frameworks

Não existe um "melhor" universal — cada projeto pesa simplicidade, controle e ecossistema de forma diferente. Abaixo, os mais usados em 2025–2026 e onde cada um se destaca.

LangChain e LangGraph

LangChain popularizou abstrações para chains, retrievers e tool calling. Para agentes simples, create_react_agent resolve casos comuns em poucas linhas.

LangGraph é a evolução orientada a produção: modela o agente como um grafo com estado tipado, checkpoints e suporte nativo a ciclos, subgrafos e interrupção humana. É a escolha mais comum quando o fluxo deixa de ser linear.

Quando usar: projetos Python/TypeScript que precisam de controle explícito do fluxo, persistência de estado e integração com o ecossistema LangChain (RAG, observabilidade com LangSmith).

CrewAI

Organiza agentes em equipes (crews) com papéis definidos (pesquisador, redator, revisor), tarefas encadeadas e delegação automática. A API é declarativa: você descreve quem faz o quê e o framework coordena.

Quando usar: workflows multiagente com papéis bem definidos, protótipos de automação de conteúdo ou pesquisa sem desenhar um grafo manualmente.

Microsoft AutoGen

Foca em conversas entre agentes — um agente "assistente" dialoga com um "executor" que roda código, ou vários agentes negociam uma solução. Suporta human-in-the-loop e execução em sandbox.

Quando usar: cenários colaborativos, coding agents e experimentação com múltiplos participantes (humanos ou bots).

OpenAI Agents SDK

SDK oficial da OpenAI para agentes com handoffs entre agentes especializados, guardrails e integração nativa com a Responses API. Menos acoplado a LangChain; bom se você já está no stack OpenAI.

Quando usar: aplicações que priorizam modelos OpenAI, handoffs simples entre agentes e deploy com infraestrutura gerenciada.

LlamaIndex Workflows / Agents

Nasceu em RAG e expandiu para workflows event-driven e agentes que combinam recuperação de documentos com ações. Forte quando o agente precisa consultar bases de conhecimento grandes.

Quando usar: agentes cujo core é busca semântica + ação (suporte interno, análise de contratos, Q&A corporativo).

Semantic Kernel (Microsoft)

SDK multi-linguagem (.NET, Python, Java) com plugins, planners e integração profunda ao ecossistema Microsoft (Azure OpenAI, Copilot patterns).

Quando usar: equipes enterprise em C#/.NET ou projetos híbridos cloud Azure.

Exemplo prático: agente ReAct com LangGraph

O trecho abaixo ilustra um agente mínimo: o modelo decide se responde diretamente ou chama uma ferramenta de busca. O grafo faz o loop até não haver mais tool calls.

from typing import Annotated, TypedDict
from langgraph.graph import StateGraph, END
from langgraph.prebuilt import ToolNode
from langchain_openai import ChatOpenAI
from langchain_core.messages import BaseMessage, HumanMessage
from langgraph.graph.message import add_messages

# Ferramenta de exemplo: busca simulada
def search_docs(query: str) -> str:
    """Busca em documentação interna."""
    return f"Resultado para '{query}': política de férias — 30 dias/ano."

tools = [search_docs]
llm = ChatOpenAI(model="gpt-4o").bind_tools(tools)

class AgentState(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]

def call_model(state: AgentState):
    # O LLM lê o histórico e pode devolver texto ou pedido de tool
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

def should_continue(state: AgentState):
    last = state["messages"][-1]
    # Se há tool_calls, segue para o nó de execução; senão, encerra
    if last.tool_calls:
        return "tools"
    return END

graph = StateGraph(AgentState)
graph.add_node("agent", call_model)
graph.add_node("tools", ToolNode(tools))
graph.set_entry_point("agent")
graph.add_conditional_edges("agent", should_continue, {"tools": "tools", END: END})
graph.add_edge("tools", "agent")  # volta ao modelo com o resultado da tool

app = graph.compile()

result = app.invoke({
    "messages": [HumanMessage(content="Quantos dias de férias tenho direito?")]
})
print(result["messages"][-1].content)

O ponto central não é a sintaxe, e sim o ciclo explícito: modelo → tool → modelo. Frameworks como LangGraph tornam esse ciclo visível, testável e extensível (por exemplo, adicionando um nó de validação antes de responder ao usuário).

Além do básico: como escolher e o que observar

Na hora de decidir, algumas perguntas práticas ajudam mais do que benchmarks genéricos:

• O fluxo é linear ou ramificado? Fluxos simples toleram ReAct em cadeia; fluxos com aprovação humana, paralelismo ou rollback pedem grafos (LangGraph, LlamaIndex Workflows).
• Quantos agentes? Um agente com muitas tools vs. vários agentes especializados muda a arquitetura — CrewAI e AutoGen facilitam o segundo; LangGraph modela ambos.
• Onde roda em produção? Verifique suporte a persistência de estado, timeouts, rate limits e tracing (LangSmith, OpenTelemetry, Application Insights).
• Vendor lock-in — abstrações finas sobre um provedor (OpenAI SDK) simplificam; abstrações grossas (LangChain) facilitam trocar modelos, mas adicionam camada de manutenção.

Armadilhas comuns:

• Loops infinitos — agentes que chamam tools repetidamente sem progresso; mitigue com recursion_limit, contadores de passos ou nós de parada explícitos
• Contexto estourado — históricos longos degradam qualidade e custo; use sumarização, memória externa ou janela deslizante
• Tools mal descritas — o modelo escolhe ferramentas pelo docstring; investir em nomes e descrições claras melhora mais do que trocar de framework
• Confundir demo com produção — protótipos em CrewAI ou ReAct simples; produção exige evals, logging e tratamento de falhas em cada nó

Conclusão

Frameworks para agentes de IA não substituem o desenho do problema — eles organizam raciocínio, ferramentas e estado para que você foque na lógica de negócio. LangGraph e LangChain dominam quando você precisa de controle e observabilidade; CrewAI e AutoGen aceleram equipes multiagente; OpenAI Agents SDK e Semantic Kernel fazem sentido em stacks já alinhados a esses ecossistemas.

O próximo passo natural é escolher um caso de uso real (suporte, automação de relatórios, coding assistant), implementar o loop mínimo com uma ferramenta e uma métrica de sucesso — e só então adicionar complexidade (memória, subagentes, human-in-the-loop) conforme a necessidade aparecer.

Referencias

1. LangGraph — Introduction
2. LangChain — Agents
3. CrewAI — Documentation
4. Microsoft AutoGen
5. OpenAI Agents SDK
6. LlamaIndex — Workflows
7. Semantic Kernel — Overview
8. ReAct: Synergizing Reasoning and Acting in Language Models