Phase 16 - Lesson 04

O Modelo de Primitivas Multiagente

Cada framework multiagente lançado em 2026 — AutoGen, LangGraph, CrewAI, OpenAI Agents SDK, Microsoft Agent Framework — é um ponto em um espaço de design quadridimensional. Quatro primitivas, nada mais: o agente, o handoff, o estado compartilhado e o orquestrador. Esta lição os constrói a partir do zero, executa um sistema experimental em todos os quatro e, em seguida, mapeia cada um dos principais frameworks nos mesmos eixos para que você possa entender qualquer novo lançamento em um único parágrafo.

Tipo: Aprender Linguagens: Python (stdlib) Pré-requisitos: Fase 14 (Engenharia de Agentes), Fase 16 · 01 (Por que Multiagente) Tempo: ~60 minutos

O Problema

A cada seis meses, um novo framework multiagente é lançado. AutoGen em 2023. CrewAI em 2024. LangGraph e OpenAI Swarm in 2024. Google ADK em abril de 2025. Microsoft Agent Framework RC em fevereiro de 2026. Cada comunicado de imprensa afirma ser "a abstração correta".

Se você tentar aprendê-los um de cada vez, sofrerá um esgotamento (burnout). As APIs parecem diferentes. As documentações discordam sobre o que é um "agente". Um framework chama sua memória compartilhada de "blackboard", outro a chama de "message pool" e um terceiro a chama de "StateGraph". Você começa a suspeitar que a área está apenas se repetindo desnecessariamente.

Não está. Por trás do marketing, as quatro primitivas são estáveis. Aprenda-as uma vez e compreenda qualquer novo framework em um único parágrafo.

Conceito

As quatro primitivas

1. Agente — um prompt do sistema mais uma lista de ferramentas. Não tem estado (stateless); cada execução começa a partir de seu prompt do sistema e do histórico de mensagens atual.
2. Handoff — uma transferência estruturada de controle de um agente para outro. Mecanicamente, uma chamada de ferramenta que retorna um novo agente ou uma aresta do grafo que segue uma condição.
3. Estado compartilhado — qualquer estrutura de dados que mais de um agente possa ler (e, às vezes, gravar). Pool de mensagens, blackboard, armazenamento de chave-valor, memória vetorial.
4. Orquestrador — quem decide quem fala a seguir. Opções: um grafo explícito (determinístico), um selecionador de palestrante baseado em LLM (suave/soft), a chamada de handoff do último palestrante (OpenAI Swarm) ou um agendador sobre uma fila (arquitetura swarm).

Esse é todo o espaço de design. Cada framework escolhe padrões para cada eixo; o resto é sintaxe superficial.

Como cada framework de 2026 se mapeia a ele

Diferenças superficiais parecem enormes. Por baixo: os mesmos quatro botões de controle.

Por que isso importa

Uma vez que você enxerga as primitivas, a comparação de frameworks se torna um breve checklist:

• O orquestrador confia na LLM para rotear (Swarm) ou define o roteamento fixo no código (LangGraph)?
• O estado compartilhado é de histórico completo (GroupChat) ou projetado (redutor StateGraph)?
• Os agentes podem modificar os prompts uns dos outros (gerente CrewAI) ou apenas fazer handoff (Swarm)?

Essas três perguntas respondem a 80% de qual framework se adapta a um determinado problema. Você para de procurar pelo "melhor framework multiagente" e começa a projetar para o eixo com o qual você realmente se importa.

A percepção stateless

Toda primitiva, exceto o estado compartilhado, é stateless (não tem estado). O Agente é uma função de (prompt, ferramentas). O Handoff é uma chamada de função. O Orquestrador é um agendador. A única coisa que possui estado no sistema é o estado compartilhado. É aí que vivem todos os bugs interessantes: envenenamento de memória (Lição 15), ordenação de mensagens, versionamento, contenção de escrita.

Frameworks que ocultam o estado compartilhado (Swarm) transferem o problema para o chamador. Frameworks que o centralizam (checkpoint do LangGraph, pool do AutoGen) o tornam inspecionável, mas deslocam o custo de coordenação para a implementação do estado compartilhado.

Anatomia de uma única primitiva

Agente

Agent = (system_prompt, tools, model, optional_name)

Sem memória. Sem estado. Dois agentes com o mesmo prompt do sistema e as mesmas ferramentas são intercambiáveis. Tudo o que parece ser o estado de um agente individual está, na verdade, no estado compartilhado ou no protocolo de handoff.

Handoff

Handoff = (from_agent, to_agent, reason, payload)

Três implementações dominam:

• Retorno de função — a ferramenta retorna o próximo agente. Este é o padrão do OpenAI Swarm. Os agentes carregam o roteamento em seus esquemas de ferramentas.
• Aresta de grafo — LangGraph. As arestas são declarativas. A LLM produz um valor; uma condição seleciona o próximo nó.
• Seleção de palestrante — AutoGen GroupChat. Uma função seletora (às vezes a própria chamada de uma LLM) lê o pool e escolhe quem fala a seguir.

Estado compartilhado

SharedState = { messages: [], artifacts: {}, context: {} }

