Subagents: Distribua o trabalho em paralelo, mas só quando você mandar

📚 Navegação da série: O artigo anterior 20 · Conectando ferramentas externas com MCP ensinou como adicionar ferramentas externas ao Codex para consultar documentação e conectar serviços. Este artigo muda de perspectiva — em vez de "adicionar ferramentas", ensina como distribuir o trabalho em paralelo: Subagents (subagentes), um conjunto de assistentes especializados com modelos, instruções e permissões independentes, que trabalham simultaneamente e entregam um resultado consolidado.

Pessoal, hoje vamos falar sobre uma das funcionalidades mais impressionantes — e mais mal utilizadas — do Codex: os subagentes.

O nome já soa sofisticado: "múltiplos agentes em paralelo", como se você estivesse comandando uma pequena equipe. Quando descobri essa funcionalidade, confesso que fiquei animado demais, tentando dividir cada tarefa em cinco ou seis agentes trabalhando ao mesmo tempo, achando que isso era o "jeito profissional".

Mas sendo honesto: os subagents do Codex são diferentes do que você viu em outros lugares, e há uma configuração contraintuitiva que você precisa saber antes de mais nada — por padrão, o Codex nunca divide o trabalho sozinho. A documentação oficial deixa isso bem claro: o Codex só cria subagentes quando você pede explicitamente que ele divida o trabalho. Se você não disser "abra alguns agentes em paralelo", ele continua trabalhando sozinho. Esse detalhe define como usar essa funcionalidade e quando usá-la.

Ao terminar este artigo, você terá:

• O que são subagents — como dividir o trabalho entre agentes especializados em paralelo e depois consolidar os resultados, e como isso difere de "um único agente trabalhando sozinho"
• Os dois problemas reais que eles resolvem: contaminação de contexto (context pollution) e deterioração de contexto (context rot), além de uma linha contraintuitiva: quando não dividir o trabalho
• Os três agentes embutidos do Codex (default / worker / explorer), prontos para usar sem configuração
• Como escrever um agente personalizado: basta colocar um arquivo TOML em ~/.codex/agents/ ou .codex/agents/, com apenas três campos obrigatórios
• Como escolher modelos e "intensidade de raciocínio" diferentes para cada agente, usando modelos rápidos para reconhecimento e modelos poderosos para revisão
• Prática passo a passo: escrever um agente de reconhecimento somente-leitura, executá-lo e verificar que ele só retorna um resumo sem ultrapassar as permissões

⚠️ Todas as menções a comandos específicos, chaves de configuração e comportamentos padrão seguem a documentação oficial do Codex; nomes de modelos como gpt-5.5 podem mudar com as versões — consulte o que está disponível localmente no momento da leitura.

---

01 Entendendo o que são subagents

Conclusão direta: subagents são agentes especializados criados temporariamente pelo Codex — cada um opera em uma thread independente, e ao terminar, não despeja todos os detalhes intermediários de volta, mas sim entrega um resumo consolidado para você.

Analogia: dividir um caso complexo entre vários detetives trabalhando simultaneamente. Você é o detetive-chefe (conversa principal), com um caso complexo nas mãos — digamos, "revisar esta alteração nos aspectos de segurança, desempenho e cobertura de testes". As três frentes não se interferem, e você não precisa investigar as três sozinho. Então você envia três detetives: um focado em vulnerabilidades de segurança, um em desempenho e um em lacunas de testes — todos saem ao mesmo tempo, cada um investigando o seu. Quando terminam, não jogam centenas de páginas de relatórios brutos na sua mesa, mas entregam um resumo: "Na segurança, há dois riscos em X e Y". O que você recebe é um consolidado organizado por área.

Esses detetives têm algumas coisas que são "deles", separadas da sua thread principal. A documentação oficial organiza bem os termos:

Subagent: um agente delegado criado pelo Codex para lidar com uma tarefa específica. Agent thread: a thread CLI de um agente, que você pode visualizar e alternar usando /agent.

Detalhando, um subagente pode ter as seguintes coisas de forma "independente":

