🧠 Role + Tools + Owned Files + Handoff
Toda definição de agent em qualquer runtime tem 4 conceitos: papel, tools permitidas, arquivos que possui, e quem recebe seu output. Pensar nesse contrato te dá portabilidade.
📌 O contrato
Mude só sintaxe.
- •Role = system prompt
- •Tools = allowlist
- •Owned files = território
- •Handoff = mailbox/return
📋 Mapeamento Claude/Codex/Gemini
Cada conceito tem nome em cada runtime. Tabela mental de tradução acelera migração.
📊 Equivalências
- Definição: frontmatter (Claude) / TOML (Codex) / YAML (Gemini)
- Tools: array em todos
- Mailbox: SendMessage (Claude Teams) / N/A em subagents
- Plan mode: Claude Code only
🔄 Lab: PR review nos 3 runtimes
Implemente o squad de PR review (security + perf + tests) nos 3 runtimes. Lado a lado solidifica a abstração.
Setup Claude
subagents em .claude/agents/
3 .md com frontmatter; spawn como teammates
Setup Codex
.codex/agents/*.toml
3 TOML com developer_instructions
Setup Gemini
.gemini/agents/*.md
3 .md com YAML; @-mention para forçar
Run
Mesmo PR nos 3
Compare findings
Aprenda
Diff entre runtimes
Mesmo squad, sintaxe diferente
🎚️ Quando trocar de runtime
Claude Code Teams quando precisa de mailbox; Codex quando quer Symphony/Linear; Gemini quando integra com Google. Não brigue com o runtime.
✓ Claude Code Teams
- ✓Mailbox real
- ✓Plan mode embutido
- ✓Hooks ricos
- ✓Subagent definitions
✓ Codex / Gemini
- ✗Symphony (Codex)
- ✗Google Workspace (Gemini)
- ✗Sandbox CI (Codex)
- ✗Browser_agent (Gemini)
📤 Exportar prompts entre runtimes
Um prompt-base + 3 wrappers (frontmatter, TOML, YAML) é o que você quer manter. Source of truth = .md; wrappers em geradores.
📌 Padrão recomendado
1 fonte, N saídas.
- •Prompt-base em prompts/X.md
- •Geradores produzem .toml e .yaml
- •CI valida que estão sincronizados
- •Mude 1 vez, propaga
📚 Frameworks acima dos CLIs
Quando complexidade cresce (cycles, branching, observabilidade), framework Python pode substituir o CLI. Trade-off de produtividade vs controle.
📊 Quando cada um
- CrewAI: papéis, prototipo rápido (2-3 dias)
- AutoGen / AG2: GroupChat, debate adversarial
- LangGraph: grafo, cycles, observabilidade prod
- Agents SDK: pipeline declarativo + Codex MCP
📌 Resumo do Módulo
Próximo módulo:
5.4 — Capstone: NeuroFlow Pro