Subagentes

O ChatGPT Work disponibiliza fluxos de trabalho com subagentes para contas elegíveis e permite acompanhar a atividade desses agentes.

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

No ChatGPT Work, peça ao ChatGPT que delegue tarefas independentes a subagentes. Os agentes são executados no ambiente hospedado do ChatGPT, e o chat mostra suas atividades e resultados. Na maioria dos níveis de inteligência, peça explicitamente que o ChatGPT delegue as tarefas. No nível Ultra, o ChatGPT pode delegar tarefas por iniciativa própria quando o uso de agentes em paralelo puder reduzir significativamente o tempo de execução ou melhorar significativamente a qualidade dos resultados.

Em um chat do aplicativo, peça ao Codex que delegue partes independentes do trabalho a subagentes. Nas versões locais atuais, o Codex delega tarefas quando você pede diretamente ou quando as instruções aplicáveis de um arquivo AGENTS.md ou de uma habilidade solicitam a delegação. O aplicativo exibe a conversa de cada subagente para que você possa examinar o trabalho realizado e o resumo enviado ao chat principal.

Em uma sessão interativa da CLI, peça ao Codex que use subagentes. O Codex também pode seguir instruções aplicáveis de um arquivo AGENTS.md ou de uma habilidade que solicitem a delegação. Use /subagents para examinar as conversas dos agentes e alternar entre elas durante a execução. A conversa principal reúne os resultados dos subagentes na resposta final.

Em um chat da IDE, peça ao Codex que delegue partes independentes do trabalho a subagentes. O Codex também pode seguir instruções aplicáveis de um arquivo AGENTS.md ou de uma habilidade que solicitem a delegação. Quando a interface de agentes em segundo plano está disponível, os subagentes ativos aparecem acima do editor de mensagens. Expanda o painel para ver o status dos subagentes, interromper todos os que estão ativos ou abrir a conversa de um deles.

Na maioria dos níveis de inteligência, peça diretamente que o ChatGPT use subagentes ou execute agentes em paralelo. O nível Ultra permite a delegação por iniciativa do ChatGPT, que pode distribuir tarefas independentes adequadas sem que você precise fazer um pedido separado.

Peça diretamente que o Codex use subagentes ou execute agentes em paralelo. O Codex também pode delegar tarefas quando as instruções aplicáveis do projeto ou de uma habilidade solicitam a delegação.

No ChatGPT Work, escolha o modelo e o nível de inteligência no editor de mensagens. Dependendo do modelo selecionado, os níveis disponíveis podem incluir Leve, Médio, Alto, Extra alto e Max. O nível Ultra está disponível apenas para contas elegíveis e modelos compatíveis. Ele usa o esforço máximo de raciocínio e permite que o ChatGPT delegue tarefas adequadas a subagentes por iniciativa própria.

Nos demais níveis de inteligência, peça explicitamente que o ChatGPT use subagentes quando quiser delegar tarefas em paralelo.

Se você não configurar o modelo do subagente nem model_reasoning_effort, o subagente herdará o modelo e o esforço de raciocínio do agente pai. Se o pedido de criação especificar um modelo ou um valor padrão em [agents] selecionar um modelo, e não houver esforço de raciocínio especificado ou configurado, o subagente usará o esforço padrão desse modelo. Para equilibrar inteligência, velocidade e custo em cada tarefa, solicite um modelo ou esforço de raciocínio específico no prompt, 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-6-luna para verificações rápidas ou configure gpt-6.1-sol com um esforço maior para tarefas que exigem raciocínio mais aprofundado.

Escolha do modelo

• gpt-6.1-sol: comece com este modelo para agentes que executam tarefas exigentes. Use-o em trabalhos com várias etapas e requisitos ambíguos que exijam planejamento, uso de ferramentas, validação e acompanhamento até a conclusão em um contexto mais amplo.
• gpt-6-luna: use para agentes rápidos com escopo delimitado que executam tarefas bem definidas, repetíveis ou em grande volume.

Esforço de raciocínio (model_reasoning_effort)

Para o GPT-6.1 Sol, use um esforço de raciocínio compatível com o cliente e o modelo selecionado. Ao configurar o modelo explicitamente, comece com high para o GPT-6 Luna ou low para o GPT-6 Astra. Ajuste o esforço de acordo com a tarefa, usando um nível compatível com o modelo selecionado.

