Subagentes

O ChatGPT Work disponibiliza fluxos de trabalho e atividades de subagentes para contas qualificadas.

As versões atuais do Codex habilitam por padrão os fluxos de trabalho com subagentes. A atividade dos subagentes aparece no aplicativo do ChatGPT para desktop, na Codex CLI e na extensão para IDE.

No ChatGPT Work, peça ao ChatGPT para delegar tarefas independentes a subagentes. Os agentes são executados no ambiente hospedado do ChatGPT, e o chat mostra suas atividades e seus resultados. Na maioria dos níveis de inteligência, solicite a delegação explicitamente. Com Ultra, o ChatGPT pode delegar tarefas de forma proativa quando agentes em paralelo puderem melhorar significativamente a velocidade ou a qualidade.

Em um chat do aplicativo, peça ao Codex para delegar partes independentes do trabalho a subagentes. As versões locais atuais do Codex fazem essa delegação quando você solicita diretamente ou quando instruções aplicáveis de AGENTS.md ou de habilidades solicitam isso. O aplicativo exibe cada thread de subagente para que você possa inspecionar seu trabalho e o resumo retornado ao chat principal.

Em uma sessão interativa da CLI, peça ao Codex para usar subagentes. O Codex também pode seguir instruções aplicáveis de AGENTS.md ou de habilidades que solicitem a delegação. Use /agent para inspecionar e alternar entre threads de agentes durante a execução. A thread principal reúne os resultados dos subagentes na resposta final.

Em um chat da IDE, peça ao Codex para delegar partes independentes do trabalho a subagentes. O Codex também pode seguir instruções aplicáveis de AGENTS.md ou de habilidades que solicitem a delegação. Quando a interface de agentes em segundo plano estiver disponível, os subagentes ativos aparecem acima do Editor. Expanda o painel para ver o status deles, interromper todos os subagentes ativos ou abrir a thread de um subagente específico.

Na maioria dos níveis de inteligência, solicite diretamente subagentes ou trabalho de agentes em paralelo. Ultra permite a delegação proativa, para que o ChatGPT possa delegar tarefas independentes adequadas sem uma solicitação adicional.

Solicite diretamente subagentes ou trabalho de agentes em paralelo. O Codex também pode delegar quando instruções aplicáveis do projeto ou de habilidades solicitarem isso.

Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

No ChatGPT Work, escolha um modelo e um nível de inteligência no Editor. Os níveis de inteligência disponíveis podem incluir Leve, Médio, Alto, Extra alto e Max, dependendo do modelo selecionado. Ultra está disponível apenas para contas qualificadas e modelos compatíveis. Esse nível usa raciocínio máximo e permite que o ChatGPT delegue proativamente tarefas adequadas a subagentes.

Nos outros níveis de inteligência, solicite explicitamente subagentes quando quiser delegar o trabalho em paralelo.

Se você não configurar um modelo de subagente nem model_reasoning_effort, o subagente herdará o modelo e o esforço de raciocínio do agente pai. Se uma solicitação explícita de criação de agente ou um valor padrão de [agents] selecionar um modelo sem um esforço de raciocínio explícito ou configurado, o subagente usará o esforço de raciocínio padrão desse modelo. Para equilibrar inteligência, velocidade e preço em cada tarefa, solicite no prompt um modelo ou um esforço de raciocínio específico, configure os valores padrão de [agents] em config.toml ou defina model e model_reasoning_effort diretamente no arquivo do agente personalizado. Por exemplo, use gpt-5.6-terra em varreduras rápidas ou uma configuração de gpt-5.6 com maior esforço para raciocínios mais exigentes.

Escolha do modelo

• gpt-5.6: Comece por aqui para agentes exigentes. É a opção mais eficaz para trabalhos ambíguos e com várias etapas que exigem planejamento, uso de ferramentas, validação e execução até o fim em um contexto mais amplo.
• gpt-5.6-terra: Use para agentes que priorizam velocidade e eficiência em vez de profundidade, como em exploração, varreduras com uso intensivo de leitura, revisão de arquivos grandes ou processamento de documentos auxiliares. Funciona bem para agentes executados em paralelo que retornam resultados sintetizados ao agente principal.
• gpt-5.6-luna: Use para agentes rápidos e de escopo delimitado que lidam com tarefas bem definidas, repetitivas ou de grande volume.

