🌐 Multi-runtime + Capstone

Cada agent é um arquivo TOML em ~/.codex/agents/ (user) ou .codex/agents/ (projeto).

Mesma ideia do Claude Code subagents — definição declarativa que vira "tipo" reusável.

Campos obrigatórios: name, description, developer_instructions; opcionais: model, sandbox_mode, mcp_servers.

Seção [agents] no config controla concorrência: max_threads (default 6), max_depth (default 1), job_max_runtime_seconds.

É a forma de impedir explosão de custo e nesting descontrolado.

Threads = paralelismo; depth = recursão; timeout previne workers travados.

Array nickname_candidates dá nomes legíveis às múltiplas instâncias do mesmo agent.

Sem isso, instâncias ficam como "agent-1, agent-2..." e diagnóstico vira sopa.

Use /agent para alternar threads; nicknames temáticos ("Athena", "Hermes") ajudam memória.

Tool experimental do Codex que processa cada linha de CSV com 1 worker e exporta resultados.

Casos como auditar 200 PRs ou gerar resumo de 500 issues ficam triviais.

1 worker por linha; coleta resultados; respeita max_threads global.

Subagents herdam sandbox e approval policies do parent. Erros propagam para o workflow.

Em CI/non-interactive, approval que não consegue subir falha o run inteiro — preveja com sandbox.

sandbox_mode por agent; runtime overrides são herdados; CI deve ter sandbox forte.

Spec open-source da OpenAI que turbinou times reportadamente em +500% PRs aterrissados ao usar Linear como control plane.

Aponta para "agentes em pipeline" governados por tickets — direção que o mercado todo está tomando.

Codex como MCP server; Agents SDK para orquestrar; deterministic + reviewable.

Cada subagent = arquivo .md com frontmatter YAML; corpo do markdown é o system prompt.

Familiar para quem usa Claude Code; muito legível; versionável em git.

Required: name, description, kind; opcionais: tools, model, temperature, max_turns, timeout_mins.

Prefixar a instrução com @subagent_name força o uso explícito sem deixar o main agent escolher.

Em debug, você quer determinismo; auto-delegation pode atrapalhar reproduzir um bug.

@nome no início; auto-delegation por padrão; mistura possível ("@codebase_investigator descobre, depois generalist resume").

Gemini suporta vários subagents (ou várias instâncias do mesmo) em paralelo, reduzindo wall-clock.

Padrão "tool exposto ao agente principal" combinado com paralelismo é poderoso.

Sem nesting (proteção de recursão); cada subagent isolado em context loop; main agente coleta.

Gemini vem com codebase_investigator, cli_help, generalist e browser_agent (experimental) prontos.

Antes de criar novo subagent, veja se um built-in já resolve. Reduz manutenção.

codebase_investigator = exploração; cli_help = doc CLI; generalist = task pesada genérica; browser_agent = web.

Subagents podem rodar remotamente (kind: remote). Útil quando quer isolamento ou recursos diferentes.

Mover work pesado para máquinas remotas é bom para CI e privacidade local.

Local default; remote para offload; observabilidade extra recomendada.

Subagent não pode invocar outro subagent (recursion protection); tools restritos por allowlist.

Modelagem hierárquica não funciona; pense flat e use o main agent como orquestrador.

Flat > nested; tools whitelisted no frontmatter; isolamento total de contexto.

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; muda só a sintaxe entre runtimes.

Role = system prompt; Tools = allowlist; Owned = território; Handoff = mailbox/return.

Cada conceito tem um nome em cada runtime: subagent definition (Claude) / TOML agent (Codex) / .md agent (Gemini).

Tabela mental de tradução acelera migração e evita "preciso reaprender tudo".

Frontmatter ↔ TOML ↔ YAML; tools allowlist ↔ tools array; mailbox ↔ N/A em subagents.

Implemente o squad de PR review (security + perf + tests) em Claude Code, Codex e Gemini.

Ver lado a lado o que muda e o que não muda solidifica a abstração portátil.

Mesmo prompt base; ajuste sintaxe da definição; tem "team" só em Claude Code; subagents bastam para review.

Claude Code Teams quando precisa de mailbox; Codex quando quer Symphony/Linear; Gemini quando integra com Google.

Não brigue com o runtime: cada um tem força em cenários distintos.

Mailbox = Claude; pipeline em ticket = Codex+Symphony; Google Workspace = Gemini.

Um prompt-base + 3 wrappers (frontmatter, TOML, YAML) é o que você quer manter no repositório.

Reduz drift entre versões; muda 1 vez, propaga para todos.

Source of truth = .md; wrappers em geradores; CI valida que estão sincronizados.

Quando complexidade cresce (cycles, branching, observabilidade), framework Python pode substituir o CLI.

CLI vs framework é trade-off de produtividade vs controle. Saber quando trocar.

CrewAI = papéis; LangGraph = grafo; AG2 = chat; Agents SDK = pipeline declarativo.

App full-stack: API REST (users + posts), front React, JWT, suíte de testes, relatório QA, doc operacional.

É realista o suficiente para exercitar todas as armadilhas; pequeno o suficiente para terminar em 4h.

App rodando em localhost:3000; tests/report.md; docs/build-summary.md; docs/cost-report.md.

5 teammates Sonnet com territórios distintos: src/api, src/ui, tests/, audits/, docs/.

É a aplicação prática de tudo que veio antes — territórios, mailbox, plan mode, hooks.

Security Reviewer como subagent definition reusável; Tech Writer com Haiku para reduzir custo.

25 pts prompt; 20 pts hooks; 20 pts testes verdes; 15 pts custo; 10 pts cleanup; 10 pts portabilidade.

Critérios objetivos forçam você a aplicar conceitos do curso, não só "fazer rodar".

Auto-avaliação primeiro; depois revisão de pares; pontuar honestamente.

Pelo menos 1 hook ativo no projeto: tests passando ao TaskCompleted, ou block-rm em PreToolUse.

Sem quality gate, "rodar" não é "qualidade". Hook é o que separa demo de entrega.

Hooks no .claude/settings.json; logs em arquivo; trigger por matcher.

Documento docs/cost-report.md com tokens por teammate, modelo escolhido por papel, e justificativa do tamanho do squad.

É o critério que diferencia engenheiro de "cliquei no botão". Mostra que entende custo.

Tokens por papel; modelo justificado; "por que 5 e não 3"; alternativa considerada.

Grave 5 min mostrando spawn, mailbox, idle notifications e cleanup; depois discuta decisões.

Apresentar consolida; outros aprendem com seus erros e acertos; portfolio show-piece.

Tempo curto força clareza; mostre só o que importa; admita o que não funcionou.