⚡ Frameworks e Ecossistema

Um grafo de estado é uma representação onde cada nó é uma função Python que recebe um estado compartilhado e retorna uma versão atualizada desse estado. O fluxo de execução segue as arestas (edges) que conectam os nós.

Sem entender o modelo mental do grafo, você não consegue projetar fluxos complexos com branches e loops. É o alicerce de tudo no LangGraph.

Estado como TypedDict · Nós como funções puras · Edges como transições · START e END como pontos de entrada/saída · Imutabilidade do estado

Nós (nodes) são funções Python que processam o estado. Edges são conexões entre nós: fixas (sempre seguem o mesmo caminho) ou condicionais (escolhem o próximo nó baseado no estado atual).

A combinação de edges fixas e condicionais é o que permite criar fluxos com decisões, branches e retornos — impossível de fazer com chains lineares simples.

add_node() · add_edge() fixo · add_conditional_edges() com função roteadora · Retorno de string para escolher próximo nó · Múltiplos destinos possíveis

Construção prática de um StateGraph: definindo o TypedDict do estado, criando nós como funções, conectando com edges e compilando o grafo para execução com graph.compile().

Teoria sem prática não funciona. Você precisa saber a sintaxe exata, a ordem de construção e como debugar erros comuns de compilação do grafo.

TypedDict como schema do estado · StateGraph(State) · graph.set_entry_point() · graph.compile() · graph.invoke() vs graph.stream()

Diferente de chains lineares, LangGraph permite que o grafo retorne para um nó anterior com base em uma condição — criando loops de retry, reflexão ou iteração até que um critério seja atendido.

Loops controlados são essenciais para agentes que precisam tentar novamente após erro, revisar sua própria saída ou aguardar aprovação humana antes de continuar.

Edge condicional apontando para nó anterior · Contador de iterações no estado · Critério de saída do loop · Prevenção de loops infinitos · Human-in-the-loop com interrupt()

O sistema de checkpoints salva o estado do grafo após cada nó. Com MemorySaver (em memória) ou PostgresSaver (persistente), o grafo pode ser retomado do ponto exato onde parou.

Sem checkpoints, uma falha no meio de um fluxo longo reinicia tudo do zero. Com checkpoints, você tem resiliência, auditoria e capacidade de pausar/retomar workflows.

MemorySaver para desenvolvimento · PostgresSaver para produção · thread_id como identificador de sessão · graph.get_state() para inspecionar · Histórico completo de execução

graph.stream() emite eventos a cada nó executado, permitindo que a UI mostre progresso em tempo real — qual nó está rodando, qual é o estado atual, quais tokens o LLM gerou.

Agentes lentos sem feedback causam abandono do usuário. Streaming transforma a experiência: o usuário vê o sistema "pensando" ao invés de esperar uma tela em branco.

graph.stream() com for loop · stream_mode="values" vs "updates" vs "debug" · Streaming de tokens do LLM · Integração com FastAPI SSE · Filtrando eventos por nó

Uma Crew é um time de agentes de IA com uma missão coletiva. Cada agente tem papel definido, e eles colaboram para completar tasks que sozinhos não conseguiriam executar.

Pensar em times de agentes ao invés de agentes isolados resolve problemas complexos com mais naturalidade — igual como times humanos se organizam.

Crew como abstração de equipe · Agents como membros · Tasks como assignments · Process como modo de trabalho · Missão coletiva compartilhada

Cada Agent no CrewAI é definido por três atributos: role (seu título/função), goal (o que quer alcançar) e backstory (seu contexto de vida e especialidade). Esses prompts de persona guiam o comportamento do LLM.

Personas bem definidas geram outputs mais consistentes e especializados. Um "Senior Data Analyst" pensa diferente de um "Content Writer" — mesmo usando o mesmo LLM por baixo.

Agent(role=..., goal=..., backstory=...) · tools=[...] para equipar com ferramentas · llm= para definir modelo · verbose=True para debug · allow_delegation= para permitir delegar

Task é uma unidade de trabalho com description (o que fazer), expected_output (qual o resultado esperado) e agent (quem executa). Flows definem como tasks se encadeiam e compartilham contexto.

