Modulo 1.4: Papeis e Especializacao de Agentes

1

👔 O Orquestrador: cerebro do swarm

O orquestrador e o agente mais importante de qualquer swarm. Ele e o cerebro central que recebe a tarefa do usuario, analisa a complexidade, cria um plano de execucao, seleciona os agentes adequados, delega subtarefas, monitora o progresso e garante que o resultado final atenda ao objetivo original. Sem um bom orquestrador, um swarm com os melhores agentes especializados do mundo seria apenas caos — como uma orquestra sem maestro, onde cada musico toca no seu tempo e tom.

Em sistemas reais, o orquestrador recebe nomes diferentes: no oh-my-openagent (OMO) e o Sisyphus — nomeado pelo mito grego porque "empurra a pedra morro acima" sem desistir, iterando ate a tarefa estar completa. No OpenCode Swarm e o Architect, que projeta a solucao e coordena a cadeia de agentes. Em frameworks como CrewAI e o Manager Agent, e no LangGraph e o Supervisor Node. Independente do nome, o orquestrador sempre usa o modelo mais potente disponivel (Claude Opus, GPT-5.3) porque precisa de raciocinio sofisticado para decompor problemas e tomar decisoes de delegacao.

💡 Responsabilidades do Orquestrador

O orquestrador acumula funcoes criticas que nenhum outro agente pode assumir:

• Analise de tarefa: Entende o pedido do usuario, identifica ambiguidades, formula perguntas de clarificacao quando necessario
• Decomposicao e planejamento: Divide a tarefa em subtarefas atomicas que podem ser delegadas a agentes especializados
• Delegacao inteligente: Seleciona qual agente e o mais adequado para cada subtarefa com base em capacidades e disponibilidade
• Monitoramento e correcao: Acompanha o progresso, detecta falhas, pede retrabalho quando necessario e nao para ate o objetivo ser atingido

📊 Orquestradores em sistemas reais

Sisyphus (OMO): "Nao para ate terminar" — itera automaticamente, corrigindo erros e ajustando o plano. Usa o modelo mais potente disponivel
Architect (OpenCode Swarm): Cria design decisions documentadas, projeta a arquitetura e coordena o pipeline de 8 agentes
Custo do orquestrador: Tipicamente 30-40% do custo total de tokens do swarm porque precisa manter contexto amplo e fazer raciocinio complexo
Regra de ouro: Use o melhor modelo disponivel para o orquestrador — economizar aqui degrada todo o swarm

2

📐 O Planejador: antes de executar

O agente planejador e responsavel por transformar requisitos vagos em planos de execucao detalhados. Enquanto o orquestrador decide o que precisa ser feito em alto nivel, o planejador detalha como — definindo a ordem das tarefas, as dependencias entre elas, os criterios de aceitacao e os riscos potenciais. Em muitos swarms, o planejador atua antes de qualquer agente executor, garantindo que o trabalho comece com direcao clara e objetivos mensuraveis.

No OMO, o planejador se chama Prometheus — nomeado pelo tita que deu fogo (conhecimento) a humanidade. O Prometheus faz algo que a maioria dos agentes nao faz: antes de planejar, ele faz perguntas de descoberta (discovery questions) ao usuario para entender restricoes, preferencias e contexto que nao estao explicitos no pedido original. Depois, ele produz um spec file (arquivo de especificacao) detalhado que serve como contrato entre o planejador e os executores. Esse spec file inclui objetivos, escopo, tarefas numeradas, criterios de aceitacao e riscos identificados.

💡 Processo de Planejamento

O planejador segue um fluxo estruturado que transforma ambiguidade em clareza:

• Discovery questions: Antes de planejar, o agente faz perguntas ao usuario — "Qual framework usar?", "Precisa de autenticacao?", "Qual banco de dados?" — reduzindo ambiguidades
• Analise de codebase: O planejador usa dados do Explorer para entender o estado atual do projeto — padroes existentes, tecnologias usadas, convencoes do time
• Spec file: Documento estruturado com objetivo, escopo, lista de tarefas numeradas, dependencias entre tarefas e criterios de aceitacao
• Validacao do plano: O spec file e revisado (por um Critic ou pelo usuario) antes de qualquer execucao — plano ruim detectado cedo economiza muito retrabalho

📊 Impacto do planejamento no swarm

Prometheus (OMO): Gera 5-10 discovery questions e produz spec files de 200-500 linhas que guiam toda a execucao posterior
Taxa de sucesso: Swarms com fase de planejamento explicita tem taxa de sucesso 40-60% maior do que swarms que pula direto para a execucao
Custo do planejamento: Tipicamente 10-15% do custo total de tokens, mas evita retrabalho que custaria 3-5x mais
"Measure twice, cut once": Planejar bem antes de executar e o principio mais impactante na qualidade de qualquer swarm

3

💻 O Executor: mao na massa