Dimensão	Thread principal (sua conversa)	Subagent (a frente enviada)
Thread / Contexto	Requisitos, decisões e histórico da sua conversa com o Codex	Sua própria thread de agente independente, com detalhes brutos da tarefa específica que recebeu
Modelo / Intensidade de raciocínio	O conjunto que você usa na sessão principal	Pode ser especificado separadamente — modelos rápidos para reconhecimento, modelos poderosos para revisão (detalhes na seção 05)
Instruções (persona)	Comportamento padrão do Codex	Suas developer_instructions personalizadas — ex.: "você só explora, não pode modificar código"
Permissões de sandbox	A política de sandbox da sua sessão atual	Herda sua política por padrão, mas pode ser configurada individualmente para cada agente — ex.: forçar read-only

O ponto mais crítico, a essência dos subagents do Codex: seu valor está em "transferir o ruído intermediário para fora da thread principal". Nas palavras da documentação — deixe o agente principal focado em requisitos, decisões e resultados finais, delegando exploração, execução de testes e análise de logs — tarefas que geram muito texto — para subagents em paralelo. Os subagents retornam apenas um resumo, não a saída bruta.

Isso determina em que os subagents são bons e onde não são, tema da próxima seção.

Esta imagem mostra o funcionamento dos subagents em uma linha: o agente principal divide uma grande tarefa e distribui para vários subagents em paralelo; cada subagent fica em seu próprio contexto independente (exploração, testes e documentação não se misturam), e ao terminar, retorna apenas um resumo para a thread principal — todos os detalhes brutos que ocupariam a tela ficam em cada thread individual, mantendo a thread principal sempre limpa.

💡 Resumo em uma frase: Subagent = conjunto de agentes especializados com threads independentes, modelos e permissões configuráveis de forma independente, trabalhando em paralelo e retornando apenas resumos à thread principal; o valor central é "transferir o ruído intermediário para fora da sua conversa principal".

---

02 O que ele resolve — e a linha contraintuitiva

Sabendo "o que é", é preciso entender "por que existe". A documentação oficial descreve os problemas que os subagents resolvem de forma bem direta — apenas duas palavras. Se você memorizar essas duas palavras, entende metade dessa funcionalidade.

Problema 1: Contaminação de contexto (context pollution)

Analogia: misturar pedidos de delivery em uma pilha de documentos importantes. Sua conversa principal tem assuntos sérios na mesa — requisitos, restrições, decisões tomadas. Aí você pede para ele "rodar toda a suíte de testes", e centenas ou milhares de linhas de log de testes aparecem, cobrindo tudo. As poucas informações úteis de "quais falharam" ficam enterradas sob uma pilha de saída inútil, e você tem que cavar fundo para encontrá-las. Isso é contaminação de contexto: o ruído abafa o sinal.

Definição oficial:

Context pollution (contaminação de contexto): informações úteis enterradas sob saída intermediária ruidosa.

Cenário real: ano passado, estava integrando uma API de terceiros, pedindo ao Codex para tentar repetidamente e cada tentativa gerava uma tela de JSON de resposta. Na décima e tantas rodada, quando queria confirmar "qual era mesmo o requisito inicial — o campo A era obrigatório?", tentei rolar para cima — tudo JSON, levei quase vinte telas para encontrar aquela frase. Naquele momento entendi: tarefas que geram muita saída intermediária nunca deveriam ser expostas na thread principal.

Problema 2: Deterioração de contexto (context rot)

Analogia: reunião que dura tempo demais, as pessoas começam a se distrair. Na primeira hora, todos focados no tema; na terceira hora, a mesa está cheia de detalhes tangenciais e divagações, e a qualidade das decisões cai visivelmente. Modelos também têm esse problema — quanto mais a conversa se enche de detalhes não relacionados, o desempenho vai gradualmente piorando.

Definição oficial:

Context rot (deterioração de contexto): desempenho gradualmente pior conforme a conversa vai sendo preenchida com detalhes cada vez menos relevantes.

A cura para os dois problemas é a mesma: tirar o trabalho barulhento da thread principal, jogá-lo para subagents em paralelo, e fazer com que retornem apenas resumos destilados. A documentação até dá um exemplo extremo — um documento enorme com milhões de tokens pode ser dividido em blocos menores, com múltiplos subagents lendo cada parte e retornando apenas os pontos-chave para a thread principal. A thread principal sempre se mantém limpa.