Tasks bem definidas com expected_output claro são o segredo de outputs consistentes. Sem isso, o agente "improvisa" o formato da resposta em cada execução.

Task(description=..., expected_output=..., agent=...) · context=[task_anterior] para passar resultado · output_pydantic= para estruturar saída · async_execution= para paralelismo

No Process.hierarchical, um Manager Agent coordena os demais — decide quem executa cada task, revisa outputs e pode redirecionar trabalho. É um agente que gerencia outros agentes.

Para workflows complexos com decisões dinâmicas sobre quem faz o quê, a hierarquia elimina a rigidez da sequência fixa e permite adaptação em tempo de execução.

manager_agent= na Crew · Process.hierarchical · Delegação automática de tasks · Manager como coordenador LLM-powered · Aprovação de outputs antes de continuar

Process.sequential executa tasks uma após a outra (o output de uma vira input da próxima). Com async_execution=True em tasks independentes, elas rodam em paralelo — reduzindo latência total.

Tarefas que não dependem umas das outras desperdiçam tempo se forem sequenciais. Paralelismo pode reduzir latência de minutos para segundos em workflows de análise.

Process.sequential (padrão) · async_execution=True por task · Dependências implícitas via context= · Tasks paralelas sem dependência · Agregação de resultados no final

Projeto completo com 3 agentes: Pesquisador (coleta dados de mercado com ferramentas web), Analista (interpreta tendências e métricas) e Redator (transforma análise em relatório executivo).

Ver o padrão completo funcionando é a melhor forma de entender como os componentes se encaixam — do Agent até o output final estruturado em Pydantic.

Três agents com ferramentas distintas · Três tasks em sequência · Contexto passado automaticamente · Output final em Pydantic · crew.kickoff() como ponto de entrada

AutoGen modela interação entre agentes como uma conversa multi-turno. Ao invés de um grafo de estado, o fluxo emerge da troca de mensagens — cada agente responde ao que o outro disse.

Problemas que se beneficiam de perspectivas múltiplas (revisão de código, pesquisa, debate) se encaixam naturalmente no modelo conversacional do AutoGen.

Conversa como fluxo de controle · Mensagens como estado · Agentes como participantes · Critério de terminação · Historia de conversa como contexto acumulado

AssistantAgent usa um LLM para responder e gerar código. UserProxyAgent pode executar código localmente e simular o usuário humano. Juntos, formam o par fundamental do AutoGen.

Esse par permite o loop de geração e execução de código automatizado — o agente escreve Python, o proxy executa, o erro vira feedback, o agente corrige. Tudo sem intervenção humana.

AssistantAgent(name=..., llm_config=...) · UserProxyAgent(code_execution_config=...) · human_input_mode="NEVER" para full autonomy · is_termination_msg para critério de parada

GroupChat é uma abstração onde N agentes participam de uma conversa mediada por um GroupChatManager, que decide quem fala a seguir com base em regras ou outro LLM.

Quando você precisa de mais de dois agentes colaborando (ex: pesquisador + analista + crítico), o GroupChat é o mecanismo nativo do AutoGen para coordenar esse tipo de interação.

GroupChat(agents=[...], messages=[], max_round=...) · GroupChatManager como moderador · speaker_selection_method="auto" vs "round_robin" · Histórico compartilhado entre agentes

Padrão onde um agente gera uma resposta e um segundo agente (o crítico) avalia, aponta problemas e sugere melhorias. O primeiro revisa e o ciclo continua até qualidade suficiente.

Reflexão melhora dramaticamente a qualidade do output sem precisar de humano na alça de feedback. É o equivalente de ter um revisor automático para cada resposta.

Agente Escritor + Agente Crítico · Critério de aprovação claro · Máximo de iterações definido · Prompt de critica estruturado · Output final aprovado pelo crítico

AutoGen permite que o UserProxyAgent execute código Python gerado pelo AssistantAgent em um ambiente controlado — seja localmente, em Docker, ou em sandbox remoto.

Execução de código automatizada é o superpoder do AutoGen. Permite análise de dados, geração de gráficos, scraping, cálculos e qualquer tarefa que código Python resolve — sem humano.