• ultra: use para obter o raciocínio mais aprofundado, se o modelo selecionado oferecer suporte a esse nível.
• max e xhigh: use para tarefas que exigem um esforço de raciocínio especialmente alto, se o modelo selecionado oferecer suporte a esses níveis.
• high: use quando um agente precisar acompanhar uma lógica complexa, verificar premissas ou analisar casos extremos (por exemplo, agentes de revisão ou de segurança).
• medium: equilibra velocidade e profundidade.
• low: use quando a tarefa for simples e a velocidade for a prioridade.

Um esforço de raciocínio maior aumenta o tempo de resposta e o consumo de tokens, mas pode melhorar a qualidade dos resultados em tarefas complexas. Para mais detalhes, consulte Modelos, Noções básicas de configuração e Referência de configuração.

Na maioria dos níveis de inteligência, o ChatGPT inicia agentes após um pedido direto. No nível Ultra, o ChatGPT também pode delegar tarefas por iniciativa própria quando for útil executá-las em paralelo.

Nas versões locais atuais, o Codex inicia agentes após um pedido direto ou quando uma instrução aplicável do projeto ou de uma habilidade solicita isso.

Abra Subagentes para ver as listas Ativos e Concluídos, ambas somente leitura. Selecione um subagente que já terminou para examinar os detalhes e o resultado. A barra lateral da versão Web mostra a atividade dos subagentes, mas não oferece controles para interromper ou orientar um subagente individualmente.

• Na atividade exibida na conversa principal, abra a conversa de um subagente para examinar seu trabalho.
• Peça diretamente ao Codex que oriente ou interrompa um subagente em execução ou que encerre conversas de subagentes que já terminaram.

Report checklistPresentation checkliststarted working

• Use /subagents na CLI para alternar entre as conversas dos agentes ativos e examinar a conversa em andamento.
• Peça diretamente ao Codex que oriente ou interrompa um subagente em execução ou que encerre conversas de agentes que já terminaram.

• Quando o painel de agentes em segundo plano estiver disponível, expanda-o para consultar o status, interromper subagentes ativos ou abrir a conversa de um subagente.
• Peça diretamente ao Codex que oriente ou interrompa um subagente em execução ou que encerre conversas de subagentes que já terminaram.

Os subagentes herdam a política de sandbox atual.

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

Os subagentes herdam o modo de permissão selecionado abaixo do editor de mensagens. Escolha o modo de permissão do turno do agente pai antes de pedir ao Codex que delegue tarefas.

Em sessões interativas da CLI, você pode receber solicitações de aprovação vindas de conversas inativas de agentes mesmo enquanto visualiza a conversa principal. O painel de aprovação identifica a conversa de origem. Pressione o para abri-la antes de aprovar, rejeitar ou responder à solicitação.

Em fluxos não interativos ou sempre que não for possível exibir uma nova solicitação de aprovação durante a execução, a ação que exige essa aprovação falha e o Codex informa o erro ao fluxo de trabalho do agente pai.

Os subagentes herdam as configurações atuais de sandbox e aprovação do turno do agente pai, inclusive as alterações feitas com /permissions ou --yolo. Um arquivo de agente personalizado não pode substituir essas configurações.

Os subagentes herdam o modo de permissão selecionado abaixo do editor de mensagens. Escolha o modo de permissão do turno do agente pai antes de pedir ao Codex que delegue tarefas.

Defina os controles de sandbox e aprovação na sessão do agente pai. As instruções de um agente personalizado podem pedir que ele evite alterações, mas não criam um sandbox separado de somente leitura.

Agentes personalizados

O Codex inclui os seguintes agentes integrados:

• default: agente de uso geral usado quando nenhum agente mais específico é selecionado.
• worker: agente voltado à execução de tarefas de implementação e correção.
• explorer: agente que explora a base de código principalmente por meio de leitura.

Para definir seus próprios agentes personalizados, adicione arquivos TOML individuais em ~/.codex/agents/ para agentes pessoais ou em .codex/agents/ para agentes específicos de um projeto.

Cada arquivo define um agente personalizado. Agentes personalizados podem alterar configurações de modelo e instruções ou desabilitar recursos compatíveis. Eles herdam as permissões, o provedor e os servidores MCP do agente pai. O arquivo de um agente personalizado não pode substituir essas configurações.

Cada arquivo de agente personalizado deve definir:

• name
• description
• developer_instructions

