🧩 Por que Multiplos Agentes
Limitacoes de agente unico. Quando dividir em multiplos agentes.
Um agente unico parece a solucao ideal: um sistema que faz tudo. Na pratica, agentes sobrecarregados falham mais. Quanto mais tools, mais contexto, mais roles voce empilha em um unico agente, mais provavel que ele se confunda, escolha a tool errada, ou perca o fio da tarefa.
A context window e a primeira limitacao fisica. Um agente que precisa carregar 20 tool definitions, um system prompt longo, historico de conversa e resultados de tools anteriores rapidamente enche 128k tokens. Quando o contexto esta cheio, o modelo comeca a "esquecer" instrucoes do inicio.
A segunda limitacao e especializacao. Um modelo com 5 tools de busca, 5 de escrita, 5 de analise e 5 de comunicacao tem 20 opcoes a cada decisao. Pesquisas mostram que LLMs perdem ate 40% de precisao na selecao de tools quando ha mais de 10-15 opcoes. Dividir em agentes especializados resolve isso: cada um tem 3-5 tools no maximo.
📊 Por que Multiagentes Funcionam
precisao na selecao de tools quando agente tem 15+ tools registradas
tokens de contexto tipico. Agente complexo facilmente usa 60-80% so com setup
tools por agente e o sweet spot para maximizar precisao de selecao
ganho de velocidade com execucao paralela de agentes independentes
Quando Dividir em Multiplos Agentes
Nem todo sistema precisa de multiagentes. Use os sinais abaixo para decidir:
Muitas tools com propositos diferentes
Se voce tem tools de busca, escrita, analise e comunicacao no mesmo agente, divida. Um agente de pesquisa (busca tools), um de geracao (escrita tools), um de validacao (analise tools).
Tarefas que podem rodar em paralelo
Se parte do trabalho e independente (ex: pesquisar dados E gerar template ao mesmo tempo), agentes separados permitem execucao paralela real. Um agente unico faz tudo sequencial.
Requisitos de qualidade diferentes por etapa
Classificacao de intencao precisa de velocidade (modelo leve). Geracao de codigo precisa de raciocinio profundo (modelo forte). Modelos diferentes por agente otimizam custo e qualidade.
Context window estourando
Se o agente regularmente atinge 70%+ da context window, e hora de dividir. Cada agente comeca com contexto limpo e recebe apenas o necessario via handoff.
Agente Unico vs Multiagentes
| Aspecto | Agente Unico | Multiagentes |
|---|---|---|
| Complexidade | Simples de implementar | Requer orquestracao e handoff |
| Precisao | Degrada com muitas tools | Alta (tools focadas por agente) |
| Velocidade | Sequencial sempre | Paralelo quando possivel |
| Custo | Menor overhead de setup | Pode otimizar por modelo/agente |
| Debugging | Um log, um fluxo | Traces distribuidos, mais complexo |
💡 Dica
Comece com agente unico. So divida quando sentir os problemas: tools demais, contexto estourando, ou tarefas que poderiam rodar em paralelo mas estao travadas esperando sequencia. Premature multi-agent e tao ruim quanto premature optimization.
Fazer
- ●Comecar com agente unico e evoluir quando necessario
- ●Medir precisao de tool selection antes de dividir
- ●Usar metricas (context usage, error rate) para justificar split
- ●Agrupar tools por dominio ao criar agentes especializados
Evitar
- ●Criar 10 agentes quando 3 resolveriam
- ●Dividir sem planejar a comunicacao entre eles
- ●Ignorar o custo de orquestracao (cada hop = latencia + tokens)
- ●Multiagentes para problemas simples (over-engineering)
🔀 Padroes de Orquestracao
Sequential, parallel, router, hierarchical. Quando usar cada um.
Orquestracao e o codigo que decide quem faz o que, em que ordem, e como os resultados fluem entre agentes. Existem 4 padroes principais, e a escolha certa depende da natureza da tarefa. A maioria dos sistemas reais combina mais de um padrao.
O erro mais comum e escolher o padrao errado. Sequential chain para tarefas independentes desperica tempo. Parallel fan-out para tarefas dependentes causa race conditions. Router sem fallback deixa mensagens sem resposta. Entender quando usar cada padrao e tao importante quanto saber implementa-lo.
Pense na orquestracao como a gestao de uma equipe: o orquestrador e o gerente que distribui tarefas, acompanha progresso e consolida resultados. Os agentes sao os especialistas que executam. A qualidade do sistema depende tanto do gerente quanto dos especialistas.
4 Padroes Fundamentais
Sequential Chain (Pipeline)
Agente A processa, passa resultado para Agente B, que passa para Agente C. Cada etapa transforma o output da anterior. Ordem fixa e previsivel.
Quando usar: Pipelines de processamento com dependencia entre etapas. Geracao de conteudo (pesquisa > escrita > revisao). ETL de dados.
Parallel Fan-out
Multiplos agentes recebem a mesma tarefa (ou partes independentes) e trabalham ao mesmo tempo. Um aggregator consolida os resultados no final.
→ [Agent B] → [Aggregator] → Output
→ [Agent C] ↗
Quando usar: Pesquisas em multiplas fontes. Analise de multiplos documentos. Geracao de multiplas opcoes para comparacao.
Router / Dispatcher
Um classificador analisa a mensagem e roteia para o agente especialista correto. Cada agente lida com um tipo de tarefa. O router pode ser LLM leve ou regra.
→ "dados" → [Data Agent]
→ "texto" → [Content Agent]
Quando usar: Chatbots multi-dominio. Sistemas com agentes especializados por area. Qualquer caso onde o tipo de tarefa determina quem resolve.
Hierarchical (Manager + Workers)
Um agente gerente planeja, delega sub-tarefas para workers, monitora progresso e valida resultados. Os workers sao agentes especializados que executam.
→ [Worker B]
← validate ← results
Quando usar: Projetos complexos com multiplas etapas. Quando o plano precisa ser adaptavel. Quando a qualidade do output requer validacao centralizada.
💡 Dica
Na pratica, a maioria dos sistemas usa Router + Sequential: o router classifica a mensagem, e dentro de cada agente especialista ha um pipeline sequencial. Comece com esse combo. So adicione parallel e hierarchical quando tiver necessidade comprovada.
Fazer
- ●Escolher padrao baseado na natureza da tarefa, nao em hype
- ●Implementar fallback em todo router (caso nenhum agente match)
- ●Medir latencia de cada padrao no seu caso de uso
- ●Combinar padroes quando necessario (router + pipeline)
Evitar
- ●Parallel para tarefas com dependencia (race condition)
- ●Sequential para tarefas independentes (desperica tempo)
- ●Hierarchical para tarefas simples (overhead de manager)
- ●Router sem metricas de acuracia de classificacao
👥 Roles: Executor, Analista, Revisor
Papeis especializados para qualidade. Separacao de responsabilidades.
O poder dos sistemas multiagentes vem da especializacao de roles. Assim como em uma equipe real, cada agente tem um papel definido com responsabilidades claras, ferramentas especificas e criterios de sucesso proprios. O padrao mais comum e o trio: Executor (faz), Analista (avalia), Revisor (valida).
A separacao de roles nao e burocracia. E controle de qualidade embutido no fluxo. Um agente que gera codigo E revisa seu proprio codigo tem vieses. Um agente separado de revisao, com criterios diferentes e sem acesso ao "raciocinio" do gerador, encontra problemas que o gerador original nunca veria. E o mesmo principio de code review entre humanos.
Cada role pode usar um modelo diferente otimizado para sua funcao. O Executor pode usar Claude Sonnet (raciocinio forte para geracao). O Analista pode usar DeepSeek R1 (barato, bom em analise logica). O Revisor pode usar um modelo com guidelines especificas de seguranca e qualidade.
Os 3 Roles Fundamentais
O "braco" do sistema. Gera codigo, redige texto, processa dados, cria arquivos. Faz o trabalho produtivo.
Tools: code_write, file_create, data_transform
Modelo: Claude Sonnet, GPT-4o (raciocinio forte)
Criterio: Output funcional e completo
O "olho critico". Avalia resultados, identifica problemas de logica, sugere melhorias. Nao gera, analisa.
Tools: code_analyze, run_tests, check_logic
Modelo: DeepSeek R1, Claude Haiku (analise barata)
Criterio: Problemas encontrados + sugestoes claras
O "QA final". Valida qualidade, checa seguranca, verifica consistencia. Aprova ou rejeita com justificativa.
Tools: security_scan, lint, validate_schema
Modelo: Modelo com safety guidelines fortes
Criterio: Aprovado/Rejeitado + razoes
System Prompts por Role
Cada agente precisa de um system prompt que define claramente seu papel, limites e criterios:
System Prompt: Executor
"Voce e um agente executor especializado em geracao de codigo TypeScript. Sua unica funcao e produzir codigo funcional e limpo. NAO faca analise de seguranca (o Revisor faz isso). NAO sugira melhorias (o Analista faz isso). Gere o codigo e pare."
System Prompt: Analista
"Voce e um agente analista. Receba codigo e identifique: bugs logicos, edge cases nao tratados, problemas de performance, e oportunidades de melhoria. Retorne uma lista estruturada de issues com severidade (alta/media/baixa) e sugestao de correcao."
System Prompt: Revisor
"Voce e um agente revisor de seguranca e qualidade. Valide: SQL injection, XSS, secrets expostos, type safety, error handling. Retorne APROVADO ou REJEITADO com lista de problemas criticos. Seja rigoroso: na duvida, rejeite."
Fluxo Executor → Analista → Revisor
O pipeline completo com retry loop quando o revisor rejeita:
async function pipeline(task: string, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
// 1. Executor gera output
const output = await executor.run(task);
// 2. Analista avalia e sugere melhorias
const analysis = await analyst.run(output);
// 3. Se ha issues criticas, executor refaz com feedback
if (analysis.critical_issues.length > 0) {
task = `${task}\n\nFEEDBACK DO ANALISTA:\n${
analysis.suggestions.join('\n')}`;
continue;
}
// 4. Revisor da aprovacao final
const review = await reviewer.run(output);
if (review.approved) return output;
// 5. Se rejeitado, executor refaz com razoes
task = `${task}\n\nREJEICAO DO REVISOR:\n${
review.reasons.join('\n')}`;
}
throw new Error("Max retries reached");
}
💡 Dica
O segredo e nao dar ao agente informacao sobre os outros roles. O Executor nao sabe que sera revisado. Isso evita "preguica" (gerar output pior sabendo que outro vai corrigir). Cada agente deve produzir seu melhor trabalho como se fosse a versao final.
Fazer
- ●System prompts claros e exclusivos por role
- ●Modelos diferentes por role (otimizar custo/qualidade)
- ●Retry loop com feedback do revisor para o executor
- ●Criterios de aprovacao/rejeicao explicitos e mensuaveis
Evitar
- ●Mesmo modelo e prompt para todos os roles (perde o beneficio)
- ●Revisor que sempre aprova (revisao cosmetic, nao funcional)
- ●Retry infinito entre executor e revisor (limitar a 3 tentativas)
- ●Roles ambiguos com responsabilidades sobrepostas
💬 Comunicacao entre Agentes
Message passing, shared state, event bus. Protocolos de handoff.
Agentes isolados que nao se comunicam sao apenas agentes separados, nao um sistema. A comunicacao entre agentes e o que transforma agentes individuais em um time coordenado. Como os agentes trocam informacao, passam contexto e delegam tarefas determina a qualidade do sistema inteiro.
Existem tres abordagens principais: message passing (agentes enviam mensagens diretamente entre si), shared state (agentes leem e escrevem em um estado compartilhado), e event bus (agentes publicam e assinam eventos). Cada uma tem trade-offs de acoplamento, complexidade e escalabilidade.
O handoff entre agentes e o momento mais critico. Se o Agente A passa contexto insuficiente para o Agente B, o resultado sera ruim independente da qualidade de B. Structured handoff com formato JSON padronizado e a melhor forma de garantir que nenhuma informacao se perca na transicao.
3 Padroes de Comunicacao
Message Passing (Direto)
Agentes enviam mensagens diretamente uns aos outros. Simples, baixo acoplamento, mas precisa saber "para quem" enviar. Funciona bem com Router pattern.
Pros: Simples, cada agente e independente, facil de testar isolado
Cons: Ponto-a-ponto, nao escala bem com muitos agentes, coupling de enderecamento
Shared State (Estado Compartilhado)
Agentes leem e escrevem em um objeto/banco compartilhado. Cada agente pega o que precisa e deixa seus resultados. Como um quadro branco onde todos escrevem.
Pros: Desacoplado, agentes nao precisam se conhecer, facil de adicionar novos
Cons: Race conditions, precisa de locking, mais complexo de debugar
Event Bus (Pub/Sub)
Agentes publicam eventos ("pesquisa_concluida", "codigo_gerado") e outros agentes assinam os eventos relevantes. Desacoplamento maximo.
Pros: Maximo desacoplamento, escala horizontal, facil de adicionar/remover agentes
Cons: Mais complexo, debugging distribuido, pode ter eventos perdidos
Structured Handoff Protocol
Todo handoff entre agentes deve seguir um formato padronizado para evitar perda de contexto:
{
"handoff": {
"id": "hf_001",
"timestamp": "2026-03-09T14:30:00Z",
"from": {
"agent_id": "research-agent",
"role": "researcher",
"model": "deepseek-r1"
},
"to": {
"agent_id": "writer-agent",
"role": "executor"
},
"task": {
"original": "Escrever artigo sobre MCP protocol",
"current_step": "Gerar rascunho baseado na pesquisa"
},
"context": {
"research_results": [
{"source": "anthropic.com/mcp", "summary": "..."},
{"source": "github.com/modelcontextprotocol", "summary": "..."}
],
"user_preferences": "tom tecnico, exemplos praticos",
"constraints": "maximo 2000 palavras, PT-BR"
},
"conversation_summary": "Usuario pediu artigo sobre MCP.
Pesquisa concluida: 5 fontes, 3 exemplos de codigo.
Foco em implementacao pratica, nao teoria.",
"metadata": {
"total_tokens_used": 15420,
"elapsed_time_ms": 8500,
"iteration_count": 3
}
}
}
Note como o handoff inclui tudo que o agente receptor precisa: quem enviou, a tarefa, o contexto coletado, um resumo da conversa ate agora, e metadados de custo/tempo. O receptor comeca com informacao completa.
JSON Message Format entre Agentes
Mensagens entre agentes devem ser estruturadas, nao texto livre. Formato padrao:
interface AgentMessage {
type: "request" | "response" | "error" | "status";
from: string; // agent_id
to: string; // agent_id
correlation_id: string; // rastrear request/response
payload: {
task?: string;
result?: any;
error?: { code: string; message: string };
status?: "working" | "done" | "blocked";
};
metadata: {
timestamp: string;
tokens_used?: number;
model?: string;
};
}
💡 Dica
Para projetos iniciais, use message passing direto com JSON tipado. Shared state e event bus adicionam complexidade que so vale em sistemas com 5+ agentes. Um objeto TypeScript com interface definida resolve a comunicacao entre 2-3 agentes de forma simples e type-safe.
Fazer
- ●Padronizar formato de mensagem entre todos os agentes
- ●Incluir conversation_summary em todo handoff
- ●Usar correlation_id para rastrear request/response
- ●Logar toda comunicacao entre agentes para debug
Evitar
- ●Handoff com texto livre (perde estrutura, dificil de parsear)
- ●Agentes que conversam entre si sem limite (loop infinito)
- ●Passar contexto inteiro (so passar o que o receptor precisa)
- ●Comunicacao sem timeout (agente pode travar esperando)
🏗️ Frameworks: CrewAI, LangGraph, Swarm
Comparacao de frameworks multiagentes. Pros e cons de cada um.
Voce nao precisa construir tudo do zero. Existem frameworks que abstraem a complexidade de orquestracao, comunicacao e gerenciamento de agentes. Os tres mais relevantes em 2026 sao CrewAI (role-based, Python), LangGraph (graph-based, Python/JS) e OpenAI Swarm (lightweight, Python).
Cada framework tem uma filosofia diferente. CrewAI pensa em agentes como "membros de uma equipe" com roles, goals e backstory. LangGraph modela o fluxo como um grafo de estados com edges condicionais. Swarm e minimalista: handoff functions que transferem controle entre agentes. A escolha depende do seu caso de uso e preferencia de abstraccao.
Uma quarta opcao que ganha tracao e construir do zero. Para sistemas simples (2-3 agentes, comunicacao direta), um orchestrator custom com 100-200 linhas de codigo pode ser mais simples de manter do que aprender e debugar um framework. Frameworks brilham quando a complexidade justifica a abstraccao.
Comparacao de Frameworks
| Aspecto | CrewAI | LangGraph | Swarm |
|---|---|---|---|
| Filosofia | Role-based crew | State graph | Handoff functions |
| Linguagem | Python | Python, JS/TS | Python |
| Complexidade | Media (muita magia) | Alta (grafo explicito) | Baixa (minimalista) |
| Controle | Abstrato (framework decide) | Total (voce define edges) | Alto (handoff explicito) |
| Provider | Multi (OpenAI, Anthropic...) | Multi (via LangChain) | OpenAI only |
| Ideal para | Prototipos rapidos | Fluxos complexos/condicionais | Sistemas leves e diretos |
Exemplo em Cada Framework
CrewAI (Python)
from crewai import Agent, Task, Crew
researcher = Agent(
role="Pesquisador",
goal="Encontrar dados relevantes sobre o tema",
backstory="Voce e um pesquisador senior com 10 anos...",
tools=[search_tool, scrape_tool]
)
writer = Agent(role="Redator", goal="Escrever artigo...", ...)
crew = Crew(agents=[researcher, writer], tasks=[...])
result = crew.kickoff()
LangGraph (Python)
from langgraph.graph import StateGraph
graph = StateGraph(AgentState)
graph.add_node("researcher", research_node)
graph.add_node("writer", writer_node)
graph.add_node("reviewer", reviewer_node)
graph.add_edge("researcher", "writer")
graph.add_conditional_edges("reviewer",
lambda s: "writer" if not s["approved"] else END)
app = graph.compile()
OpenAI Swarm (Python)
from swarm import Swarm, Agent
def transfer_to_writer():
return writer_agent
researcher = Agent(
name="Researcher",
instructions="Pesquise o tema e transfira para o Writer.",
functions=[search, transfer_to_writer]
)
writer = Agent(name="Writer", instructions="Escreva...", ...)
client = Swarm()
response = client.run(agent=researcher, messages=[...])
📊 Ecossistema de Frameworks (2026)
50k+ stars GitHub. Popular para prototipos. Role/goal/backstory abstraction.
Parte do LangChain ecosystem. Controle total via graph. Producao-ready.
OpenAI experimental. ~500 linhas de codigo. Educational, nao production.
100-300 linhas fazem um orchestrator funcional. Controle total, zero dependencia.
💡 Dica
Antes de adotar um framework, construa um prototipo custom com 100 linhas. Isso forca voce a entender os padroes (routing, handoff, state) antes de delegar para abstraccoes. Depois, se a complexidade crescer, migre para um framework sabendo exatamente o que ele faz por baixo. Quem entende o padrao usa qualquer framework.
Fazer
- ●Entender o padrao antes de adotar o framework
- ●Avaliar se o framework suporta seu provider (Anthropic, OpenAI, local)
- ●Testar performance e custo com seu caso de uso real
- ●Considerar a opcao "custom" para sistemas simples
Evitar
- ●Escolher framework por hype sem avaliar fit
- ●Frameworks complexos para problemas simples (over-engineering)
- ●Depender de abstraccoes sem entender o que acontece por baixo
- ●Assumir que Swarm e production-ready (e experimental)
🛠️ Exercicio: Sistema de 3 Agentes
Router + Specialist + Reviewer. Construa, teste, itere.
Neste exercicio voce vai construir um sistema multiagente funcional com 3 agentes: um Router que classifica a intencao da mensagem, um Specialist que executa a tarefa, e um Reviewer que valida o resultado. O sistema deve funcionar end-to-end: receber uma mensagem, rotear para o agente certo, executar, revisar e retornar.
Este exercicio combina tudo que voce aprendeu: roles especializados, padroes de orquestracao, comunicacao estruturada e handoff. O Router usa o padrao Router/Dispatcher. O Specialist + Reviewer usa o padrao Sequential Chain. E a comunicacao entre eles usa JSON messages com handoff protocol.
Arquitetura do Sistema
Mensagem do usuario
|
[Router Agent]
|
+-- "codigo" --→ [Code Specialist] --→ [Code Reviewer] --→ Output
|
+-- "dados" --→ [Data Specialist] --→ [Data Reviewer] --→ Output
|
+-- "texto" --→ [Text Specialist] --→ [Text Reviewer] --→ Output
|
+-- "outro" --→ Resposta direta (sem specialist)
Para simplificar, implemente apenas 1 tipo de Specialist (ex: Code). O padrao e o mesmo para todos, muda apenas o system prompt e as tools.
Especificacao dos 3 Agentes
Router Agent
Classifica a intencao da mensagem e roteia. Use modelo leve (Haiku, Llama 3.2) para baixo custo e alta velocidade.
// Router retorna classificacao estruturada
{
"intent": "codigo" | "dados" | "texto" | "outro",
"confidence": 0.95,
"reasoning": "Usuario pediu para criar uma funcao JS"
}
Specialist Agent
Executa a tarefa com tools especificas. Use modelo forte (Sonnet, GPT-4o) para qualidade de output. ReAct loop interno.
// Specialist tem tools registradas
tools: [
{ name: "write_code", ... },
{ name: "run_tests", ... },
{ name: "read_file", ... }
]
Reviewer Agent
Valida output do Specialist. Retorna APROVADO ou REJEITADO com feedback estruturado. Se rejeitado, Specialist refaz.
// Reviewer retorna decisao estruturada
{
"approved": false,
"issues": [
{ "severity": "high", "description": "Sem error handling" },
{ "severity": "medium", "description": "Variaveis nao tipadas" }
],
"suggestions": ["Adicionar try/catch", "Usar TypeScript strict"]
}
Scaffold do Orchestrator (TypeScript)
async function orchestrate(userMessage: string) {
// 1. Router classifica a intencao
const classification = await router.classify(userMessage);
console.log(`[Router] Intent: ${classification.intent}
(${classification.confidence})`);
// 2. Se "outro", responde direto
if (classification.intent === "outro") {
return await directResponse(userMessage);
}
// 3. Specialist executa com retry loop
let result: string;
for (let attempt = 0; attempt < 3; attempt++) {
result = await specialist.execute(userMessage);
// 4. Reviewer valida
const review = await reviewer.validate(result);
if (review.approved) {
console.log(`[Reviewer] Aprovado na tentativa ${attempt + 1}`);
return result;
}
// 5. Se rejeitado, specialist refaz com feedback
console.log(`[Reviewer] Rejeitado: ${
review.issues.map(i => i.description).join(', ')}`);
userMessage += `\n\nFEEDBACK: ${review.suggestions.join('\n')}`;
}
return `Resultado apos 3 tentativas:\n${result}`;
}
Checklist de Validacao
💡 Dica
Construa e teste cada agente isoladamente antes de conecta-los. Primeiro o Router: teste com 10 mensagens diferentes e valide a acuracia. Depois o Specialist: teste com tarefas diretas. Por fim o Reviewer: teste com outputs bons e ruins. So integre quando cada peca funcionar sozinha.
Fazer
- ●Testar cada agente isolado antes de integrar
- ●Usar modelo leve no Router, forte no Specialist
- ●Implementar logging detalhado em cada etapa
- ●Medir custo total por request (soma de todos os agentes)
Evitar
- ●Integrar tudo sem testar cada peca individualmente
- ●Usar o mesmo modelo caro em todos os 3 agentes
- ●Reviewer que sempre aprova (validacao sem valor)
- ●Ignorar o caso "outro" no Router (mensagens sem classificacao)
📋 Resumo do Modulo 4.3
Multiplos agentes resolvem limitacoes de agente unico: context window, precisao de tool selection e impossibilidade de paralelismo.
4 padroes de orquestracao: sequential chain, parallel fan-out, router/dispatcher, hierarchical. Escolha baseado na tarefa.
Roles especializados (Executor, Analista, Revisor) com system prompts exclusivos e modelos diferentes por funcao.
Comunicacao estruturada: message passing, shared state ou event bus. Handoff com JSON padronizado e conversation_summary.
Frameworks: CrewAI (role-based), LangGraph (graph), Swarm (lightweight). Ou construa custom para sistemas simples.
Na pratica: sistema Router + Specialist + Reviewer funcional. Teste isolado, integre depois, metriques tudo.