code_execution_config={"work_dir": "..."} · Docker para isolamento · last_n_messages para limitar contexto · Timeout de execução · Captura de stdout e stderr como feedback

AutoGen brilha em: pesquisa exploratória, geração e depuração de código, debates entre perspectivas, e workflows onde o fluxo emergir da conversa é mais natural que grafos pré-definidos.

Escolher o framework errado para o problema certo é um dos erros mais custosos. Entender onde AutoGen supera LangGraph economiza semanas de refatoração.

AutoGen ideal para: code gen + execução iterativa · pesquisa com múltiplas perspectivas · workflows emergentes · LangGraph ideal para: controle de fluxo preciso · estado complexo · produção crítica

O SDK da OpenAI define Agent como uma unidade com instructions (sistema de prompt), tools (ferramentas disponíveis) e handoffs (agentes para quem pode passar controle). Runner é o executor.

Entender a arquitetura do SDK permite usá-lo sem combatê-lo. O design opinionado dele favorece certos padrões — conhecê-los acelera o desenvolvimento.

Agent(name=..., instructions=..., tools=..., handoffs=...) · Runner.run() como executor principal · Context object como estado compartilhado · Resultado como RunResult com histórico

Handoff é quando um agente decide que outro agente é mais adequado para continuar — ele "passa o bastão" com todo o contexto. É como uma transferência telefônica inteligente entre especialistas.

Handoffs permitem especialização: um agente de triagem encaminha para o especialista certo sem que o usuário precise re-explicar o problema — contexto é preservado automaticamente.

handoffs=[agente_especialista] na definição · Transferência automática de contexto · Triage agent como entrada principal · Padrão: triage → billing / technical / general · Handoff como tool call especial

Guardrails são validações que rodam em paralelo com o agente — verificando se o input do usuário é seguro e se o output do agente atende critérios de qualidade antes de ser retornado.

Guardrails nativos eliminam a necessidade de wrappers customizados de validação. São executados de forma paralela, sem adicionar latência ao fluxo principal.

InputGuardrail e OutputGuardrail · @input_guardrail decorator · GuardrailFunctionOutput com tripwire · Execução paralela sem overhead · Integração com content policy da OpenAI

O SDK registra automaticamente cada execução — quais tools foram chamadas, quais handoffs ocorreram, quais guardrails dispararam. Sem configuração adicional, você tem um trace completo.

Debug de sistemas multi-agente sem tracing é adivinhar. Com tracing nativo, você sabe exatamente onde um workflow falhou e quais decisões o agente tomou.

Trace automático por default · Exportação para OpenTelemetry · Integração com LangSmith e Arize · span por tool call · RunResult.trace para acesso programático

Swarm é um padrão onde múltiplos agentes especialistas coexistem e se ativam por handoff — um agente de triagem distribui o trabalho para o especialista mais adequado em cada momento.

Para sistemas de customer service, suporte técnico ou assistentes corporativos, o padrão Swarm é mais escalável que um agente monolítico tentando fazer tudo.

Triage agent como porta de entrada · N agentes especialistas · Handoffs bidirecionais · Contexto compartilhado via Context · Escalabilidade horizontal adicionando agentes

SDK da OpenAI é ideal para projetos simples com OpenAI e handoffs diretos. LangGraph para controle fino de estado e ciclos complexos. A escolha depende de: complexidade, vendor lock-in e requisitos de controle.

Começar com o SDK e migrar para LangGraph quando necessário é um caminho válido. Entender os trade-offs evita super-engenharia prematura.

SDK: simplicidade, OpenAI-first, handoffs nativos · LangGraph: multi-provider, ciclos complexos, estado detalhado · CrewAI: abstração de equipe, menos código · AutoGen: conversação, code gen

MCP (Model Context Protocol) é um protocolo client-server onde o agente (cliente) descobre e chama ferramentas expostas por servidores externos via JSON-RPC sobre stdio ou HTTP.

MCP desacopla ferramentas de frameworks — um servidor MCP funciona com LangGraph, CrewAI e qualquer cliente compatível. É o padrão de interoperabilidade do ecossistema.

JSON-RPC como protocolo base · tools/list para descoberta · tools/call para execução · resources/ para dados · prompts/ para templates · Transports: stdio vs SSE