Esforço de raciocínio (model_reasoning_effort)

• ultra: Use para o raciocínio mais profundo quando o modelo selecionado oferecer suporte a esse nível.
• max e xhigh: Use para raciocínios especialmente exigentes quando o modelo selecionado oferecer suporte a esses níveis.
• high: Use quando um agente precisar analisar uma lógica complexa, verificar suposições ou lidar com casos extremos, como agentes de revisão ou especializados em segurança.
• medium: Uma configuração padrão equilibrada para a maioria dos agentes.
• low: Use quando a tarefa for simples e a velocidade for o mais importante.

Um esforço de raciocínio maior aumenta o tempo de resposta e o uso de tokens, mas pode melhorar a qualidade em trabalhos complexos. Para mais detalhes, consulte Modelos, Configuração básica e Referência de configuração.

Na maioria dos níveis de inteligência, o ChatGPT inicia agentes após uma solicitação direta. Com Ultra, o ChatGPT também pode delegar proativamente quando o trabalho em paralelo for útil.

As versões locais atuais do Codex iniciam agentes após uma solicitação direta ou uma instrução aplicável do projeto ou de uma habilidade.

I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

Abra Subagentes para ver as listas somente leitura Ativos e Concluídos . Selecione um subagente concluído para inspecionar seus detalhes e seu resultado. A barra lateral da Web informa a atividade dos subagentes, mas não oferece controles para interromper ou orientar um subagente específico.

• Abra uma thread de subagente pela atividade exibida na thread principal para inspecionar seu trabalho.
• Peça diretamente ao Codex para orientar um subagente em execução, interrompê-lo ou fechar threads de subagentes concluídos.

• Use /agent na CLI para alternar entre threads de agentes ativas e inspecionar a thread em andamento.
• Peça diretamente ao Codex para orientar um subagente em execução, interrompê-lo ou fechar threads de agentes concluídas.

• Quando o painel de agentes em segundo plano estiver disponível, expanda-o para inspecionar o status, interromper subagentes ativos ou abrir a thread de um subagente.
• Peça diretamente ao Codex para orientar um subagente em execução, interrompê-lo ou fechar threads concluídas de subagentes.

Os subagentes herdam sua política de Sandbox atual.

O ChatGPT Work executa subagentes em seu ambiente hospedado e não disponibiliza um Sandbox local do Codex nem controles do modo de aprovação. Os subagentes usam as ferramentas disponíveis no chat principal. As permissões de sites e conectores permanecem específicas de cada ferramenta.

Os subagentes herdam o modo de permissão selecionado abaixo do Editor. Escolha o modo de permissão do turno principal antes de pedir ao Codex para delegar o trabalho.

Em sessões interativas da CLI, solicitações de aprovação podem aparecer em threads inativas de agentes mesmo enquanto você visualiza a thread principal. A sobreposição de aprovação mostra o rótulo da thread de origem, e você pode pressionar o para abrir essa thread antes de aprovar, rejeitar ou responder à solicitação.

Em fluxos não interativos ou quando uma execução não consegue apresentar uma nova solicitação de aprovação, uma ação que exige nova aprovação falha, e o Codex retorna o erro ao fluxo de trabalho principal.

O Codex também reaplica as substituições ativas em tempo de execução do turno principal ao iniciar um agente filho. Isso inclui as opções de Sandbox e aprovação definidas de forma interativa durante a sessão, como alterações em /permissions ou --yolo, mesmo que o arquivo do agente personalizado selecionado defina padrões diferentes.

Os subagentes herdam o modo de permissão selecionado abaixo do Editor. Escolha o modo de permissão do turno principal antes de pedir ao Codex para delegar o trabalho.

Você também pode substituir a configuração de Sandbox de agentes personalizados específicos, por exemplo, configurando explicitamente um deles para operar em modo somente leitura.

Agentes personalizados

O Codex inclui agentes integrados:

• default: agente de uso geral usado como alternativa.
• worker: agente focado na execução de implementações e correções.
• explorer: agente de exploração da base de código, com uso intensivo de leitura.

Para definir seus próprios agentes personalizados, adicione arquivos TOML independentes em ~/.codex/agents/ para agentes pessoais ou em .codex/agents/ para agentes com escopo de projeto.