O agente executor (ou coder) e onde o trabalho concreto acontece. Enquanto o orquestrador planeja e o planejador especifica, o executor escreve codigo, cria arquivos, modifica configuracoes e implementa solucoes reais. Ele recebe uma tarefa atomica bem definida — "crie o endpoint POST /api/users com validacao de email" — e a implementa com foco total, sem se preocupar com o contexto macro do projeto. Essa focalizacao e intencional: quanto mais restrita a tarefa, maior a qualidade do output.

No OMO, o executor se chama Hephaestus — o deus grego da forja e do artesanato, que constroi coisas concretas. Multiplas instancias de Hephaestus podem rodar em paralelo, cada uma trabalhando em uma tarefa atomica diferente em sua zona segura de arquivos. No OpenCode Swarm, o papel equivalente e o Coder, que recebe a especificacao do Architect e implementa exatamente o que foi pedido. Uma pratica comum e usar modelos de custo medio para executores (Claude Sonnet, GPT-4o) porque as tarefas sao bem definidas e nao exigem o raciocinio sofisticado de um Opus ou GPT-5.3.

💡 Principios do Agente Executor

O executor eficaz segue principios que maximizam qualidade e minimizam conflitos:

• Tarefas atomicas: Cada tarefa deve ser pequena o suficiente para ser completada em uma unica sessao sem perda de contexto — idealmente 1-3 arquivos modificados
• Contexto minimo: O executor recebe apenas as informacoes necessarias para sua tarefa especifica — nada mais. Isso mantem o foco e reduz custos de tokens
• Zona segura: Cada executor trabalha em arquivos designados exclusivamente para ele, evitando conflitos com outros executores paralelos
• Output estruturado: O executor retorna nao apenas o codigo, mas tambem metadados sobre o que fez — arquivos modificados, decisoes tomadas, dependencias criadas

📊 Executores na pratica

Hephaestus (OMO): Multiplas instancias paralelas por categoria (Frontend, Backend, Database). Cada uma implementa tarefas atomicas do spec file
Coder (OpenCode Swarm): Recebe especificacao do Architect e implementa em sequencia. Resultado passa por Reviewer antes de avancar
Modelo recomendado: Claude Sonnet ou GPT-4o — custo-beneficio ideal para tarefas bem definidas que nao exigem raciocinio de fronteira
Produtividade: Um executor focado em tarefa atomica produz codigo 2-3x mais consistente do que um agente generico tentando fazer tudo

4

🔍 O Revisor: olhar critico

O agente revisor (reviewer ou critic) e o guardiao da qualidade do swarm. Ele recebe o output do executor e avalia com olhar critico: o codigo esta correto? Segue os padroes do projeto? Tem vulnerabilidades de seguranca? E eficiente? Trata erros adequadamente? O revisor nao implementa — ele julga, critica e, quando necessario, rejeita o trabalho com feedback especifico sobre o que precisa ser corrigido. A separacao entre quem cria e quem revisa e um dos principios mais poderosos dos swarms.

Uma tecnica fundamental e usar um modelo diferente do executor para a revisao — o chamado padrao anti-blindspot. Se o Coder usa Claude Sonnet, o Reviewer usa GPT-4o (ou vice-versa). A logica e que modelos diferentes, treinados com dados diferentes, capturam tipos diferentes de erros. Um modelo pode ter pontos cegos que outro nao tem. O resultado da revisao e binario e claro: APPROVED (o codigo avanca para a proxima etapa) ou NEEDS_REVISION (o codigo retorna ao executor com lista de correcoes). Esse gate de qualidade impede que codigo ruim avance no pipeline.

💡 Mecanismo de Revisao

O revisor opera com criterios explicitos e resultado binario que nao deixa margem para ambiguidade:

• Anti-blindspot: Usar provider diferente do executor (Claude revisa GPT, GPT revisa Claude) — dados de treinamento distintos capturam erros complementares
• Checklist de revisao: Corretude logica, seguranca, performance, tratamento de erros, aderencia ao plano original, convencoes do projeto
• APPROVED / NEEDS_REVISION: Resultado binario — ou o codigo avanca, ou retorna ao executor com lista detalhada de correcoes necessarias
• Feedback construtivo: O revisor nao apenas aponta erros — ele explica por que e como corrigir, fornecendo contexto que ajuda o executor a melhorar

📊 Impacto da revisao automatica

Reducao de bugs: Swarms com revisao automatica detectam 60-80% mais defeitos do que swarms sem revisor dedicado
Anti-blindspot em numeros: Cross-provider review detecta 15-25% mais erros do que same-provider review — cada modelo tem pontos cegos diferentes
Ciclos de correcao: Em media, 30-40% dos outputs do executor sao rejeitados na primeira revisao e aprovados na segunda apos correcoes
ROI claro: O custo de um agente revisor (10-15% do total de tokens) evita bugs que custariam 5-10x mais para corrigir em producao

5

🧪 O Testador: prova que funciona