A linha contraintuitiva: quais tarefas não dividir

Certo, problemas explicados. Voltando à frase inicial — por que "dividir logo de cara" está errado?

Porque subagents não são de graça. A documentação enfatiza repetidamente um custo: cada subagent precisa rodar o modelo e chamar ferramentas sozinho, então fluxos de trabalho com subagents consomem mais tokens do que a abordagem equivalente com um único agente. Quanto mais você divide, mais gasta. Há também um segundo custo implícito — escrita em paralelo é muito mais arriscada do que leitura em paralelo:

Para começar, use agentes paralelos para tarefas predominantemente de leitura — exploração, testes, triagem, resumo. Fluxos de trabalho paralelos predominantemente de escrita exigem mais cuidado, pois múltiplos agentes modificando código simultaneamente podem conflitar e aumentar os custos de coordenação.

Condensei as considerações da documentação em uma tabela de decisão — o item mais importante desta seção:

Tipo de tarefa	Deve dividir para subagents?	Por quê
Exploração / execução de testes / análise de logs / resumo (predominantemente leitura, gera muita saída)	✅ Vale dividir e pode paralelizar	Transferir o ruído para fora da thread principal é exatamente o propósito
Várias pesquisas independentes entre si (auth / banco de dados / API cada uma separada)	✅ Vale paralelizar	Rodar simultâneo transforma três chamadas sequenciais em uma paralela
Pequena modificação explicável em uma frase, alteração já visível	❌ Não dividir	Subagents precisam rodar o modelo e gastar tokens — custo maior que o benefício
Múltiplos agentes modificando o mesmo conjunto de arquivos simultaneamente	⚠️ Usar com cautela	Escrita paralela cria conflitos e custo de coordenação alto
Etapas com dependências fortes — B só pode começar após A terminar	⚠️ Dividir não acelera	Paralelismo pressupõe independência

Cenário real: durante um período fui teimoso, queria "abrir um agente para modificar" até para "renomear este nome de função". Era pura burocracia — criar, rodar o modelo, retornar — e no final era mais lento do que simplesmente dizer "renomeie este nome" na thread principal, além de desperdiçar tokens. Desde então estabeleci uma regra: tarefas explicáveis em uma frase com a alteração visível nunca são divididas.

💡 Resumo em uma frase: Subagents curam "contaminação de contexto + deterioração de contexto" — transferindo tarefas barulhentas de leitura para fora da thread principal para execução paralela; mas modificações pequenas, dependências fortes e escrita paralela são três tipos a evitar — dividir muito ≠ ser profissional, divisão excessiva é mais lenta, mais cara e cria conflitos.

A imagem abaixo conecta "a decisão de dividir ou não" com "como funciona após dividir":

O que esta imagem mostra: primeiro, decidir "dividir ou não" — se não dividir, fica na thread principal; se dividir e você pediu, o Codex envia vários agentes em paralelo, aguarda todos os resultados e entrega um consolidado para a thread principal — observe a bifurcação "você pediu", sem ela o Codex não divide sozinho.

---

03 Sem precisar configurar: três agentes embutidos + como ativá-los

Falando de "se deve ou não usar", vamos ao prático. Boa notícia: o Codex vem com três agentes embutidos, prontos para usar — você não precisa escrever uma linha de configuração.

Os três agentes embutidos da documentação oficial:

Agente embutido	Perfil	Ideal para
default	Agente de propósito geral	Escolha padrão quando não há requisito específico
worker	Focado em execução: implementação, correções	Tarefas práticas como escrever código e corrigir bugs
explorer	Focado em leitura: análise de codebase, exploração	Leitura ampla de código, localização, pesquisa

Ter os agentes não é suficiente — alguém precisa ativá-los. Aqui está a regra mais importante do Codex sobre esse assunto: o Codex não divide automaticamente — você precisa dizer explicitamente na sua mensagem que quer paralelismo. Nas palavras da documentação oficial:

O Codex não cria subagents automaticamente — apenas quando você explicitamente pede subagents ou trabalho com agentes paralelos.