FastMCP é uma biblioteca Python que simplifica a criação de servidores MCP — você decora funções com @mcp.tool() e o servidor expõe automaticamente o tool/list e tool/call.

Criar seu próprio servidor MCP permite expor qualquer API interna da empresa para agentes — sem precisar alterar o código dos frameworks que os utilizam.

FastMCP() como instância · @mcp.tool() decorator · Type hints geram schema JSON automaticamente · @mcp.resource() para dados · mcp.run() para iniciar · Pydantic para validação

Servidores MCP em HTTP precisam autenticar clientes. Bearer token no header Authorization é o padrão mais simples. OAuth 2.0 para cenários enterprise com múltiplos usuários.

Um servidor MCP sem autenticação expõe suas ferramentas internas para qualquer cliente. Em produção, qualquer servidor acessível externamente precisa de autenticação.

Bearer token via Authorization header · Middleware de validação · Rate limiting por cliente · IP allowlist para servidores internos · Auditoria de chamadas · HTTPS obrigatório em produção

O cliente MCP chama tools/list na inicialização para descobrir todas as ferramentas disponíveis — nome, descrição e schema de parâmetros. Depois chama tools/call para executar.

A descoberta dinâmica permite que o agente se adapte a novos servidores sem reconfiguração. Você pode adicionar ferramentas no servidor e o agente as usa automaticamente.

tools/list retorna lista de ToolDefinition · JSON Schema para parâmetros · Descrições claras guiam o LLM · Versionamento de tools · Cache de lista para performance

Deploy de um servidor MCP como serviço HTTP em plataformas cloud: Railway (zero config), Fly.io (mais controle) ou container Docker em qualquer cloud. O servidor fica acessível por URL.

Um servidor MCP local só funciona em desenvolvimento. Para agentes em produção atenderem usuários reais, o servidor precisa estar disponível 24/7 com alta disponibilidade.

Dockerfile para MCP server · Railway deploy em 5 min · Variáveis de ambiente para secrets · Health check endpoint · Logging estruturado · Restart automático em falhas

Existe um ecossistema crescente de servidores MCP prontos: filesystem, GitHub, PostgreSQL, Brave Search, Slack, Notion e dezenas mais — instale e conecte em minutos.

Antes de construir, verifique se já existe. O ecossistema MCP cresce rapidamente — muitas integrações comuns já estão disponíveis como servidores prontos para uso.

mcp.so como marketplace · Servidores oficiais Anthropic · Servidores da comunidade · Instalação via npx ou pip · Configuração no claude_desktop_config.json · Composição de múltiplos servidores

Os 6 critérios que definem a escolha: controle de fluxo (precisão vs. abstração), curva de aprendizado, suporte a ciclos/loops, observabilidade nativa, tamanho da comunidade e suporte enterprise.

Sem critérios claros, você escolhe framework por hype ou familiaridade. Critérios objetivos garantem que a escolha serve ao problema, não ao gosto pessoal.

Controle de fluxo · Curva de aprendizado · Suporte a loops · Observabilidade · Comunidade e maturidade · Suporte enterprise · Vendor lock-in

LangGraph oferece controle preciso do fluxo via grafo dirigido — ideal para workflows complexos com branches e estados. CrewAI oferece abstração de equipe — ideal para colaboração entre agentes especializados.

São o par mais comparado. Entender a distinção fundamental (fluxo vs. equipe) evita usar a ferramenta certa no contexto errado.

LangGraph: curva alta, controle total, loops nativos · CrewAI: curva baixa, abstração rica, menos controle de fluxo · LangGraph brilha em: produção crítica · CrewAI brilha em: prototipagem rápida

CrewAI organiza agentes em equipes com papéis fixos e tasks definidas. AutoGen organiza agentes em conversas dinâmicas. A diferença é estrutura vs. emergência.

Ambos usam múltiplos agentes, mas de formas radicalmente diferentes. Confundir os dois leva a código estranho que luta contra o design do framework.

CrewAI: tasks definidas, output esperado claro, processo estruturado · AutoGen: conversa emergente, mais flexível, melhor para code gen · Escolha por: previsibilidade vs. flexibilidade

