Codex: Subagents do Codex
Última atualização: 2026-08-31
Subagents permitem que o Codex decomponha tarefas complexas e as delegue a agentes especializados para execução paralela, melhorando drasticamente a eficiência.
📋 Pré-requisitos: Compreensão dos modos de fluxo de trabalho e Agent Skills do Codex
1. O Que Você Vai Aprender
- Conceitos e princípios de funcionamento dos Subagents
- Estratégias de delegação de tarefas
- Execução paralela e coordenação
- Comparação Subagent vs agente único
2. O Que São Subagents
Subagents são agentes auxiliares criados pelo Agent Codex principal, cada um responsável por uma subtarefa.
graph TB
A[Agent Principal] --> B[Subagent 1: Frontend]
A --> C[Subagent 2: Backend]
A --> D[Subagent 3: Testes]
B --> B1[Modificar Componentes UI]
C --> C1[Adicionar Endpoints API]
D --> D1[Escrever Casos de Teste]
B1 --> E[Agent Principal Agrega]
C1 --> E
D1 --> E
| Recurso | Descrição |
|---|---|
| Execução Independente | Cada subagent tem seu próprio sandbox |
| Execução Paralela | Múltiplos subagents rodam simultaneamente |
| Autocoordenação | Agent Principal agrega resultados |
| Divisão Especializada | Cada subagent pode usar um Skill diferente |
3. Casos de Uso
(1) Desenvolvimento Paralelo Multi-módulo
> Add product review functionality to the e-commerce site:
> - Frontend: review component + review list + star ratings
> - Backend: review API + rating aggregation
> - Testing: frontend and backend tests
# Codex automaticamente decompõe em subagents:
# Subagent 1: Desenvolvimento de componente frontend
# Subagent 2: Desenvolvimento de API backend
# Subagent 3: Escrita de testes
# Três subagents executam em paralelo
(2) Tradução Multi-idioma
> Translate README.md into Japanese, Portuguese, and Arabic
# Codex cria três subagents para tradução paralela
# Subagent 1: en → ja
# Subagent 2: en → pt-br
# Subagent 3: en → ar
▶ Exemplo 1: Desenvolvimento Multi-módulo de Alice
# Alice adiciona uma funcionalidade completa de pagamentos
> Add Stripe payments:
> 1. Payment page UI
> 2. Payment API endpoint
> 3. Webhook handling
> 4. Order management
> 5. Tests for all modules
# Codex decompõe em 4 subagents:
🔄 Subagent 1: Página de pagamento UI + página de gerenciamento de pedidos
🔄 Subagent 2: API de pagamento + endpoint Webhook
🔄 Subagent 3: Modelo de pedido + migração de banco de dados
🔄 Subagent 4: Testes de integração
# Execução paralela, total ~15 minutos
# Execução serial levaria ~50 minutos
4. Estratégia de Delegação de Tarefas
(1) Condições para Paralelismo
| Condição | Descrição |
|---|---|
| Modificar arquivos diferentes | Subagents não operam no mesmo arquivo |
| Sem dependências de dados | Subagents não precisam compartilhar estado |
| Independentemente verificável | Cada subtarefa pode ser verificada independentemente |
(2) Quando Não Paralelizar
| Situação | Descrição |
|---|---|
| Modificar mesmo arquivo | Pode causar conflitos |
| Dependências sequenciais | Passos posteriores precisam de resultados anteriores |
| Banco de dados compartilhado | Pode causar condições de corrida |
(3) Princípios de Decomposição
1. Decompor por módulo funcional (frontend / backend / testes)
2. Decompor por diretório de arquivos (src/auth/ / src/api/ / src/utils/)
3. Decompor por tipo de tarefa (implementação / testes / documentação)
4. Garantir limites claros para cada subtarefa
5. Coordenação de Subagents
(1) Coordenação Automática
O Agent Principal gerencia automaticamente o ciclo de vida dos subagents:
1. Analis tarefa, decompor em subtarefas
2. Criar subagent para cada subtarefa
3. Atribuir ambientes sandbox independentes
4. Monitorar progresso da execução
5. Agregar resultados, lidar com conflitos
6. Executar verificação de integração
(2) Mesclagem de Resultados
# Após subagents completarem, Agent Principal mescla resultados:
✅ Subagent 1: Componentes frontend concluídos (3 arquivos)
✅ Subagent 2: API backend concluída (2 arquivos)
✅ Subagent 3: Testes concluídos (4 arquivos)
# Agent Principal executa testes de integração
→ Running integration tests...
→ All 15 tests passed ✓
# Lidar com conflitos (se houver)
→ No conflicts detected
→ Ready for review
6. Subagent vs Agente Único
| Dimensão | Subagents | Agente Único |
|---|---|---|
| Velocidade de Execução | Rápida (paralela) | Lenta (serial) |
| Consumo de Recursos | Alto (múltiplos sandboxes) | Baixo (sandbox único) |
| Complexidade de Coordenação | Alta | Baixa |
| Risco de Conflito | Presente | Nenhum |
| Melhor Para | Subtarefas independentes | Tarefas com dependências |
❓ Perguntas Frequentes
P: Subagents são criados automaticamente? R: Nas versões App/Web, o Codex cria subagents automaticamente com base na complexidade da tarefa. No CLI, você precisa especificar explicitamente ou acionar via Skills.
P: Há limite de contagem de subagents? R: Depende do seu plano de assinatura. Free: máx 1, Plus: máx 3, Pro: máx 10, Business: máx 20.
P: Como os subagents se comunicam entre si? R: Subagents coordenam através do Agent Principal, não diretamente. O Agent Principal coleta resultados e decide próximos passos.
P: A falha de um subagent afeta os outros? R: Não. Cada subagent roda independentemente. Falha única não afeta outros. O Agent Principal lida com subtarefas falhas.
P: Como crio subagents manualmente? R: Decomponha explicitamente a tarefa no Prompt, e o Codex reconhecerá e criará subagents. Você também pode usar Skills para definir fluxos de trabalho de subagents.
📖 Resumo
- Subagents são agentes auxiliares criados pelo Agent Principal, rodando independentemente
- Casos de uso: paralelismo multi-módulo, tradução multi-idioma, processamento em lote
- Princípios de decomposição: por módulo/diretório/tipo, garantir limites claros
- Agent Principal autocoordena, agrega resultados, lida com conflitos
- Paralelismo acelera mas aumenta consumo de recursos e risco de conflitos
📝 Exercícios
- Básico (⭐): Faça o Codex decompor automaticamente uma tarefa de complexidade média em subagents para execução.
- Intermediário (⭐⭐): Desenhe uma funcionalidade multi-módulo garantindo que cada módulo pode ser desenvolvido em paralelo, observe a execução dos subagents.
- Avançado (⭐⭐⭐): Compare a mesma tarefa usando execução serial de agente único vs execução paralela de subagents, escreva um relatório de performance.
