Codex passa a oferecer suporte a Subagents

• 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 geral
  • worker: agente orientado à execução, focado em implementação e correções
  • explorer: 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 agente
• description (string, obrigatório): guia voltado a humanos sobre quando o Codex deve usar esse agente
• developer_instructions (string, obrigatório): instruções centrais que definem o comportamento do agente
• nickname_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"

[kgcrom]

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.

[hmmhmmhm]

Aproveitei quando rolou aquela promoção super agressiva no KakaoTalk e estou usando muito bem hahaha

[xguru]

Codex, por favor, criem logo um controle remoto também!