AutoGen usa conversação como mecanismo de controle — agentes se comunicam por mensagens. OpenAI SDK usa handoffs — um agente transfere explicitamente controle para outro. São filosofias opostas de coordenação.

Para customer service e suporte, handoffs do SDK são mais previsíveis. Para pesquisa e code gen, a conversa do AutoGen é mais poderosa. Contexto define a escolha.

AutoGen: multi-provider, código exec, pesquisa · SDK: OpenAI-first, handoffs diretos, guardrails nativos · AutoGen: mais setup · SDK: opinionado mas mais simples para casos simples

Tabela com cenários práticos e o framework recomendado: fluxo complexo com branches (LangGraph), time de agentes com papéis (CrewAI), pesquisa e code gen (AutoGen), projeto simples OpenAI (SDK).

Ter uma tabela de referência rápida elimina a paralisia de escolha. Em vez de comparar infinitamente, você consulta o guia e decide em minutos.

Por cenário de uso · Por requisito técnico · Por nível de experiência da equipe · Por budget de infra · Por necessidade de observabilidade · Por tempo de desenvolvimento disponível

Estratégias para migrar de um framework para outro sem reescrever tudo: identificar o núcleo lógico do agente, isolar ferramentas como MCP servers, migrar incrementalmente por módulo.

É comum começar com CrewAI e migrar para LangGraph quando o sistema cresce. Saber migrar sem big bang reescreve economiza semanas de risco de projeto.

Isolar ferramentas via MCP · Extrair lógica de negócio · Migrar nó a nó · Feature flags para rollout gradual · Testes A/B entre versões · Manter backwards compatibility durante transição

LangGraph é excelente em controle de fluxo preciso (quando fazer o quê) mas verboso para colaboração multi-agente. CrewAI é excelente em abstração de equipe mas fraco em controle de fluxo. Combinados, cobrem ambos.

Sistemas reais em produção frequentemente precisam de fluxo preciso em algumas etapas e trabalho em equipe em outras. Saber combinar é a habilidade de engenharia agentic madura.

LangGraph como orquestrador macro · CrewAI como nó especializado · Separação de responsabilidades clara · Estado fluindo entre os dois · Checkpoint antes e depois da Crew

LangGraph define a estrutura macro do sistema — quais etapas existem, em que ordem, com quais condições de saída. CrewAI executa dentro de nós específicos sem LangGraph saber os detalhes internos da Crew.

Separar orquestração macro (LangGraph) de execução especializada (CrewAI) cria sistemas mais manuteníveis — você pode substituir a Crew sem alterar o grafo e vice-versa.

Nó do LangGraph instancia e executa uma Crew · Crew recebe input do state · Crew retorna resultado que volta ao state · LangGraph decide próximo passo baseado no resultado · Interface clara entre os dois

Um nó do LangGraph que, ao ser executado, instancia uma Crew completa, chama crew.kickoff() com os inputs do state, e retorna o resultado de volta para o state do grafo.

É o padrão de implementação concreto. Saber exatamente como encapsular a Crew em uma função de nó é a habilidade técnica central desta integração.

def crew_node(state: State): crew = create_crew(state) · result = crew.kickoff() · return {"crew_result": result} · Crew criada fresh a cada execução ou reutilizada · Timeout no nó para limitar execução

O estado do LangGraph (TypedDict) é convertido para o formato de input da Crew, e o output da Crew é serializado de volta para o estado. A fronteira é o nó que faz essa tradução.

A interface entre frameworks é onde bugs acontecem. Definir claramente o contrato de entrada/saída entre LangGraph e CrewAI previne problemas de tipo e dados perdidos.

Pydantic para validar o contrato de interface · Serialização explícita de tipos complexos · Logs na fronteira para debug · Teste unitário do nó de integração · Estado parcial vs. estado completo na Crew

Três padrões comprovados: (1) Nó único de Crew, (2) Múltiplas Crews em nós paralelos, (3) Crew que usa LangGraph sub-grafo internamente. Cada padrão resolve um tipo de problema diferente.

Padrões nomeados facilitam comunicação na equipe e evitam reinventar soluções. Um "Padrão Crew-no-Nó" é auto-explicativo para qualquer engenheiro que conhece o material.

