O maestro não apenas dispara subagentes — ele os encadeia: o resultado de A alimenta B, que alimenta C. Este módulo ensina como projetar, depurar e escalar pipelines sequenciais sem deixar agentes conversando entre si.
O maestro coordena toda a cadeia. Agentes não se comunicam diretamente — cada um responde apenas ao maestro.
Encadear subagentes significa que o output de A vira o input de B, que por sua vez alimenta C — e o maestro orquestra cada passagem. Não existe conversa direta entre os agentes: a cadeia vive inteiramente no contexto do maestro.
O maestro extrai o resultado de A e o injeta como contexto no prompt de B.
A→B→C sempre nessa ordem; o maestro não pula etapas sem checar o output anterior.
Entre cada etapa o maestro pode validar, transformar ou abortar antes de continuar.
Skills são instruções carregadas no contexto do maestro — elas guiam o comportamento. Agents são sub-processos com janela própria — eles executam trabalho isolado. Em uma cadeia, a skill define o roteiro; os agents fazem as etapas.
✓ Skill: bom para
◎ Agent: bom para
💡 Dica prática
Use a skill como o maestro da cadeia — ela contém o prompt que lança cada agent em sequência e instrui o maestro a fazer o handoff de outputs entre eles.
Confundir skill com agent é o erro mais comum ao projetar cadeias. Entender a distinção evita inflar o contexto do maestro com trabalho que deveria viver em janela separada.
No Claude Code, um subagente não tem permissão de lançar outro subagente diretamente. Toda delegação passa pelo maestro. Isso não é limitação — é design intencional para garantir rastreabilidade, controle de custos e visibilidade do fluxo.
⛔ Padrão proibido
# ❌ NÃO funciona assim
Agent A → lança Agent B internamente
Agent B → lança Agent C internamente
# ✓ Como funciona de fato
Maestro → Agent A → retorna resultado
Maestro → Agent B (com output de A) → retorna resultado
Maestro → Agent C (com output de B) → retorna resultado✗ Risco de ignorar
✓ Benefício do modelo
A arquitetura é estrela (maestro no centro), não malha (todos conectados). Cada subagente é uma folha da árvore — nunca um nó intermediário com filhos próprios.
Cada subagente tem exatamente uma relação: com o maestro que o criou. Ele não conhece outros subagentes, não tem acesso ao contexto deles e não pode influenciá-los. É um especialista contratado para uma única missão — entrega o relatório e encerra.
Maestro monta o prompt
Inclui contexto necessário + saída da etapa anterior
Subagente abre janela própria
Contexto zerado — só vê o que o maestro enviou
Executa a tarefa
Pode usar ferramentas, ler arquivos, chamar APIs
Retorna resultado ao maestro
Texto limpo — relatório único, sem conversa
Janela encerra — contexto liberado
Não existe "depois" para o subagente
Entender a relação 1-para-1 evita tentar "fazer agentes colaborarem diretamente" — o que quebra silenciosamente, sem erro explícito.
A decisão de sequenciar é do maestro, não dos agentes. O maestro avalia: "B depende do output de A?" Se sim, é cadeia. Se não, pode ser paralelo. Essa decisão determina latência vs. custo.
🔗 Encadear quando:
⚡ Paralelizar quando:
💡 Regra do polegar
Se você consegue descrever a tarefa como "pesquise e depois redija e depois revise", é uma cadeia. Se é "pesquise e ao mesmo tempo colete exemplos", é paralelo.
Encadear quando poderia paralelizar desperdiça latência. Paralelizar quando há dependência produz resultados incorretos. Saber diferenciar é a habilidade central de orquestração.
Uma skill pode conter instruções que orientam o maestro a lançar subagentes em sequência.
A skill não executa nada — ela é carregada no contexto do maestro e guia cada chamada ao
Agent tool.
Lista as etapas, o que cada agente recebe e o que deve retornar.
Lança Agent A, captura output, monta prompt para Agent B, e assim por diante.
O mesmo roteiro pode ser invocado em qualquer projeto sem reescrever.
Colocar a lógica da cadeia numa skill torna o projeto auditável, versionável e portável. Sem esse padrão, a orquestração fica espalhada em prompts ad-hoc impossíveis de manter.
Uma cadeia de 3-5 agentes funciona bem com maestro humano. Acima disso, os outputs acumulados inflam o contexto e aumentam o custo de cada etapa. O passo natural é migrar para um workflow: ferramentas como n8n, LangGraph ou scripts Python que coordenam as chamadas de agente fora do contexto do LLM.
⚠ Sinais de alerta
✓ Solução: workflow
Saber quando parar de usar o maestro conversacional e migrar para workflow é a diferença entre um pipeline que funciona em produção e um que colapsa na terceira semana.
Skill que orquestra subagentes em cadeia pesquisa → rascunho → revisão
# pipeline-pesquisa
Orquestra 3 subagentes em cadeia para produzir um artigo pesquisado e revisado.
## Quando usar
Quando o usuário pedir "pesquise X e escreva um artigo" com qualidade alta.
## Etapas
### ETAPA 1 — Pesquisa (web-research-assistant)
Lançar um subagente `web-research-assistant` com o prompt:
```
Pesquise profundamente sobre: {TEMA}
Retorne:
- 5 fatos verificados com fonte
- 3 perspectivas contraditórias
- 1 dado quantitativo recente
Formato: markdown estruturado, máx. 400 palavras.
```
Capture o output como `PESQUISA`.
### ETAPA 2 — Rascunho (general-purpose)
Com `PESQUISA` em mãos, lançar `general-purpose`:
```
Com base nas pesquisas abaixo, escreva um artigo de 600 palavras sobre {TEMA}.
Tom: educativo, direto, sem jargão.
Use os fatos como base; cite as perspectivas contraditórias.
--- PESQUISA ---
{PESQUISA}
```
Capture como `RASCUNHO`.
### ETAPA 3 — Revisão (general-purpose)
Lançar `general-purpose` com o rascunho:
```
Revise o artigo abaixo para:
1. Precisão factual (corrija erros vs. pesquisa fornecida)
2. Clareza e fluidez
3. Tamanho: mantenha 500-650 palavras
Retorne APENAS o artigo final, sem comentários.
--- RASCUNHO ---
{RASCUNHO}
--- PESQUISA ORIGINAL ---
{PESQUISA}
```
## Output
Retorne ao usuário o artigo revisado com o cabeçalho:
`## Artigo: {TEMA} (pesquisado + revisado)`
## Regras
- Maestro NÃO encurta as etapas
- Se ETAPA 1 falhar, abortar com mensagem clara
- Agentes não se comunicam diretamente
Etapa 1
web-research-assistant coleta fatos com fontes
Etapa 2
general-purpose transforma pesquisa em rascunho
Etapa 3
general-purpose revisa e entrega o artigo final
Copie e adapte — cada prompt dispara uma cadeia de subagentes
Use a skill pipeline-pesquisa. Tema: "impacto dos LLMs no mercado de trabalho".
Encadeie: [1] web-research-assistant para coletar 5 fatos recentes com fonte,
[2] general-purpose para rascunhar artigo de 600 palavras,
[3] general-purpose para revisar precisão e fluência.
Retorne apenas o artigo final.Encadeie 3 subagentes:
1. Explore para mapear todos os arquivos em src/ e listar funções com mais de 50 linhas
2. general-purpose para refatorar as 3 maiores funções encontradas (recebe output do 1)
3. general-purpose para escrever testes unitários das funções refatoradas (recebe output do 2)
Cada agente recebe apenas o output do anterior — não o contexto todo.Monte uma cadeia de 3 subagentes para processar o relatório em /docs/relatorio.pdf:
[A] web-research-assistant: pesquise o contexto de mercado do tema do relatório
[B] general-purpose: sintetize relatório + pesquisa num resumo executivo de 1 página
[C] general-purpose: formate o resumo em HTML compatível com o design system AutomationsAI
Passe o output de cada etapa como contexto para a próxima.Maestro orquestrando uma cadeia de 3 subagentes no terminal
Modele uma cadeia de 3 etapas para um problema real seu
✓ Cadeia bem modelada
✗ Sinais de problema
💡 Dica de auto-avaliação
Passe seu modelo pelo teste do "e se A falhar?": se o maestro consegue detectar e abortar antes de lançar B, a cadeia está bem desenhada. Se não, falta um ponto de controle.