No mínimo, uma lista de mensagens. Frequentemente mais: artefatos estruturados (saídas de Task do CrewAI), contexto tipado (redutores do LangGraph), memória externa (MCP, banco de dados vetorial).

Duas topologias: pool completo (cada agente vê cada mensagem) e projetado (agentes veem uma visão delimitada por papel/função). Pools completos são simples e escalam mal. Pools projetados escalam, mas exigem design de esquema prévio.

Orquestrador

Orchestrator = ({state, last_speaker}) -> next_agent

Quatro tipos:

• Estático — o grafo é fixado em tempo de compilação (determinístico no LangGraph, Sequential no CrewAI).
• Selecionado por LLM — uma LLM lê o pool e escolhe o próximo palestrante (AutoGen, Hierarchical do CrewAI).
• Direcionado por handoff — o agente atual decide chamando uma ferramenta de handoff (Swarm).
• Direcionado por fila — os workers buscam tarefas em uma fila compartilhada; sem um próximo palestrante explícito (arquiteturas swarm, Matrix).

O que muda entre os frameworks

Uma vez fixadas as primitivas, as decisões de design restantes são:

• Estratégia de memória — checkpointing efêmero versus durável (checkpointer do LangGraph).
• Fronteira de segurança — quem pode aprovar um handoff (humano no circuito / human-in-the-loop).
• Contabilidade de custos — orçamentos de tokens por agente.
• Observabilidade — rastreamento de handoffs, persistência de estado para reprodução (replay).

Tudo implementável sobre as primitivas. Nenhum deles é uma nova primitiva.

Construa

code/main.py implementa as quatro primitivas em aproximadamente 150 linhas de Python stdlib. Sem LLM real — cada agente é uma política programada em script para que o foco permaneça na estrutura de coordenação.

O arquivo exporta:

• Agent — uma dataclass de nome, prompt do sistema, ferramentas, função de política.
• Handoff — uma função que retorna um novo agente.
• SharedState — um pool de mensagens thread-safe.
• Orchestrator — três variantes: StaticOrchestrator, HandoffOrchestrator, LLMSelectorOrchestrator (simulado).

A demonstração executa o mesmo pipeline de três agentes (pesquisa → escrita → revisão) por meio de todos os três tipos de orquestrador e imprime o pool de mensagens no final. Você pode ver que as saídas diferem apenas em quem escolhe o próximo; os agentes e o estado compartilhado são idênticos em todas as execuções.

Execute-o:

python3 code/main.py

Saída esperada: três execuções do orquestrador, uma por padrão. Cada uma imprime o pool final de mensagens. A execução direcionada por handoff atinge menos agentes se o pesquisador decidir que concluiu cedo — esse é o trade-off do roteamento por LLM em miniatura.

Use

outputs/skill-primitive-mapper.md é uma habilidade (skill) que lê qualquer base de código ou documentação de framework multiagente e retorna o mapeamento das quatro primitivas. Execute-o em um novo lançamento de framework para obter uma compreensão de um parágrafo antes de ler as documentações detalhadamente.

Coloque em Produção

Antes de adotar um novo framework, escreva o mapeamento de primitivas para ele. Se não conseguir, a documentação está incompleta ou o framework está inventando uma quinta primitiva (raro — verifique se há um estilo de estado compartilhado que você ainda não viu).

Fixe o mapeamento no seu documento de arquitetura. Quando um novo membro da equipe entrar, envie o mapeamento antes dos documentos da API. Quando as versões do framework mudarem, compare (diff) o mapeamento, não o registro de alterações (changelog).

Exercícios

1. Execute code/main.py três vezes com diferentes políticas de agente. Observe como a escolha do orquestrador altera quais agentes são executados.
2. Implemente um quarto tipo de orquestrador: um direcionado por fila no qual os agentes consultam (poll) o estado compartilhado para buscar trabalho. Qual deadlock pode acontecer e como você o detecta?
3. Pegue o guia de início rápido do LangGraph (https://docs.langchain.com/oss/python/langgraph/workflows-agents) e reescreva-o como as quatro primitivas. Quais das abstrações do LangGraph mapeiam 1:1 e quais são wrappers de conveniência?
4. Leia o cookbook do OpenAI Swarm (https://developers.openai.com/cookbook/examples/orchestrating_agents). Identifique qual das quatro primitivas o Swarm torna mais ergonômica e qual ele empurra para o chamador.
5. Encontre um framework nesta tabela que oculte inteiramente o estado compartilhado. Explique o que quebra quando os agentes precisam coordenar através de handoffs sem reler o histórico.

Termos-Chave

Leitura Adicional

• OpenAI cookbook: Orchestrating Agents — Routines and Handoffs — a articulação mais clara da orquestração direcionada por handoff
• Documentações estáveis do AutoGen — GroupChat + seleção de palestrante é a referência para orquestração selecionada por LLM
• Workflows e agentes do LangGraph — orquestração de arestas de grafo e estado compartilhado baseado em redutores
• Introdução ao CrewAI — agentes com papéis, objetivos e histórias de fundo, processos sequenciais / hierárquicos
• AG2 (continuação comunitária do AutoGen) — a linha ativa do AutoGen v0.2 depois que a Microsoft colocou a v0.4 em manutenção