Então "ativar" não depende de nenhuma sintaxe especial — é só você deixar claro na mensagem como dividir o trabalho, se deve esperar por todos e o que deve ser retornado no resumo. Os exemplos da documentação usam instruções diretas como "spawn two agents", "delegate this work in parallel" e "use one agent per point". Um bom prompt para subagents, segundo a documentação, deve especificar três coisas: como dividir o trabalho, se deve esperar todos os agentes terminarem antes de continuar, e qual formato de resumo retornar.

Seguindo os exemplos oficiais, você pode dizer diretamente no Codex:

Use subagents em paralelo para revisar este branch (branch atual vs main). Abra um agente focado em riscos de segurança, um em lacunas de testes e um em manutenibilidade. Espere os três terminarem e consolide os achados por categoria, incluindo a localização dos arquivos.

Analogia: você é o diretor ordenando "gravar simultaneamente". Se não der a ordem, tudo é gravado em sequência; quando você diz "grave estas três cenas com três câmeras simultaneamente e me entregue tudo", a equipe se divide. Essa frase "simultâneo + me entregue tudo" é sua instrução de criação — as câmeras (agentes) sempre estiveram lá, esperando o seu comando.

Uma vez iniciado, a coordenação fica por conta do Codex — de acordo com a documentação, ele cria novos agentes, repassa instruções subsequentes, aguarda os resultados e encerra as threads concluídas; quando múltiplos agentes estão rodando, ele espera os resultados que você solicitou ficarem prontos e retorna uma resposta consolidada.

Cenário real: na primeira vez que usei essa funcionalidade para revisar um PR, segui o prompt "spawn one agent per point" da documentação e passei seis pontos de revisão de uma vez. Achei que ia demorar muito, mas com as várias frentes em paralelo foi muito mais rápido do que perguntar um por um — e recebi um consolidado organizado pelos seis pontos. Naquele momento entendi de verdade o que "paralelo" economiza — economiza as rodadas de espera sequencial.

⚠️ Há uma diferença de plataforma sobre visibilidade: a atividade dos subagents atualmente pode ser vista no Codex app e CLI, mas a visibilidade nas extensões IDE está marcada como "em breve" na documentação oficial. Para ver os agentes rodando visualmente, use o app ou CLI.

💡 Resumo em uma frase: três agentes embutidos (default / worker / explorer) prontos para usar; mas o Codex nunca divide sozinho — você precisa dizer explicitamente na mensagem "abra X agentes em paralelo, espere terminar, retorne o consolidado" para ele agir — e ele aguarda todos os resultados antes de entregar o resumo.

---

04 Gerenciar agentes em execução: /agent para visualizar, ou comandar diretamente

Com vários agentes rodando ao mesmo tempo, você precisa de uma forma de ver em que ponto estão e até mudar de ideia. O Codex oferece dois controles.

Controle 1: Alternar e visualizar com /agent

O comando oficial é /agent (singular, não /agents), usado no CLI para alternar entre threads de agentes ativos e ver o que cada thread está fazendo no momento.

/agent

Atenção — pode ser diferente do que você imagina de outras ferramentas: este não é um comando para "executar um agente", mas sim para "entrar e visualizar / alternar threads". Criação acontece quando você fala, visualização acontece com /agent.

Controle 2: Comandar diretamente na conversa

O jeito mais natural é falar diretamente com o Codex. Nas palavras da documentação oficial: você pode dizer diretamente ao Codex para controlar um subagent em execução, pará-lo ou encerrar threads de agentes que já terminaram. Não precisa memorizar subcomandos — basta usar linguagem natural, como "pare o agente de exploração que ainda está rodando".

Analogia: você é a central de despacho, falando pelo rádio a qualquer momento. Vários carros estão em campo; você pode mudar para a frequência de um carro e ouvir o relatório em tempo real (/agent), ou falar diretamente pelo rádio "carro 3, pode parar de investigar, volte" (comando direto). Os carros estão fora trabalhando sozinhos, mas a palavra final sobre a direção sempre é sua.

Há uma pegadinha sobre aprovações que a documentação destaca especificamente: no CLI interativo, pedidos de aprovação podem aparecer de uma thread de agente que você não está vendo no momento. Por exemplo, você está olhando a thread principal, mas um agente em segundo plano chega a uma operação que requer aprovação — a janela pop-up indica de qual thread veio. Você pode pressionar o para entrar nessa thread e ver o contexto, antes de decidir se aprova, rejeita ou como responder. Em fluxos não interativos (como scripts), operações que não podem gerar novas aprovações falharão diretamente e propagarão o erro para o fluxo de trabalho.

