Criar Agente
Propósito
Projetar agentes de IA com uma disciplina de escopo primeiro. Antes de escrever qualquer prompt, configuração ou vinculação de ferramenta, você deve passar por uma entrevista de escopo estruturada. A profundidade da entrevista depende da complexidade do agente sendo projetado.
Esta não é uma habilidade de escrever prompts. É uma habilidade de validação de escopo. A saída é um Agent Spec validado — um blueprint que outra IA ou humano pode usar para construir o agente corretamente.
Cada spec de agente define 8 dimensões:
Arquétipo → Personalidade → Capacidades → E/S → Ecossistema → Memória → Ciclo de Vida → Risco/Métricas
Regras de Ferro
-
Escopo antes da construção — Nenhum código, nenhum prompt, nenhuma configuração de ferramenta até que o escopo seja validado. Zero exceções.
Autoridade de Correção: Usado apenas para rascunho/suposição de spec — corrija suposições no spec que o usuário errou (dep ausente, contradição, risco de segurança) imediatamente, sem precisar perguntar. Apenas informe o que ajustou e por quê. Não edite arquivos, configurações, ferramentas ou workflows reais sem obter aprovação. Peça aprovação antes se a solução correta exigir mudar de ferramenta ou alterar um workflow existente — mas se o senso comum pode corrigir o spec, faça isso.
-
Profundidade mínima suficiente — Padrão: Rápido. Promova para Padrão/Profundo/ Crítico apenas quando sinais explícitos aparecerem. Não comece no Padrão.
-
Inferir primeiro, perguntar depois — Antes de fazer uma pergunta, tente inferir a resposta a partir do contexto, codebase, agentes existentes e o que o usuário já disse. Pergunte apenas sobre o que permanece genuinamente incerto.
-
Codebase primeiro — Se a resposta para uma pergunta existe em configurações, docs ou agentes existentes — vá encontrá-la. Não pergunte. Exceção Greenfield: Se não existir codebase (sem index.md, AGENTS.md, opencode.jsonc ou agentes existentes), pule a varredura do codebase e vá diretamente para a entrevista.
-
Minimize idas e vindas — Infira o spec → apresente rascunho → deixe o usuário marcar. Pergunte um de cada vez apenas para lacunas genuínas que o rascunho não consegue resolver. Nunca despeje 10 perguntas de uma vez.
-
Recomende, não seja aberto — Toda pergunta deve incluir uma resposta recomendada. Dê algo para reagir.
-
Spec deve ser aprovado — Nunca construa até que o Agent Spec seja explicitamente aprovado. Para a camada Rápida, a confirmação do usuário do spec inferido conta como aprovação. Documente como
Status: Aprovado via Rápido. -
Pare no sinal — Quando o usuário disser "chega" ou "pare" — pare. Não discuta, não insista por mais.
-
Produza um Agent Spec — Toda sessão produz um spec validado, mesmo na camada Rápida.
Sistema de Arquétipos de Agente
Agentes seguem padrões baseados em seu arquétipo. Use esta tabela para escolher o arquétipo certo e entender em quais domínios de entrevista focar ou pular.
Catálogo de Arquétipos
| # | Arquétipo | Propósito Principal | Personalidade Padrão | Ferramentas Típicas | Camada Sugerida |
|---|---|---|---|---|---|
| 🛠️ | Sistema | Automatizar, configurar, manter | Prático, conciso, direto | CLI, sistema de arquivos, Docker, git | Rápido → Padrão |
| 🎨 | Criativo | Design, visual, movimento | Expressivo, detalhista | Tailwind, GSAP, APIs de imagem | Rápido → Padrão |
| 💻 | Desenvolvedor | Código, arquitetura, depuração | Técnico, preciso, minucioso | MCPs, linters, executores de teste | Rápido → Profundo |
| 📝 | Escriba | Documentar, escrever, organizar | Claro, estruturado, paciente | Obsidian, markdown, pesquisa | Rápido |
| 🔬 | Especialista | Domínio único e profundo | Autoritário, meticuloso | CLI/MCP específico de domínio | Rápido → Profundo |
| 🎯 | Orquestrador | Coordenar, delegar, gerenciar | Sistemático, orientado a processos | Lista de agentes, protocolo de handoff | Rápido → Crítico |
| 🔍 | Pesquisador | Pesquisar, analisar, sintetizar | Curioso, analítico, minucioso | Exa, Firecrawl, ferramentas web | Rápido |
| 🎮 | Jogo | Comportamento específico de jogo | Lúdico, adaptável | API de jogo, framework de bot | Rápido → Profundo |
Lista de Minimização de Arquétipo
Não é "pular", mas informar qual domínio deve ser curto ou pulável se óbvio.
Existem 3 níveis:
- Aprofundado — Pergunte tudo
- Breve — Faça apenas 1-2 perguntas e resuma
- Pular se óbvio — Não pergunte se o senso comum pode determinar (ex: Escriba → Memória = apenas sessão)
| Arquétipo | Breve | Pular se óbvio | Aprofundado |
|---|---|---|---|
| Sistema | Identidade, E/S | Memória | Capacidades, Ecossistema |
| Criativo | Risco/Métricas, Ciclo de Vida | Memória | Identidade, E/S, Personalidade |
| Desenvolvedor | Ciclo de Vida | Identidade | Capacidades, Ecossistema, E/S |
| Escriba | Ecossistema | Risco/Métricas, Memória | Identidade, E/S |
| Especialista | E/S, Ciclo de Vida | — | Capacidades, Risco/Métricas |
| Orquestrador | — | — | Todos os domínios |
| Pesquisador | Ciclo de Vida, Personalidade | Memória | Capacidades, E/S, Identidade |
| Jogo | Ecossistema | Risco/Métricas | Capacidades, E/S, Personalidade |
Desenvolvedor + Identidade: Breve não é Pular — a identidade (frontmatter) ainda deve existir porque determina quando o agente é chamado. Apenas mantenha curto (1-2 frases).
Seleção de Arquétipo
Ao entrevistar, recomende um arquétipo com base no propósito do agente. Se vários arquétipos se encaixam, escolha o dominante e anote os secundários.
Exemplo: "Isso parece um arquétipo Desenvolvedor com alguma sobreposição de Especialista.
Pela lista de minimização: Ciclo de Vida = breve, Identidade = breve (frontmatter
apenas), foque aprofundado em Capacidades + Ecossistema."
Sistema de Camadas de Profundidade
Nem todo agente precisa da mesma profundidade. Esta skill define 4 camadas. Padrão: Rápido. Comece leve, escale apenas quando sinais exigirem.
Camada 1 — Rápido (inferir → confirmar → construir, pergunte mais se incerto)
│ ← PADRÃO
Camada 2 — Padrão (Apresentar rascunho → usuário marca → aprovar)
│
Camada 3 — Profundo (Padrão + Mapa de Ecossistema + Rastreio de Dependências)
│
Camada 4 — Crítico (Profundo + Modelo de Risco + Modelo de Custo + Portões de Segurança)
Seleção de Camada
| Sinal | Rápido | Padrão | Profundo | Crítico |
|---|---|---|---|---|
| Agente é novo ou modificado (1-2 caps), escopo claro | ✅ | — | — | — |
| Agente existente, pequena alteração | ✅ | — | — | — |
| Novo agente, propósito único, sem dependências | — | ✅ | — | — |
| Novo agente, 1-2 integrações externas | — | ✅ | ✅ | — |
| Agente em ecossistema multi-agente | — | — | ✅ | ✅ |
| Lida com pagamento / autenticação / PII | — | — | — | ✅ |
| Implantado em produção | — | — | — | ✅ |
| Alto custo de token por chamada | — | — | — | ✅ |
| Implicações de segurança ou conformidade | — | — | — | ✅ |
| Arquétipo = Orquestrador | — | — | — | ✅ |
| Arquétipo = Especialista | — | — | ✅ | — |
Padrão: Rápido. Promova apenas quando sinais explícitos estiverem presentes.
Regra de escalada: Se durante uma entrevista de camada inferior você descobrir sinais que justificam uma camada superior, promova explicitamente:
Nota de promoção:
Gatilho: [o que você encontrou]
Evidência: [onde encontrou]
Risco de permanecer: [por que a camada inferior é insegura]
Camada 1 — Rápido
Para agentes simples e pequenas alterações. Infira o spec do contexto, confirme com o usuário, construa. Sem entrevista completa, sem portão de aprovação separado.
Não pense demais nesta camada. Se incerto, ainda comece aqui — a complexidade surgirá durante a inferência. Promova se sinais aparecerem.
Critérios de Entrada
- Agente é novo (1-2 capacidades) ou existente com pequena modificação.
- Nenhuma integração externa além do que já existe.
- Nenhuma coordenação multi-agente.
- Nenhum risco de segurança, custo ou conformidade.
- Requisitos são claros o suficiente para que uma entrevista de 8 domínios pareceria engenharia excessiva.
Processo
1. Inferir spec do contexto ← Leia do que o usuário disse + codebase + agentes existentes
2. Apresentar mini-spec ← Use formato fixo abaixo
3. Usuário marca ← "Diga onde alterar"
Se a marcação for trivial (1-2 palavras, pequena correção de formato)
→ Pode construir
Se a marcação for estrutural (adicionar cap, mudar ferramenta, alterar limite)
→ apresente mini-spec revisado → usuário confirma → Construa
4. Construir
Formato do Mini-Spec (Fixo)
## Quick Spec: [Nome]
Função: [Uma frase — "O que faz, para quem, para obter o quê"]
Capacidades:
- [ação 1]
- [ação 2]
Limites:
- [o que não pode fazer]
Autoridade: [Somente leitura / Sugerir / Modificar no escopo / Executar / Autônomo]
Ferramentas: [ferramenta / MCP / nenhuma necessária]
Aprovação: [Confirmado via Rápido / Revisado e Confirmado]
Use o arquivo templates/quick-spec.md como template real.
Não encurte ou pule estes campos — se um campo for óbvio, escreva "—" (não pergunte ao usuário).
Se modificar agente existente → use o mesmo formato, mas mostre apenas os campos alterados.
Exemplo
Usuário: "Quero um agente que resuma meus e-mails"
Inferir:
Arquétipo: Escriba
Capacidade: ler e-mail → resumo em tópicos
Ferramentas: Gmail MCP (já existente)
Ecossistema: está com o steward
Apresentar mini-spec:
## Quick Spec: resumidor-email
Função: Ler Gmail → resumir em tópicos para o Mike toda manhã
Capacidades:
- Ler e-mails do Gmail MCP → resumir em tópicos
- Separar por remetente / assunto
Limites:
- Não responder e-mails, não excluir e-mails
Autoridade: Somente leitura
Ferramentas: Gmail MCP (já existente)
Aprovação: —
"Português/Inglês? Todos os e-mails ou apenas de tópicos específicos?"
Usuário: "Português, todos, sem log"
(marcação trivial — Enviar para Construir)
Construir.
## Quick Spec: resumidor-email
...
Autoridade: Somente leitura
Aprovação: Confirmado via Rápido
Camada 2 — Padrão
Para novos agentes e mudanças significativas. Promova para Padrão quando Rápido for insuficiente (integrações complexas, impacto no ecossistema ou escopo pouco claro).
Processo
1. Portão de Intenção → Reformule, identifique arquétipo, usuário + objetivo + restrição
2. Varredura do Codebase → Leia index.md, opencode.jsonc, AGENTS.md, agentes existentes
(se não houver → greenfield: pule, vá direto para apresentar rascunho)
3. Correspondência de Arquétipo → Selecione arquétipo, aplique lista de minimização
4. Apresentar Rascunho → Infira spec completo do contexto conhecido → apresente rascunho de 1 página
Pergunte apenas sobre incertezas (não uma de cada vez)
5. Usuário Marca → Usuário edita / adiciona / remove do rascunho
6. Iterar (se necessário) → Se houver lacuna → apresente rascunho revisado
7. Propor Spec → Agent Spec completo (veja templates/agent-spec.md)
8. Portão de Aprovação → Usuário aprova antes de construir
Entrevista de Escopo (8 Domínios)
Para camada Rápida: pule tudo — infira + confirme desde o início
Para Padrão+:
- Infira rascunho do spec do contexto existente → apresente rascunho de uma página ao usuário
- Usuário lê e marca (edita/adiciona/remove)
- Use a lista de verificação abaixo para verificar se algo foi esquecido — pergunte apenas o que o rascunho não cobre
- Aplique a Lista de Minimização de Arquétipo — breve / pular se óbvio / aprofundado de acordo com o arquétipo
Não pergunte item por item da lista de verificação — apresente rascunho primeiro, pergunte apenas lacunas
Domínio 1: Identidade e Propósito
-
Nome — como o agente se chama? (proponha se sem nome)
-
Arquétipo — qual arquétipo do catálogo?
-
Função — uma frase clara: "Este agente [faz X] para [usuário Y] para que [Z]."
-
Persona —
Campo O quê Exemplo Tom formal / casual / técnico / lúdico / autoritário / acolhedor "técnico, mas acessível" Frase de exemplo Fala real do agente "Deixe-me verificar a configuração... Encontrei. O problema está na linha 42." Sempre recomende uma persona.
"Sugiro um tom técnico, mas acessível — preciso nos fatos, relaxado na conversa." -
Contexto conhecido — o que ele precisa saber antes de trabalhar?
-
Trabalho mais restrito — qual é a menor definição útil de sua função?
Domínio 2: Capacidades e Limites
-
Capacidades — ações principais, ranqueadas por prioridade. Cada capacidade inclui:
- Descrição (1 frase)
- Gatilho (como essa capacidade é invocada?)
- Saída esperada (como é o sucesso?)
- Modo de falha (o que acontece se não funcionar?)
-
Limites — lista explícita do que ele nunca deve fazer. Formate cada um como uma Regra Crítica com cenário:
Regra: Nunca modificar arquivos fora do diretório do projeto. Cenário: Usuário pede "corrigir minhas configurações da área de trabalho" — agente tem acesso ao sistema de arquivos. Consequência: Recusar educadamente, explicar limite de escopo. -
Mapeamento de Ferramentas — para cada capacidade, determine quais ferramentas são necessárias. Faça isso após capacidades e limites estarem claros.
Capacidade: "Pesquisar documentação" ↓ Pesquisar codebase por ferramentas existentes → encontrou Exa MCP (pesquisa web) ↓ Propor: "Recuperação de conhecimento via Exa MCP (já configurado). Se Exa estiver indisponível, fallback para pesquisa web via Firecrawl."Regra: Proponha uma ferramenta específica se já existir uma no codebase. Apenas proponha uma categoria quando nenhuma ferramenta existente se encaixar. Mas: Se a ferramenta existente não corresponder à necessidade (ex: precisa de pesquisa local em docs, mas só tem Exa para pesquisa web) — não force o encaixe. Marque como ajuste parcial ou lacuna e proponha a categoria mais adequada.
✅ "Usa Exa MCP para pesquisa web — já configurado" ✅ "Exa MCP existe para pesquisa web, mas pesquisa em log de trabalho deve usar Obsidian + grep — é um ajuste parcial para pesquisa externa" ✅ "Nenhum vector DB existente encontrado. Precisa de uma ferramenta de busca semântica como Chroma ou Qdrant." ❌ "Precisa de uma ferramenta de recuperação de conhecimento" (vago — Exa existe, use-a) ❌ "Usa Exa MCP para tudo" (forçar encaixe — Exa não é adequado para pesquisa local)Categorias de ferramentas (referência para lacunas):
Recuperação de conhecimento → pesquisa, vector DBs, armazenamento de documentos, web scraping Execução de código → sandboxes, interpretadores, compiladores, linters Comunicação → e-mail, mensagens, notificações, webhooks Operações de sistema → E/S de arquivos, gerenciamento de processos, rede, registro Processamento de dados → ETL, transformação, validação, armazenamento Visual/criativo → geração de imagens, mecanismos de layout, animação Monitoramento → logs, métricas, rastreamento, alertas IA/LLM → APIs de modelo, embeddings, pipelines RAG, vector DBs Testes → executores de teste, cobertura, mocking, navegadores E2E -
Habilidades — quais habilidades o agente deve ter?
...
[truncado para tradução]