Se o arquivo de um agente personalizado definir model ou model_reasoning_effort, o valor do arquivo terá precedência. Antes de aplicar o arquivo, o Codex determina o valor de cada configuração nesta ordem: primeiro, o valor especificado no pedido de criação do agente, depois, o valor padrão correspondente em [agents] e, por fim, o valor do agente pai. Se o pedido de criação ou um valor padrão em [agents] selecionar um modelo, mas nenhum dos dois especificar o esforço de raciocínio, o Codex usará o esforço padrão desse modelo. Um arquivo de agente personalizado que define apenas model preserva o 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 usar outro. Os subagentes herdam as habilidades do agente pai, e um agente personalizado pode desabilitar habilidades específicas com skills.config.

Configurações globais

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

Observações:

• O valor padrão de agents.enabled é true. Defina-o como false para desabilitar as ferramentas para trabalhar com vários agentes.
• Se você não definir agents.max_concurrent_threads_per_session, o Codex escolherá o valor padrão. Configurações existentes podem continuar usando agents.max_threads como nome alternativo para manter a compatibilidade com versões anteriores.
• Os valores especificados no pedido de criação do agente têm precedência sobre agents.default_subagent_model e agents.default_subagent_reasoning_effort.
• O valor padrão de agents.interrupt_message é true. Defina-o como false para omitir do contexto do agente a mensagem de interrupção que o modelo receberia.
• Se um agente personalizado tiver o mesmo nome que um agente integrado, como explorer, o agente personalizado terá precedência.

Schema do arquivo de agente personalizado

Use model, model_reasoning_effort, model_reasoning_summary e model_verbosity para personalizar o comportamento do modelo. Consulte a referência de configuração para saber quais valores são aceitos.

Para restringir os recursos de um agente personalizado, defina como false as chaves de recursos compatíveis: features.shell_tool, features.apps, features.plugins, features.memories ou features.request_permissions_tool. Desabilite habilidades específicas com skills.config ou as habilidades incluídas no pacote com skills.bundled.enabled = false. Defina skills.include_instructions = false para omitir o bloco de instruções de habilidades incluído automaticamente. Os requisitos gerenciados continuam em vigor.

Outras configurações de sessão, como sandbox_mode, approval_policy, model_provider e mcp_servers, não substituem a configuração do agente pai quando são incluídas no arquivo de um agente personalizado. O nível de serviço também segue a preferência da sessão raiz. Configure os servidores MCP na sessão do agente pai para que o agente personalizado possa usá-los.

O Codex identifica o agente personalizado pelo campo name. A convenção mais simples é dar ao arquivo o mesmo nome do agente, mas o que determina a identidade do agente é o campo name.

Exemplos de agentes personalizados

Os agentes personalizados mais eficazes têm escopo delimitado e critérios claros de atuação. Atribua a cada agente uma tarefa bem definida, um conjunto de ferramentas adequado à tarefa e instruções que o mantenham dentro desse escopo.

Os exemplos usam o GPT-6.1 Sol quando a conta com a qual você entrou ou o seu espaço de trabalho tem acesso. Caso ele não esteja disponível, escolha um modelo ao qual você tenha acesso.

Exemplo 1: revisão de pull request

Neste exemplo, três agentes personalizados dividem a revisão, cada um com uma função específica:

• pr_explorer mapeia a base de código e reúne evidências.
• reviewer identifica riscos relacionados ao funcionamento correto do código, à segurança e aos testes.
• docs_researcher consulta 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

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

.codex/agents/pr-explorer.toml:

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
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:

1
2
3
4
5
6
7
8
9
10name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
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-6-luna"
model_reasoning_effort = "high"
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.
"""

Essa configuração funciona bem com prompts como este:

Revise esta branch comparando-a com a main. Peça ao pr_explorer que mapeie os caminhos de execução afetados, ao reviewer que identifique riscos reais e ao docs_researcher que verifique as APIs do framework das quais a alteração depende.

Exemplo 2: depuração da integração do frontend

Essa divisão de tarefas é útil para investigar regressões na interface, fluxos que falham de forma intermitente no navegador ou bugs de integração que envolvem 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

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

.codex/agents/code-mapper.toml:

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

.codex/agents/browser-debugger.toml:

1
2
3
4
5
6
7
8
9name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
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.
"""

.codex/agents/ui-fixer.toml:

name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-6-luna"
model_reasoning_effort = "high"
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 este:

Investigue por que a janela modal de configurações não salva as alterações. Peça ao browser_debugger que reproduza a falha e ao code_mapper que rastreie o caminho de execução responsável. Assim que estiver claro como a falha ocorre, peça ao ui_fixer que implemente a menor correção possível.