💡 Resumo em uma frase: dois controles para gerenciar agentes em execução — /agent (singular) para entrar e alternar threads / ver progresso, ou falar diretamente para parar, controlar ou encerrar um agente; no CLI interativo, outros threads também podem gerar pedidos de aprovação — pressione o para ver antes de aprovar.

---

05 Agentes personalizados: escreva um arquivo TOML e configure o modelo específico

Os três agentes embutidos cobrem muitos cenários, mas se você perceber que repete sempre o mesmo tipo de tarefa — como "revisar como um owner, focando em corretude e segurança" — é hora de transformar isso em um agente personalizado, ativável com uma frase na próxima vez.

Como criar: coloque um arquivo TOML (Tom's Obvious Minimal Language, um formato de configuração simples, mais legível que JSON) no diretório de agentes — um arquivo define um agente. Os dois locais oficiais:

Onde colocar	Quem pode usar	Ideal para
~/.codex/agents/	Todos os seus projetos	Agentes pessoais de uso geral que você quer ter em qualquer lugar
.codex/agents/	Apenas o projeto atual	Agentes específicos do projeto, podem ser commitados para a equipe

Analogia: criar uma "ficha de especialista" para um detetive específico. Os três embutidos são de uso geral da empresa; o TOML que você escreve é a ficha individual de um detetive com especialidade — nome, área de atuação, regras de trabalho e nível de equipamento (modelo). Com a ficha criada, basta chamar pelo nome.

Um arquivo de agente personalizado tem esta aparência, com apenas três campos obrigatórios:

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""

Explicando cada campo (conforme o schema oficial):

Campo	Obrigatório	Para que serve	Ponto importante
name	Sim	O nome usado pelo Codex para criar / referenciar este agente	É a única fonte da verdade da identidade — o nome do arquivo deve idealmente coincidir, mas name prevalece
description	Sim	Descrição para humanos: em que cenário usar este agente	Escreva com clareza para facilitar reconhecimento pela equipe
developer_instructions	Sim	Instruções centrais que definem o comportamento do agente	A "persona + regras de trabalho" dele
nickname_candidates	Não	Pool de apelidos para exibição na criação	Quando múltiplas instâncias do mesmo agente estão abertas, a UI pode mostrar apelidos diferentes para distinguir — apenas para exibição, não afeta a identidade

Os outros campos opcionais são herdados da sessão pai se não especificados: model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config. A documentação também menciona — arquivos de agente personalizado são carregados como uma "camada de configuração", então você pode adicionar outras chaves suportadas por config.toml. Há também uma prioridade para memorizar: se o seu agente personalizado tiver o mesmo nome de um embutido (como explorer), o seu sobrepõe o embutido.

Escolher modelos e intensidade de raciocínio diferentes para cada agente

Esta é a parte mais valiosa dos agentes personalizados — dar a cada frente o cérebro mais adequado para ela. Dois ajustes:

• model: qual modelo usar. A filosofia da documentação é "reconhecimento usa rápido, revisão usa poderoso" — para leitura, varredura de arquivos grandes e workers paralelos, use modelos mais rápidos e econômicos (a documentação cita a categoria gpt-5.4-mini); para revisão e lógica complexa multi-etapas, use modelos mais poderosos (a documentação lista gpt-5.4 / gpt-5.5, sendo gpt-5.5 o mínimo para demanding agents e o exemplo de revisor usa gpt-5.4). Nomes específicos de modelos mudam com as versões, consulte a documentação oficial — basta memorizar a filosofia "reconhecimento usa rápido, ataque usa poderoso".
• model_reasoning_effort: intensidade de raciocínio, três níveis.

Intensidade	Usar para	Custo
high	Seguir lógica complexa, verificar suposições, cobrir casos de borda (agentes de revisão / segurança)	Mais lento, mais tokens, mas qualidade maior em tarefas complexas
medium	Padrão equilibrado para a maioria dos agentes	Intermediário
low	Tarefa direta, prioridade em velocidade	Mais rápido

Aplicando nos arquivos — modelo rápido e raciocínio baixo para o explorador, modelo poderoso e raciocínio alto para o revisor:

Nota sobre os modelos: o exemplo oficial do explorador usa gpt-5.3-codex-spark (requer ChatGPT Pro, research preview), aqui substituído por gpt-5.4-mini — usuários Pro podem voltar para gpt-5.3-codex-spark.

# .codex/agents/explorer.toml — explorador somente-leitura: rápido, econômico, não age
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless asked.
"""

Note o sandbox_mode = "read-only" — isso é configurar permissões individualmente para um agente específico. A documentação diz que subagents herdam por padrão a política de sandbox da sua sessão atual, mas você pode marcar um específico como somente-leitura no arquivo do agente, tornando este explorador incapaz de fazer alterações mesmo se quisesse.

⚠️ Uma armadilha de prioridade de permissões: configurações de runtime temporárias que você fez na sessão (como ajustes com /permissions ou --yolo) são reaplicadas aos subagents criados — mesmo que o arquivo do agente tenha valores padrão diferentes. Ou seja, suas escolhas em tempo real da sessão sobrepõem os padrões estáticos do arquivo do agente.

Há também uma configuração global [agents] que controla o "interruptor geral" de todos os subagents, escrita no seu config.toml (não em arquivos de agente individuais):

Chave global	Para que serve	Valor padrão
agents.max_threads	Limite máximo de threads de agente simultâneas	Padrão 6 se não configurado
agents.max_depth	Profundidade de aninhamento de agentes (sessão raiz começa em 0)	Padrão 1: permite subagents diretos, mas proíbe aninhamento adicional
agents.job_max_runtime_seconds	Timeout padrão por worker em tarefas de processamento CSV em lote	Recai para 1800 segundos por worker se não configurado

A documentação tem uma observação muito prática sobre max_depth: mantenha o padrão 1, a menos que você realmente precise de delegação recursiva. Aumentá-lo transforma instruções de "delegação ampla" em fan-out em camadas — tokens, latência e recursos da máquina explodem — max_threads pode limitar threads concorrentes, mas não contém os custos e a imprevisibilidade trazidos pela recursão profunda.

💡 Resumo em uma frase: agente personalizado é um TOML em ~/.codex/agents/ ou .codex/agents/, com name / description / developer_instructions obrigatórios; campos opcionais herdam da sessão pai, model + model_reasoning_effort dão ao explorador um cérebro rápido e ao revisor um cérebro poderoso, e sandbox_mode pode bloquear permissões individualmente.

---

06 Prática: escreva um agente explorador somente-leitura e coloque-o para trabalhar

Só ler sem praticar não cria memória muscular. Esta seção te guia para escrever um agente personalizado mínimo e fazê-lo rodar de verdade, vendo com seus próprios olhos a cadeia "explorador investigando sozinho, retornando apenas conclusões, sem ultrapassar permissões". Não depende de nenhum ambiente complexo.

Criaremos o mais simples: um "explorador de projetos" somente-leitura, especializado em ler código e reportar estrutura e potenciais problemas, mas sem poder modificar uma única palavra (bloqueado por sandbox_mode = "read-only").

Passo 1: criar um projeto de teste e o diretório de agentes (Mac / Linux)

mkdir sub-demo
cd sub-demo
mkdir -p .codex/agents

Esperado: sub-demo tem o diretório .codex/agents/. Rodando ls .codex você deve ver agents dentro.

Usuários Windows, no PowerShell: mkdir sub-demo; cd sub-demo; mkdir .codex\agents -Force. Os comandos echo, cat também devem ser adaptados para PowerShell.

Passo 2: escrever o arquivo do agente personalizado

No editor de sua preferência, crie sub-demo/.codex/agents/scout.toml e cole:

name = "scout"
description = "Explorador de projetos somente-leitura que lê arquivos especificados, reporta estrutura e problemas potenciais, sem fazer modificações."
sandbox_mode = "read-only"
model_reasoning_effort = "low"
developer_instructions = """
Você é um explorador de código somente-leitura, apenas explora, não modifica código.
Quando ativado:
1. Leia os arquivos especificados pelo usuário
2. Liste os problemas em três categorias: legibilidade, nomenclatura, bugs potenciais
3. Ofereça uma direção de melhoria para cada item, mas nunca modifique nenhum arquivo
Por fim, retorne apenas um resumo conciso — não cole o código-fonte original inteiro.
"""

Note que não há campo model — por padrão, ele herda o modelo da sessão pai. sandbox_mode = "read-only" o fixa como somente-leitura — ele não consegue escrever mesmo que queira; model_reasoning_effort = "low" faz tarefas leves rodarem mais rápido.

Passo 3: criar algum código "com espaço para melhoria" para ele explorar

echo 'def f(a, b):
    return a / b' > calc.py

O nome da função f e os parâmetros a / b são muito ruins, e não trata divisão por zero — perfeito para o explorador detectar.

Esperado: sub-demo tem calc.py com as duas linhas acima.

Passo 4: iniciar o Codex e pedir explicitamente que este agente explore

codex

Dentro, lembre-se da regra de ferro da seção 03 — você precisa dizer explicitamente que quer um subagent; o Codex não vai dividir sozinho:

Envie o subagent scout para explorar calc.py, seguindo suas regras, retornando apenas um resumo dos problemas sem modificar arquivos.

Esperado: o Codex cria o subagent scout (no app / CLI você pode ver esta thread de agente rodando, possivelmente com um apelido). Ele lê calc.py em sua thread somente-leitura e depois retorna apenas um "resumo de exploração" para a thread principal — provavelmente apontando: nome de função f e parâmetros a / b são pouco descritivos, sem tratamento para divisor zero, sugerindo nomenclatura mais clara e verificação de fronteiras. Note que ele apenas indica direções, sem modificar seus arquivos (porque é read-only). Para ver o progresso no meio do caminho, você pode digitar /agent para entrar na thread e dar uma olhada.

Passo 5: verificar que ele de fato não modificou nenhum arquivo

Saia do Codex e volte ao terminal:

cat calc.py

(No Windows PowerShell use type calc.py)

Esperado: calc.py permanece intacto, ainda com as duas linhas originais — este é o poder de "bloquear permissões": você o fixou como somente-leitura, e mesmo que quisesse ajudar a corrigir, não consegue — só pode falar.

Completando esses cinco passos, você verificou pessoalmente a cadeia completa "escrever TOML → dizer explicitamente para criar → subagent trabalhando em thread independente → retornando apenas resumo sem ultrapassar permissões". Qualquer agente personalizado futuro é, na essência, esse mecanismo com instruções diferentes, modelo diferente e permissões ajustadas.

⚠️ Se o Codex não criou o scout e tratou diretamente, provavelmente você não deixou suficientemente claro que queria um subagent — volte à seção 03, seja mais explícito com "envie o subagent XX para", não deixe ele achar que você só quer um resultado.

💡 Resumo em uma frase: escreva um TOML read-only para o explorador, diga explicitamente "envie scout para explorar", faça-o rodar, e então use cat para confirmar que o arquivo não foi modificado — verificar pessoalmente a cadeia "trabalho independente + permissões bloqueadas sem ultrapassar" vale mais do que memorizar dez campos.

---

07 Menção avançada: processamento em lote de CSV (experimental)

⚠️ Esta funcionalidade está marcada pela documentação oficial como experimental, podendo mudar conforme o suporte a subagents evolui — aqui apenas mencionamos brevemente para que você saiba que existe, não a trate como uma capacidade estável.

Se você tem muitas tarefas parecidas — como "um arquivo por linha / um PR por linha / um alvo de migração por linha", revisar uma por uma — o Codex tem um spawn_agents_on_csv: ele lê um CSV, cria um subagent worker para cada linha, aguarda o lote completo e exporta os resultados combinados como CSV.

Analogia: esteira de triagem. Uma caixa de pacotes (uma tarefa por linha do CSV), abrir uma fileira de triadores (um worker por linha) para etiquetar simultaneamente, ao terminar tudo consolidar em uma planilha geral. Cada worker deve chamar report_agent_job_result exatamente uma vez para reportar o resultado; caso contrário, essa linha ficará marcada como erro no CSV exportado. Para parâmetros e uso detalhado, consulte a documentação oficial.

Quais tarefas valem a pena, quais não valem:

Cenário	Adequado para spawn_agents_on_csv?	Razão
Revisar dezenas de PRs em lote, estrutura dos objetos consistente	✅ Adequado	Mesma ação, muitos objetos similares — benefício do paralelismo evidente
Traduzir comentários de dezenas de arquivos para o inglês em lote	✅ Adequado	Cada linha é independente, sem interdependências — o cenário ideal para processamento CSV em lote
Etapas com dependências de ordem (B só pode começar após A)	❌ Inadequado	As linhas do CSV são enviadas em paralelo, não há garantia de ordem
Apenas três ou quatro objetos, alterações muito pequenas	❌ Inadequado	O custo de iniciar o processamento em lote experimental é maior do que dizer diretamente
Escrita paralela no mesmo conjunto de arquivos	⚠️ Usar com cautela	Múltiplos workers agindo simultaneamente — mesmo risco de conflito da seção 02

💡 Resumo em uma frase: spawn_agents_on_csv (experimental) é adequado para cenários de "mesma ação repetida em grande quantidade de objetos similares" — leitura ou escrita independente; dependências, poucos objetos ou escrita paralela nos mesmos arquivos são mais estáveis com subagents comuns ou diretamente na thread principal.

---

08 Resumo

Este artigo cobriu os "subagents" do Codex de "o que são" até "como ativar, como escrever e como verificar" — o ponto central não é ensinar a dividir de forma elaborada, mas ajudá-lo a estabelecer aquela linha de julgamento de "quando paralelizar versus fazer sozinho", e memorizar o comportamento contraintuitivo do Codex: sem pedir, ele não divide.

Revisão dos pontos-chave:

Pergunta	Resposta	Ponto-chave
O que é um subagent	Conjunto de agentes especializados com threads independentes, modelos / permissões configuráveis	Trabalhando em paralelo, retornando apenas resumos à thread principal
O que ele resolve	Contaminação de contexto + deterioração de contexto	Transferir tarefas barulhentas de leitura para fora da thread principal
Quando não usar	Modificações pequenas, dependências fortes, escrita paralela	Dividir muito ≠ profissional — excessivo é mais lento, caro e cria conflitos
Como ativar	Você deve dizer explicitamente para paralelizar; o Codex nunca divide sozinho	Diga claramente "como dividir, se deve esperar todos, o que retornar"
Embutido / Personalizado	Três embutidos prontos; personalizado com TOML	Obrigatórios: name / description / developer_instructions
Como escolher o modelo	model + model_reasoning_effort	Exploração usa cérebro rápido, revisão usa cérebro poderoso

Você agora deve ser capaz de: julgar se uma tarefa deve ou não ser dividida para subagents (sem se empolgar e dividir de imediato); usar bem os três agentes embutidos, ou escrever um agente personalizado com instruções, modelo e permissões específicas em ~/.codex/agents/; e lembrar — só dividirá quando você pedir, e ao terminar, retornará apenas o resumo. Esse senso de "paralelizar quando deve, fazer sozinho quando deve" é a verdadeira barreira dos subagents — a funcionalidade se aprende em dez minutos, o bom julgamento vem com o uso.

Lembre-se desta frase contraintuitiva do início: os subagents do Codex são poderosos, mas não tomam decisões por você — dividir ou não, e quantos, é sempre decisão sua.

---

O próximo artigo 22 "Agent Skills" — até agora você foi equipando o Codex com "apoio externo" de forma crescentemente sistemática: AGENTS.md define as regras, comandos com barra acumulam atalhos, MCP conecta ferramentas externas, e agora você sabe dividir em subagents paralelos. Mas você não notou que as "regras de trabalho" do subagent ainda exigem escrever um longo developer_instructions a cada vez? Se essa habilidade pudesse ser empacotada como uma skill reutilizável, chamada quando necessário, não seria mais prático? O próximo artigo fala exatamente sobre como o Codex consolida habilidades em Skills.

---

Leitura recomendada

• Conectando ferramentas externas com MCP: adicionando "interfaces externas" ao Codex
• Controle de computador e navegador (Computer Use): dando mãos ao Codex
• Planos e preços