Cada arquivo define um agente personalizado. O Codex carrega esses arquivos como camadas de configuração para as sessões iniciadas, permitindo que os agentes personalizados substituam as mesmas configurações de uma sessão normal do Codex. Isso pode parecer mais complexo do que um manifesto dedicado ao agente, e o formato pode evoluir conforme a criação e o compartilhamento amadurecem.

Cada arquivo independente de agente personalizado deve definir:

• name
• description
• developer_instructions

Se um arquivo de agente personalizado definir model ou model_reasoning_effort, o valor no arquivo terá precedência. Antes de aplicar o arquivo, o Codex determina cada configuração a partir de um valor explícito de inicialização, seguido do padrão correspondente em [agents] e, por fim, do valor do agente principal. Se uma solicitação explícita de inicialização ou um padrão em [agents] selecionar um modelo e nenhum deles definir um esforço de raciocínio, o Codex usará o esforço padrão desse modelo. Um arquivo de agente personalizado que defina apenas model preserva esse esforço determinado anteriormente. Defina também model_reasoning_effort no arquivo se o modelo selecionado não oferecer suporte a esse esforço ou se você quiser um esforço diferente. Outras configurações da sessão, como sandbox_mode, mcp_servers e skills.config, são herdadas do agente principal quando o arquivo do agente personalizado as omite.

Configurações globais

As configurações globais de subagentes continuam em [agents] na sua configuração.

Observações:

• agents.enabled usa true por padrão. Defina como false para desativar as ferramentas multiagente.
• Se você não definir agents.max_concurrent_threads_per_session, o Codex escolherá o padrão. As configurações existentes podem continuar usando agents.max_threads como um alias legado.
• Valores explícitos de inicialização têm precedência sobre agents.default_subagent_model e agents.default_subagent_reasoning_effort.
• agents.interrupt_message usa true por padrão. Defina como false para omitir do contexto do agente a mensagem de interrupção visível para o modelo.
• Se o nome de um agente personalizado corresponder ao de um agente integrado, como explorer, o agente personalizado terá precedência.

Esquema do arquivo de agente personalizado

Você também pode incluir outras chaves compatíveis de config.toml em um arquivo de agente personalizado, como model, model_reasoning_effort, sandbox_mode, mcp_servers e skills.config.

O Codex identifica o agente personalizado pelo campo name. Fazer o nome do arquivo corresponder ao nome do agente é a convenção mais simples, mas o campo name é a referência definitiva.

Exemplos de agentes personalizados

Os melhores agentes personalizados têm escopo delimitado e diretrizes bem definidas. Atribua a cada agente uma função clara, um conjunto de ferramentas adequado a ela e instruções que o impeçam de assumir tarefas fora do escopo.

Exemplo 1: revisão de PR

Esse padrão divide a revisão entre três agentes personalizados, cada um com um foco específico:

• pr_explorer mapeia a base de código e reúne evidências.
• reviewer identifica riscos relacionados à correção do código, à segurança e aos testes.
• docs_researcher verifica a documentação do framework ou da API por meio de um servidor MCP dedicado.

Configuração do projeto (.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 8

.codex/agents/pr-explorer.toml:

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
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 the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""

.codex/agents/reviewer.toml:

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""

.codex/agents/docs-researcher.toml:

name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not make code changes.
"""

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Essa configuração funciona bem com prompts como:

Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

Exemplo 2: depuração de integração de frontend

Esse padrão é útil para regressões de interface, fluxos instáveis no navegador ou bugs de integração que abrangem tanto o código do aplicativo quanto o produto em execução.

Configuração do projeto (.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 6

.codex/agents/code-mapper.toml:

name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Map the code that owns the failing UI flow.
Identify entry points, state transitions, and likely files before the worker starts editing.
"""

.codex/agents/browser-debugger.toml:

name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
Use browser tooling for screenshots, console output, and network evidence.
Do not edit application code.
"""

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20

.codex/agents/ui-fixer.toml:

name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
developer_instructions = """
Own the fix once the issue is reproduced.
Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
"""

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false

Essa configuração funciona bem com prompts como:

Investigate why the settings modal fails to save. Have browser_debugger reproduce it, code_mapper trace the responsible code path, and ui_fixer implement the smallest fix once the failure mode is clear.