Todo subagente bem construído sobe a mesma escada: começa com um papel claro, avança pelos passos numerados e chega até um formato de saída que qualquer orquestrador consegue ler. O que separa um agente fraco de um especialista confiável está nessa progressão.
🎭 Papel: "you are a senior…"
A primeira linha do corpo define a identidade do agente. Não é vaidade — é sinalização de domínio. O modelo calibra vocabulário, profundidade e tom com base nessa declaração. Uma frase de papel bem escrita vale mais que dez parágrafos de instrução vaga.
Anatomia de um papel efetivo
Um papel completo tem três partes: nível (senior / staff / principal), domínio (security engineer / code reviewer / technical writer) e contexto operacional (working in a production codebase / reviewing PRs / writing for developers).
✓ Papel efetivo
- ✓ "You are a senior security engineer reviewing production Python code for OWASP vulnerabilities."
- ✓ "You are a staff technical writer creating developer documentation for a REST API."
- ✓ Inclui domínio específico + contexto de uso
✗ Papel fraco
- ✗ "You are a helpful assistant." — genérico demais, zero sinalização de domínio
- ✗ "You are an expert." — sem especificar em quê
- ✗ Omitir o papel completamente
Dica: teste seu papel perguntando "que vocabulário um [seu papel] usaria?" — se a resposta mudar entre "helpful assistant" e "senior security engineer", o papel está fazendo trabalho real.
🔢 Passos numerados: "when invoked: 1…"
Depois do papel vêm os passos de execução — a sequência exata que o agente deve seguir toda vez que for acionado. Passos numerados transformam comportamento emergente (imprevisível) em comportamento reproduzível.
Por que numerar?
O modelo tende a seguir listas numeradas com mais fidelidade do que parágrafos de instrução. A numeração cria um contrato explícito de execução — pular um passo se torna visível para quem revisa o output.
📄 Formato de saída
O orquestrador vai ler o que o subagente retornar. Se o formato variar, o orquestrador precisa de lógica extra para parsear. Um formato de saída declarado no corpo do agente elimina essa variação e torna a integração trivial.
Seção ## Output Format no corpo
Declare o formato explicitamente em uma seção separada do corpo. Use Markdown para estrutura
e code fences para mostrar o esquema exato esperado.
Respond with a Markdown document containing:
- **Summary**: 1-2 sentences
- **Findings**: numbered list, each with severity (HIGH/MED/LOW)
- **Recommendation**: one actionable fix per finding
Do not include any other sections.
✓ Formato estruturado
- ✓ Seção dedicada
## Output Format - ✓ Campos nomeados com tipos (string, número, lista)
- ✓ Esquema JSON quando o orquestrador vai parsear automaticamente
✗ Formato livre
- ✗ Sem declaração de formato — output varia a cada invocação
- ✗ "Responda em prosa" para integrações automatizadas
- ✗ Campos opcionais sem valor padrão declarado
Dica: quando o subagente vai retornar dados para outro agente processar, prefira JSON a Markdown — é mais fácil de parsear programaticamente. Use Markdown quando a saída é para leitura humana direta.
🚫 O que NÃO fazer
Declarar restrições explícitas é tão importante quanto declarar o que fazer. O modelo sabe mais do que você quer que ele use — a seção de não-fazer delimita o escopo e evita que o agente "ajude demais" fora do seu papel.
Seção ## Constraints
Use uma seção ## Constraints ou
## Do not para listar
comportamentos proibidos. Cada restrição deve ser acionável — não vaga.
- Do not fix code — only report findings
- Do not comment on style — focus on security only
- Do not escalate to the user — return results to orchestrator
- Do not hallucinate CVE numbers — say "unverified" if unsure
⚠️ Restrições vazias não funcionam
"Do not do anything harmful" não é uma restrição acionável — o modelo já tem guardrails para isso. Restrições úteis são específicas ao domínio do agente: "do not suggest architectural changes" (para um code reviewer), "do not translate content" (para um qa-checker).
⚡ Um agente, uma tarefa
O maior erro de corpo de agente não é o que está lá — é o que está a mais. Agentes que fazem múltiplas coisas não fazem nenhuma delas bem. O teste é simples: se você conseguir colocar um "e também" no papel do agente, ele precisa ser dividido.
O teste do "e também"
Review the code for bugs,
and also suggest improvements,
and also update the docs,
and also check security.
security-reviewer: OWASP checks
doc-writer: update docs
refactor-advisor: suggest improvements
Dica prática: quando um agente demora muito, produz outputs grandes e difíceis de parsear, ou fica "confuso" entre modos de operação — é sinal de que ele está tentando fazer coisas demais. Divida no ponto do "e também".
🔧 O corpo invoca skills
Um subagente pode usar skills registradas no sistema — ele as invoca pelo nome, com um comando no corpo. Isso permite que o agente delegue partes do trabalho para skills especializadas sem precisar reimplementar comportamentos que já existem.
Como declarar no corpo
1. Read the target file(s) fully.
2. Use the `impeccable` skill to check prose quality.
3. Apply findings to the output.
4. Return a diff-style summary.
A instrução de uso da skill vai nos passos numerados — não no papel. O papel define quem o agente é; os passos definem o que ele usa.
✓ Delegação correta
- ✓ Skill invocada em passo específico e numerado
- ✓ Resultado da skill integrado ao output final
- ✓ Skill faz uma coisa; agente orquestra o fluxo
✗ Problemas comuns
- ✗ Invocar skill sem usar o resultado (desperdício de tokens)
- ✗ Chamar skill que faz exatamente o que o agente já faz
- ✗ Invocar múltiplas skills sem critério de ordem
🔁 Iterar com feedback
Um corpo de agente não nasce pronto. A primeira versão funciona 70% do tempo — os outros 30% revelam o que está faltando ou o que está errado. Iterar com feedback real é o que separa um agente "funciona às vezes" de um agente "confiável em produção".
Regra prática: se você precisou explicar ao orquestrador "o agente retornou X mas você deve ignorar a parte Y", isso é um sinal de que a correção deveria estar no corpo do agente, não na lógica do orquestrador.
Exemplo real: security-reviewer.md
Abaixo está um corpo completo de subagente de revisão de segurança. Cada seção demonstra um dos conceitos deste módulo aplicado em conjunto.
Por que este corpo funciona
- → Papel específico: seniority + domínio + escopo (Python/TS, produção)
- → Passos checklist: 5 passos que cobrem todo o fluxo sem ambiguidade
- → Formato declarado: 3 seções nomeadas com estrutura exata
- → Restrições acionáveis: 5 proibições específicas ao domínio de segurança
Conteúdo detalhado
Use quando você já tem um processo documentado e quer transformá-lo num agente.
Use para revisar agentes que "quase funcionam" e identificar o que falta.
Use quando um agente faz tudo mas não faz nada bem.
Tela simulada: invocando o security-reviewer
O orquestrador invocou o security-reviewer
num arquivo de autenticação. Veja como o corpo estruturado produz uma saída consistente e parseável.
Exercício: dividir um agente faz-tudo
Aplique o que você aprendeu neste módulo.
O agente problemático
Sua tarefa
- 1 Liste todas as responsabilidades separadas deste agente (aplique o teste do "e também")
- 2 Proponha 3 agentes especializados (nome + papel de uma linha cada)
- 3 Escreva o corpo completo de um dos agentes: papel + passos numerados + formato de saída + constraints
Critério de conclusão
- ✓ Você identificou ≥4 responsabilidades separadas no agente original
- ✓ Cada agente proposto passa no teste do "e também" — zero sobreposição de responsabilidade
- ✓ O corpo que você escreveu tem papel específico (nível + domínio + contexto)
- ✓ Os passos numerados cobrem o fluxo completo sem "e também"
- ✓ O formato de saída está declarado e seria parseável por outro agente
- ✓ As constraints são específicas ao domínio — não genéricas