O agente testador (Test Engineer) e o que garante que o codigo nao apenas parece correto mas realmente funciona. Enquanto o revisor avalia qualidade estatica (lendo o codigo), o testador valida dinamicamente — escrevendo e executando testes que provam que o codigo se comporta como esperado. Isso inclui testes unitarios que verificam funcoes individuais, testes de integracao que validam como componentes interagem e, crucialmente, testes adversariais que tentam deliberadamente quebrar o codigo com inputs inesperados.

A contribuicao mais valiosa do testador e a capacidade de gerar testes adversariais — cenarios que o executor nunca pensaria em cobrir. O que acontece se o usuario enviar um campo vazio? E se o email tiver 500 caracteres? E se duas requisicoes chegarem ao mesmo tempo? O testador pensa como um adversario que quer quebrar o sistema. Em swarms maduros, o testador tambem valida que as correcoes do executor nao introduziram regressoes — ou seja, que ao corrigir um bug, outros bugs nao foram criados. Esse ciclo de codigo → revisao → teste → correcao e o que produz software de qualidade profissional.

💡 Tipos de Teste no Swarm

O agente testador gera e executa diferentes categorias de testes para cobertura completa:

• Testes unitarios: Validam funcoes e metodos individuais isoladamente — entrada X deve produzir saida Y. Rapidos e precisos para detectar bugs logicos
• Testes de integracao: Verificam como componentes interagem — o endpoint chama o servico que consulta o banco corretamente?
• Testes adversariais: Inputs maliciosos, edge cases extremos, concorrencia, campos vazios, payloads enormes — tentam deliberadamente quebrar o sistema
• Testes de regressao: Verificam que correcoes nao quebraram funcionalidades existentes — rodam a suite completa apos cada mudanca

📊 Testes em swarms reais

Cobertura tipica: Agentes testadores bem configurados geram 80-95% de cobertura de codigo em funcoes criticas
Testes adversariais: Detectam 20-30% mais vulnerabilidades do que testes unitarios tradicionais — essenciais para seguranca
Ciclo de feedback: Quando testes falham, o resultado volta ao executor com o stack trace e sugestoes de correcao — fechando o loop automaticamente
Modelo recomendado: Modelos de custo medio funcionam bem para geracao de testes — a tarefa e estruturada e nao exige raciocinio de fronteira

6

🔎 Agentes de suporte: explorador, pesquisador, visual

Alem dos papeis centrais (orquestrador, planejador, executor, revisor, testador), swarms eficazes contam com agentes de suporte que fornecem contexto e inteligencia aos demais. Esses agentes nao produzem codigo diretamente, mas o trabalho que fazem melhora dramaticamente a qualidade de tudo que vem depois. O mais fundamental e o Explorer — um agente read-only que escaneia toda a codebase, identifica padroes, mapeia dependencias e cria um "mapa" do projeto que outros agentes consultam. Sem o Explorer, cada agente teria que redescobrir a estrutura do projeto sozinho.

O Librarian (pesquisador) vai alem da codebase e busca informacoes externas: documentacao de APIs, artigos tecnicos, exemplos de implementacao, melhores praticas. Quando o executor precisa integrar uma API que nunca usou, o Librarian ja preparou um resumo com os endpoints relevantes, formatos de resposta e exemplos funcionais. O Multimodal Looker traz uma capacidade unica: analise visual. Ele pode analisar screenshots de UI, diagramas de arquitetura, wireframes de design e extrair informacoes que agentes baseados apenas em texto nao conseguem captar — como "o botao de login esta desalinhado 3px a esquerda".

💡 Papeis de Suporte

Cada agente de suporte fornece um tipo especifico de inteligencia que melhora o trabalho dos agentes centrais:

• Explorer (read-only): Escaneia codebase, identifica padroes, mapeia dependencias, lista arquivos relevantes. Nunca modifica nada — opera exclusivamente em modo leitura
• Librarian (pesquisador): Busca documentacao externa, exemplos de implementacao, artigos tecnicos e melhores praticas. Cria resumos contextualizados para os executores
• Multimodal Looker (visual): Analisa imagens — screenshots de UI, diagramas, wireframes. Extrai informacoes visuais que agentes de texto nao captam
• SME — Subject Matter Expert: Especialista de dominio que fornece contexto profundo sobre a area de negocio — regulamentacoes, padroes da industria, terminologia especifica

📊 Impacto dos agentes de suporte

Explorer: Reduz o tempo de "entendimento do projeto" de 5-10 minutos por agente para menos de 1 minuto — o mapa ja esta pronto
Librarian: Evita que executores "inventem" integracoes com APIs — pesquisa previa reduz erros de integracao em 50-70%
Multimodal Looker: Essencial para tarefas de frontend — detecta discrepancias visuais entre design e implementacao que revisao de codigo puro nao pega
Custo baixo: Agentes de suporte podem usar modelos gratuitos ou de baixo custo porque suas tarefas sao predominantemente de leitura e pesquisa

👔 Papeis e Especializacao de Agentes