Padrão 1: Nó único sequencial · Padrão 2: Crews paralelas em Send() API · Padrão 3: Crew com grafo interno · Escolha por complexidade e paralelismo · Documentação do padrão no código

Sistema de due diligence onde LangGraph orquestra as etapas (coleta de dados → análise → validação → relatório) e uma CrewAI executa a etapa de análise com time especializado (financeiro, jurídico, mercado).

Ver um projeto completo end-to-end com ambos os frameworks consolida todos os conceitos anteriores em um sistema coerente — do TypedDict inicial até o relatório final.

4 nós no LangGraph (coleta, análise via Crew, validação, relatório) · Crew de 3 analistas · Checkpoint antes e depois · Streaming de progresso · Output final estruturado em Pydantic

Observabilidade para agentes vai além de logging — envolve traces (fluxo completo de execução), spans (duração de cada etapa), métricas (taxas de sucesso, custo, latência) e avaliação de qualidade das respostas.

Sem observabilidade, você está cego em produção. Não sabe qual nó está falhando, quanto custa por execução, nem se a qualidade do output degradou após uma mudança de prompt.

Traces vs. Logs vs. Métricas · Span como unidade de execução · LLM como-judge para qualidade · Cost tracking por run · Latência P50/P95/P99 · Alertas automáticos

LangSmith é a plataforma de observabilidade da LangChain — captura automaticamente traces de execuções LangGraph, mostra inputs/outputs de cada nó, custo de tokens e permite filtrar runs com erro.

LangSmith se integra com LangGraph em 3 linhas de configuração. É a ferramenta mais usada para debug e monitoramento de sistemas baseados em LangChain/LangGraph.

LANGCHAIN_TRACING_V2=true · LANGCHAIN_API_KEY= · Trace automático sem código adicional · Filtros por status, model, data · Comparação de runs A/B · Datasets para regression testing

Arize Phoenix é uma plataforma open-source de observabilidade para LLMs — roda localmente, captura traces via OpenTelemetry, visualiza embeddings e permite avaliar qualidade de respostas.

Para quem não pode usar SaaS por compliance ou custo, Phoenix oferece capacidades similares ao LangSmith self-hosted. É o padrão open-source do ecossistema de observabilidade para LLMs.

pip install arize-phoenix · px.launch_app() para UI local · OpenInference como formato de trace · Instrumentação automática via openinference-instrumentation · Exportação para Arize cloud opcional

Métricas técnicas: latência, tokens, erros. Métricas de negócio: taxa de sucesso por objetivo de usuário, custo médio por execução bem-sucedida, NPS do sistema agentic, ROI vs. processo manual.

Stakeholders de negócio não se importam com latência P95. Eles querem saber se o sistema resolve o problema e quanto custa. Métricas de negócio traduzem desempenho técnico em valor.

Taxa de conclusão de objetivo · Custo por tarefa completada · Tempo médio de execução · Taxa de erro por tipo · Satisfação do usuário final · ROI vs. automação alternativa

Configurar alertas automáticos quando métricas ultrapassam thresholds: taxa de erro acima de 5%, custo por hora acima do budget, latência P95 acima de 30s. Dashboards para visão em tempo real.

Descobrir problemas pelo cliente é o pior cenário. Alertas proativos permitem que você detecte e corrija degradações antes que afetem usuários — diferença entre SLA cumprido e incidente.

Threshold por métrica com hysteresis · Notificação via Slack/PagerDuty · Dashboard por trilha de agentes · Anotações de deploy para correlação · Runbooks de resposta a alertas

LLM-as-judge: usar outro LLM para avaliar automaticamente a qualidade das respostas do agente em produção — pontuando relevância, completude, tom e corretude em cada execução.

Avaliação manual de qualidade não escala. Com LLM-as-judge, você tem feedback automático sobre qualidade de cada resposta — detectando degradação antes que cause problemas reais.

Evaluator LLM separado do agente principal · Rubrica de avaliação estruturada · Score 1-5 por dimensão · Amostragem aleatória em produção · Trending de qualidade ao longo do tempo · Gatilho de re-treino quando score cai