- O OpenAI Codex agora oferece suporte a workflows com subagentes, permitindo distribuir tarefas complexas em paralelo entre vários agentes especializados e consolidar os resultados em uma única resposta
- Os subagentes só são criados quando o usuário solicita explicitamente, e como cada agente usa modelos e ferramentas de forma independente, o consumo de tokens aumenta em relação a um único agente
- É possível definir agentes personalizados em arquivos TOML, configurando de forma independente para cada agente o modelo, o modo de sandbox, servidores MCP e mais
- Também inclui o recurso experimental spawn_agents_on_csv, que cria em lote agentes workers usando cada linha de um arquivo CSV como unidade de trabalho
- A documentação oficial traz diretamente padrões de combinação de agentes personalizados para cenários práticos como revisão de código e depuração de frontend
Visão geral e disponibilidade dos subagentes
- O Codex oferece suporte a workflows com subagentes que criam (spawn) agentes especializados em paralelo e reúnem os resultados em uma única resposta
- É especialmente útil para tarefas complexas que exigem alto paralelismo, como explorar um codebase ou planejar a implementação de funcionalidades em múltiplas etapas
- Nos workflows com subagentes, também é possível definir agentes personalizados com configurações de modelo e instruções diferentes conforme a tarefa
- Na versão atual do Codex, os workflows com subagentes vêm ativados por padrão
- Atualmente, a atividade dos subagentes pode ser vista no app do Codex e na CLI, e a visibilidade na IDE Extension será adicionada em breve
- Os subagentes só são criados quando o usuário solicita explicitamente, e como cada subagente executa suas próprias operações com modelo e ferramentas, o consumo de tokens é maior do que em execuções com um único agente
Workflow típico
- O Codex cuida da orquestração entre os agentes: inclui criar novos subagentes, encaminhar instruções de acompanhamento, aguardar resultados e encerrar threads de agentes
- Quando vários agentes estão em execução, o Codex aguarda até que todos os resultados estejam prontos e então retorna uma resposta consolidada
- Exemplo de prompt: pedir que seja criado um agente para cada aspecto do PR atual — problema de segurança, qualidade do código, bugs, race conditions, instabilidade de testes e manutenibilidade — e que o resultado geral seja resumido
Gerenciamento de subagentes
- Na CLI, o comando
/agent permite alternar entre threads ativas de agentes e inspecionar threads em andamento
- Também é possível pedir diretamente ao Codex para controlar, interromper ou encerrar threads concluídas de subagentes em execução
Aprovação e controle de sandbox
- Os subagentes herdam a política de sandbox atual do usuário
- Em sessões interativas da CLI, pedidos de aprovação vindos de threads de agentes inativos podem aparecer mesmo enquanto a thread principal está em uso, com o rótulo da thread de origem exibido na sobreposição de aprovação
- Pressione
o para abrir essa thread e então aprovar, recusar ou responder
- Em fluxos não interativos, não é possível exibir novas aprovações, então tarefas que exigem aprovação falham e o erro é propagado para o workflow superior
- Ao criar agentes filhos, as substituições dinâmicas de runtime do turno do agente pai são reaplicadas, incluindo mudanças feitas em
/approvals ou configurações interativas como --yolo
- Mesmo que o arquivo do agente personalizado selecionado defina outros padrões, a configuração do pai tem prioridade
- Também é possível substituir separadamente a configuração de sandbox de um agente personalizado específico, como definir determinado agente em modo somente leitura
Agentes personalizados
- O Codex oferece 3 agentes integrados por padrão
default: agente de fallback de uso geralworker: agente orientado à execução, focado em implementação e correçõesexplorer: agente focado em leitura para explorar o codebase
- Para definir agentes personalizados, adicione arquivos TOML independentes em
~/.codex/agents/ (uso pessoal) ou .codex/agents/ (escopo do projeto)
- Cada arquivo define um agente personalizado, e o Codex o carrega como uma camada de configuração na sessão de criação
- Campos obrigatórios que devem existir em todos os arquivos de agentes personalizados:
name, description, developer_instructions
- Campos opcionais como
nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config etc. são herdados da sessão pai quando omitidos
Configuração global
- As configurações globais dos subagentes são definidas na seção
[agents] do arquivo de configuração
agents.max_threads: limite máximo de threads de agentes abertas simultaneamente (padrão: 6)agents.max_depth: profundidade de aninhamento dos agentes criados (padrão: 1, permitindo apenas agentes filhos diretos e impedindo aninhamentos mais profundos)agents.job_max_runtime_seconds: timeout padrão por worker para jobs spawn_agents_on_csv (se não for definido, o padrão por chamada é 1800 segundos)- Se o nome de um agente personalizado for igual ao de um agente integrado, como
explorer, o agente personalizado terá prioridade
Esquema de arquivo de agente personalizado
name (string, obrigatório): nome do agente usado pelo Codex ao criar ou referenciar esse agentedescription (string, obrigatório): guia voltado a humanos sobre quando o Codex deve usar esse agentedeveloper_instructions (string, obrigatório): instruções centrais que definem o comportamento do agentenickname_candidates (string[], opcional): conjunto de apelidos exibidos para instâncias do agente criado- Também podem ser incluídas outras chaves compatíveis com
config.toml: model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config etc.
- O Codex identifica agentes pelo campo
name; embora fazer o nome do arquivo coincidir com o nome do agente seja a convenção mais simples, o campo name é a fonte da verdade
Apelidos de exibição
nickname_candidates serve para mostrar rótulos distinguíveis na interface quando várias instâncias do mesmo agente personalizado são executadas- Os apelidos são apenas para exibição; o Codex continua identificando e criando agentes pelo
name
- Os candidatos a apelido devem formar uma lista não vazia de nomes únicos e podem usar caracteres ASCII, números, espaços, hífens e underlines
- Exemplo: se o agente
reviewer tiver os apelidos ["Atlas", "Delta", "Echo"], o apelido será exibido no app e na CLI, mas o tipo básico do agente continuará sendo reviewer
Exemplo 1: padrão de revisão de PR
- Padrão que divide a revisão em três agentes personalizados especializados
pr_explorer: agente somente leitura que mapeia o codebase e coleta evidências (modelo: gpt-5.3-codex-spark, reasoning effort: medium)reviewer: revisor de PR que encontra problemas de correção, segurança e riscos de teste (modelo: gpt-5.4, reasoning effort: high)docs_researcher: especialista em documentação que verifica a documentação de frameworks ou APIs por meio de um servidor MCP dedicado (modelo: gpt-5.3-codex-spark, somente leitura)
- Configuração do projeto:
max_threads = 6, max_depth = 1
- Instruções do
pr_explorer: permanecer em modo de exploração, rastrear caminhos reais de execução, citar arquivos e símbolos e evitar sugerir mudanças a menos que o agente pai solicite
- Instruções do
reviewer: revisar do ponto de vista do responsável pelo código, priorizando correção, segurança, regressões comportamentais e cobertura de testes ausente, incluindo passos de reprodução quando possível, e evitar comentários puramente de estilo a menos que escondam bugs reais
- Instruções do
docs_researcher: usar o servidor MCP de docs para verificar APIs, opções e comportamentos por versão, respondendo de forma concisa com links ou referências exatas, sem alterar código
- Exemplo de prompt de uso: "Revise esta branch em comparação com a main. O pr_explorer mapeia os caminhos de código afetados, o reviewer encontra riscos reais e o docs_researcher valida as APIs de framework das quais o patch depende"
Processamento em lote com CSV: spawn_agents_on_csv (experimental)
- Recurso experimental, sujeito a mudanças futuras
- Quando há muitas tarefas parecidas, cria em lote subagentes workers usando cada linha do CSV como uma unidade de trabalho
- O Codex lê o CSV, cria um agente worker por linha, aguarda a conclusão de todo o lote e então exporta os resultados em CSV
- Casos de uso adequados:
- Revisar um arquivo, pacote ou serviço por linha
- Inspecionar uma lista de incidentes, PRs ou alvos de migração
- Gerar resumos estruturados para um grande volume de entradas semelhantes
- Parâmetros de entrada da ferramenta:
csv_path (CSV de origem), instruction (template de prompt do worker, com placeholders {column_name}), id_column (ID estável do item), output_schema (formato JSON fixo), output_csv_path, max_concurrency, max_runtime_seconds
- Cada worker deve chamar
report_agent_job_result exatamente uma vez; se encerrar sem reportar resultado, a linha será marcada como erro
- Ao executar com
codex exec, uma atualização de progresso em uma linha é exibida em stderr durante o lote
- O CSV exportado inclui os dados originais das linhas e metadados como
job_id, item_id, status, last_error, result_json etc.
- Configurações de runtime relacionadas:
agents.max_threads (limite de concorrência), agents.job_max_runtime_seconds (timeout por worker; max_runtime_seconds da chamada tem prioridade) e sqlite_home (caminho de persistência de estado em SQLite usado para jobs de agentes e resultados exportados)
Exemplo 2: padrão de depuração integrada de frontend
- Padrão útil para bugs integrados que cruzam regressões de UI, fluxos instáveis no navegador e o código da aplicação com o produto em execução
- Combinação de três agentes personalizados:
code_mapper: agente explorador somente leitura que encontra os caminhos relevantes de código frontend e backend (modelo: gpt-5.3-codex-spark, reasoning effort: medium)browser_debugger: depurador de UI que usa ferramentas de navegador para reproduzir o problema e capturar evidências (modelo: gpt-5.4, reasoning effort: high, sandbox: workspace-write)
- Usa ferramentas de navegador para screenshots, saída de console e evidências de rede, mas não pode editar o código da aplicação
- Conecta-se ao servidor MCP do Chrome DevTools (
http://localhost:3000/mcp, startup_timeout_sec: 20)
ui_fixer: agente focado em implementação responsável por correções pequenas e direcionadas depois que o problema é entendido (modelo: gpt-5.3-codex-spark, reasoning effort: medium)
- Faz a menor alteração defensável possível, não toca em arquivos não relacionados e valida apenas o comportamento alterado
- Exemplo de prompt de uso: "Investigue por que o modal de configurações falha ao salvar. O browser_debugger reproduz, o code_mapper rastreia o caminho de código correspondente e o ui_fixer implementa a correção mínima depois de identificar o modo de falha"
3 comentários
O agent usa apenas o modelo GPT-5.1-Codex-Mini, mas ao adicionar o prompt abaixo em Custom instructions do Codex App, o agent passa a funcionar com GPT-5.3-Codex-Spark.
"- when it spawns agents, use models "GPT-5.3-Codex-Spark" or higher."
Ou então também é bem divertido poder especificar o modelo ao criar o agent, e gosto de como o Codex App mostra isso em uma estrutura de subpastas.
Aproveitei quando rolou aquela promoção super agressiva no KakaoTalk e estou usando muito bem hahaha
Codex, por favor, criem logo um controle remoto também!