📁 Onde definir agents
Cada agent é um arquivo TOML em ~/.codex/agents/ (user) ou .codex/agents/ (projeto). Mesma ideia do Claude Code: declarativo + reusável.
📌 Anatomia mínima
Campos obrigatórios.
- •name = "security-reviewer"
- •description = "Audits auth code for vulnerabilities"
- •developer_instructions = '''...'''
📊 Campos opcionais
- model = "o3"
- sandbox_mode = "workspace-write"
- mcp_servers = ["linear", "github"]
- nickname_candidates = ["Athena", "Hermes"]
⚙️ Config global [agents]
Seção [agents] no config global controla concorrência. Sem isso, swarms descontrolados.
📊 Defaults importantes
- max_threads = 6 (paralelismo)
- max_depth = 1 (recursão)
- job_max_runtime_seconds = ?
- Threads = N de agents simultâneos
- Depth = quanto pode recursar
💡 Valor seguro
max_threads = 4-6 cobre 90% dos casos. Aumente só com motivo claro.
🪪 Nicknames e display
Array nickname_candidates dá nomes legíveis às múltiplas instâncias do mesmo agent. Sem isso, instâncias ficam 'agent-1, agent-2...'.
📌 Use /agent
Comando para alternar threads.
- •
/agentlista threads ativas - •Selecione por número ou nickname
- •Inspect progress
- •Mensagem direta
💡 Nicknames temáticos
Athena, Hermes, Apollo — facilitam memória vs 'agent-1, agent-2'.
📊 spawn_agents_on_csv
Tool experimental que processa cada linha de CSV com 1 worker e exporta resultados consolidados. Casos como 'auditar 200 PRs' ficam triviais.
📌 Casos de uso
Onde batch ganha.
- •Auditar 200 PRs
- •Resumir 500 issues
- •Categorizar 1000 logs
- •Validar dados em lote
⚠️ Respeita max_threads
Não tente burlar com batch — Codex respeita max_threads global.
🛡️ Sandbox e approval inheritance
Subagents herdam sandbox e approval policies do parent. Em CI/non-interactive, approval que não consegue subir falha o run.
📌 Modos sandbox
Do mais restrito ao mais permissivo.
- •read-only — leitura apenas
- •workspace-read — workspace + leitura
- •workspace-write — workspace + escrita
- •danger-full-access — tudo
💡 CI
CI deve ter sandbox forte; sem aprovador humano para subir prompt.
🎼 Symphony: orquestração no Linear
Spec open-source da OpenAI que turbinou times reportadamente em +500% de PRs aterrissados ao usar Linear como control plane.
📌 Como funciona
Codex MCP server + Agents SDK.
- •Linear ticket → trigger
- •Codex como MCP server
- •Agents SDK orquestra pipeline
- •PR de volta no ticket
- •Auditável e determinístico
💡 Padrão a observar
Mesmo se você usa Claude Code Teams hoje, Symphony aponta para o ano que vem.
📌 Resumo do Módulo
Próximo módulo:
5.2 — Gemini CLI Subagents