Subagentes

O ChatGPT Work e o Codex podem executar fluxos de trabalho com subagentes ao iniciar agentes especializados em paralelo e, em seguida, reunir os respetivos resultados numa única resposta. Isto pode ser particularmente útil para tarefas complexas altamente paralelizáveis, como a exploração de bases de código ou a implementação de um plano de funcionalidades com várias etapas.

Nos clientes Codex locais, também pode definir agentes personalizados com diferentes configurações de modelo e instruções para diferentes tarefas.

Disponibilidade

ChatGPT Work na Web

O ChatGPT Work disponibiliza fluxos de trabalho com subagentes e a respetiva atividade às contas elegíveis.

Clientes Codex locais

As versões atuais do Codex ativam, por predefinição, os fluxos de trabalho com subagentes. A atividade dos subagentes é apresentada na aplicação ChatGPT para computador, no Codex CLI e na extensão para IDE.

Uma vez que cada subagente realiza o seu próprio trabalho com o modelo e as ferramentas, os fluxos de trabalho com subagentes consomem mais tokens do que execuções comparáveis com um único agente.

ChatGPT Work na Web

No ChatGPT Work, peça ao ChatGPT para delegar trabalho independente a subagentes. Os agentes são executados no ambiente alojado do ChatGPT, e a conversa apresenta a respetiva atividade e os resultados. Na maioria dos níveis de inteligência, peça explicitamente a delegação. Com o Ultra, o ChatGPT pode delegar trabalho proativamente quando agentes paralelos melhorarem substancialmente a velocidade ou a qualidade.

Aplicação ChatGPT para computador

Numa conversa da aplicação, peça ao Codex para delegar partes independentes do trabalho a subagentes. As versões locais atuais do Codex delegam quando o solicita diretamente ou quando instruções AGENTS.md aplicáveis ou instruções de uma skill o pedem. A aplicação apresenta cada thread de subagente, para que possa inspecionar o respetivo trabalho e o resumo devolvido à conversa principal.

Codex CLI

Numa sessão interativa da CLI, peça ao Codex para utilizar subagentes. O Codex também pode seguir instruções AGENTS.md aplicáveis ou instruções de uma skill que peçam delegação. Utilize /agent para inspecionar e alternar entre threads de agentes enquanto são executados. A thread principal reúne os resultados dos subagentes na sua resposta final.

Extensão para IDE

Numa conversa do IDE, peça ao Codex para delegar partes independentes do trabalho a subagentes. O Codex também pode seguir instruções AGENTS.md aplicáveis ou instruções de uma skill que peçam delegação. Quando a interface de agentes em segundo plano está disponível, os subagentes ativos aparecem acima da caixa de composição. Expanda o painel para ver o respetivo estado, parar todos os subagentes ativos ou abrir a thread de um subagente específico.

Por que motivo os fluxos de trabalho com subagentes são úteis

Mesmo com janelas de contexto grandes, os modelos têm limites. Se sobrecarregar a conversa principal (onde define requisitos, restrições e decisões) com resultados intermédios ruidosos, como notas de exploração, registos de testes, rastreios da pilha e resultados de comandos, a sessão pode tornar-se menos fiável ao longo do tempo.

Esta situação é frequentemente descrita como:

• Poluição do contexto: as informações úteis ficam ocultas por resultados intermédios ruidosos.
• Degradação do contexto: o desempenho piora à medida que a conversa se enche de detalhes menos relevantes.

Para obter informações de contexto, consulte o artigo da Chroma sobre degradação do contexto.

Os fluxos de trabalho com subagentes ajudam ao retirar o trabalho ruidoso da thread principal:

• Mantenha o agente principal concentrado nos requisitos, nas decisões e nos resultados finais.
• Execute subagentes especializados em paralelo para exploração, testes ou análise de registos.
• Devolva resumos dos subagentes em vez de resultados intermédios em bruto.

Também podem poupar tempo quando o trabalho pode ser executado de forma independente em paralelo e tornam tarefas de maior dimensão mais fáceis de gerir ao dividi-las em partes delimitadas. Por exemplo, o Codex pode dividir a análise de um documento com vários milhões de tokens em problemas mais pequenos e devolver conclusões sintetizadas à thread principal.

Como ponto de partida, utilize agentes paralelos para tarefas com utilização intensiva de leitura, como exploração, testes, triagem e síntese. Tenha mais cuidado com fluxos de trabalho paralelos com utilização intensiva de escrita, pois vários agentes a editar código em simultâneo podem criar conflitos e aumentar o esforço de coordenação.

Termos fundamentais

O Codex utiliza alguns termos relacionados nos fluxos de trabalho com subagentes:

• Fluxo de trabalho com subagentes: um fluxo de trabalho no qual o Codex executa agentes em paralelo e combina os respetivos resultados.
• Subagente: um agente delegado que o Codex inicia para tratar de uma tarefa específica.
• Thread de agente: a thread na qual um subagente realiza o seu trabalho. Os clientes compatíveis permitem abrir estas threads para inspecionar o progresso ou os resultados.

Acionar fluxos de trabalho com subagentes

ChatGPT Work na Web

Na maioria dos níveis de inteligência, peça diretamente subagentes ou trabalho com agentes em paralelo. O Ultra permite a delegação proativa, pelo que o ChatGPT pode delegar trabalho independente adequado sem um pedido separado.

Clientes Codex locais

Peça diretamente subagentes ou trabalho com agentes em paralelo. O Codex também pode delegar quando instruções aplicáveis do projeto ou de uma skill o pedem.

Na prática, o acionamento manual significa utilizar instruções diretas, como «inicie dois agentes», «delegue este trabalho em paralelo» ou «utilize um agente por ponto». Os fluxos de trabalho com subagentes consomem mais tokens do que execuções comparáveis com um único agente, porque cada subagente realiza o seu próprio trabalho com o modelo e as ferramentas.

Um bom pedido para subagentes deve explicar como dividir o trabalho, se o Codex deve aguardar por todos os agentes antes de continuar e que resumo ou resultado deve devolver.

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.

Escolher modelos e raciocínio

Agentes diferentes necessitam de definições de modelo e de raciocínio diferentes.

ChatGPT Work na Web

No ChatGPT Work, escolha um modelo e um nível de inteligência na caixa de composição. Os níveis de inteligência disponíveis podem incluir Light, Medium, High, Extra High e Max, consoante o modelo selecionado. O Ultra está disponível apenas para contas elegíveis e modelos compatíveis. Utiliza o raciocínio máximo e permite ao ChatGPT delegar proativamente trabalho adequado a subagentes.

Nos outros níveis de inteligência, peça explicitamente subagentes quando pretender que o trabalho seja delegado em paralelo.

Clientes Codex locais

Se não fixar um modelo ou model_reasoning_effort, o Codex pode escolher uma configuração que equilibre inteligência, velocidade e preço para a tarefa. Pode privilegiar gpt-5.6-terra para análises rápidas ou uma configuração gpt-5.6 com maior esforço para raciocínios mais exigentes. Quando pretender um controlo mais rigoroso, oriente essa escolha no seu pedido ou defina model e model_reasoning_effort diretamente no ficheiro do agente.

Escolha do modelo

• gpt-5.6: comece por aqui para agentes exigentes. É a opção mais robusta para trabalho ambíguo e com várias etapas que exija planeamento, utilização de ferramentas, validação e acompanhamento num contexto mais amplo.
• gpt-5.6-terra: utilize para agentes que privilegiem a velocidade e a eficiência em detrimento da profundidade, como exploração, análises com utilização intensiva de leitura, revisão de ficheiros grandes ou processamento de documentos de apoio. É adequado para agentes paralelos que devolvem resultados sintetizados ao agente principal.
• gpt-5.6-luna: utilize para agentes rápidos e com âmbito restrito que tratem de trabalho claro, repetível ou de grande volume.

Esforço de raciocínio (model_reasoning_effort)

• ultra: utilize para o raciocínio mais profundo quando o modelo selecionado o suportar.
• max e xhigh: utilize para raciocínios especialmente exigentes quando o modelo selecionado suportar estes níveis.
• high: utilize quando um agente necessitar de seguir lógica complexa, verificar pressupostos ou analisar casos extremos (por exemplo, agentes de revisão ou orientados para a segurança).
• medium: uma predefinição equilibrada para a maioria dos agentes.
• low: utilize quando a tarefa for simples e a velocidade for a principal prioridade.

Um maior esforço de raciocínio aumenta o tempo de resposta e a utilização de tokens, mas pode melhorar a qualidade em trabalhos complexos. Para obter detalhes, consulte Modelos, Noções básicas de configuração e Referência de configuração.

Orquestração e controlos de threads

O ChatGPT ou o Codex trata da orquestração entre agentes, incluindo iniciar novos subagentes, encaminhar instruções de seguimento, aguardar pelos resultados e fechar threads de agentes.

Quando estão em execução muitos agentes, o Codex aguarda até que todos os resultados solicitados estejam disponíveis e, em seguida, devolve uma resposta consolidada.

ChatGPT Work na Web

Na maioria dos níveis de inteligência, o ChatGPT inicia agentes após um pedido direto. Com o Ultra, o ChatGPT também pode delegar proativamente quando o trabalho em paralelo é útil.

Clientes Codex locais

As versões locais atuais do Codex iniciam agentes após um pedido direto ou uma instrução aplicável do projeto ou de uma skill.

Para ver este processo em funcionamento, experimente o seguinte pedido no seu projeto:

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

Gerir subagentes

ChatGPT Work na Web

Abra Subagentes para ver as listas só de leitura Ativos e Concluídos. Selecione um subagente concluído para inspecionar os respetivos detalhes e resultado. A barra lateral da Web apresenta a atividade dos subagentes; não disponibiliza controlos para parar ou orientar um subagente individual.

Aplicação ChatGPT para computador

• Abra uma thread de subagente a partir da atividade apresentada na thread principal para inspecionar o respetivo trabalho.
• Peça diretamente ao Codex para orientar um subagente em execução, pará-lo ou fechar threads de subagentes concluídas.

Codex CLI

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

Extensão para IDE

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

Aprovações e controlos do sandbox

Clientes Codex locais

Os subagentes herdam a política de sandbox atual.

ChatGPT Work na Web

O ChatGPT Work executa subagentes no respetivo ambiente alojado e não disponibiliza um sandbox local do Codex nem um controlo do modo de aprovação. Os subagentes utilizam as ferramentas disponíveis na conversa principal. As permissões de sites e conectores continuam a ser específicas de cada ferramenta.

Aplicação ChatGPT para computador

Os subagentes herdam o modo de permissões selecionado por baixo da caixa de composição. Escolha o modo de permissões para o turno principal antes de pedir ao Codex para delegar trabalho.

Codex CLI

Em sessões interativas da CLI, os pedidos de aprovação podem surgir a partir de threads de agentes inativas, mesmo enquanto consulta a thread principal. A sobreposição de aprovação apresenta a etiqueta da thread de origem, e pode premir o para abrir essa thread antes de aprovar, rejeitar ou responder ao pedido.

Em fluxos não interativos, ou sempre que uma execução não consiga apresentar uma nova aprovação, uma ação que necessite de nova aprovação falha, e o Codex comunica o erro ao fluxo de trabalho principal.

O Codex também reaplica as substituições de runtime ativas do turno principal quando inicia um agente subordinado. Isto inclui as opções de sandbox e aprovação que definir interativamente durante a sessão, como alterações de /permissions ou --yolo, mesmo que o ficheiro do agente personalizado selecionado defina predefinições diferentes.

Extensão para IDE

Os subagentes herdam o modo de permissões selecionado por baixo da caixa de composição. Escolha o modo de permissões para o turno principal antes de pedir ao Codex para delegar trabalho.

Também pode substituir a configuração do sandbox para agentes personalizados individuais, por exemplo, ao marcar explicitamente um para trabalhar em modo só de leitura.

Agentes personalizados

O Codex inclui agentes integrados:

• default: agente de recurso para fins gerais.
• worker: agente orientado para a execução, destinado a implementações e correções.
• explorer: agente de exploração da base de código com utilização intensiva de leitura.

Para definir os seus próprios agentes personalizados, adicione ficheiros TOML autónomos em ~/.codex/agents/ para agentes pessoais ou em .codex/agents/ para agentes ao nível do projeto.

Cada ficheiro define um agente personalizado. O Codex carrega estes ficheiros como camadas de configuração para sessões iniciadas, pelo que os agentes personalizados podem substituir as mesmas definições que uma configuração de sessão normal do Codex. Esta abordagem pode parecer mais complexa do que um manifesto de agente dedicado, e o formato poderá evoluir à medida que a criação e a partilha amadurecem.

Cada ficheiro autónomo de agente personalizado tem de definir:

• name
• description
• developer_instructions

Se um ficheiro de agente personalizado definir model ou model_reasoning_effort, prevalece o valor do ficheiro. Caso contrário, o Codex resolve cada definição de forma independente: um valor explícito de iniciação, seguido da predefinição [agents] correspondente e, depois, do valor do agente principal. Se uma iniciação selecionar um modelo diferente e não existir um esforço explícito nem configurado, o Codex utiliza o esforço predefinido desse modelo. Outras definições de sessão, como sandbox_mode, mcp_servers e skills.config, são herdadas do agente principal quando o ficheiro do agente personalizado as omite.

Definições globais

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

Notas:

• agents.enabled tem como valor predefinido true. Defina-o como false para desativar as ferramentas multiagente.
• Se deixar agents.max_concurrent_threads_per_session por definir, o Codex escolhe o valor predefinido. As configurações existentes podem continuar a utilizar agents.max_threads como alias legado.
• Os valores explícitos de iniciação substituem agents.default_subagent_model e agents.default_subagent_reasoning_effort.
• agents.interrupt_message tem como valor predefinido true. Defina-o 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 incorporado, como explorer, o seu agente personalizado tem precedência.

Esquema do ficheiro de agente personalizado

Também pode incluir outras chaves config.toml suportadas num ficheiro de agente personalizado, como model, model_reasoning_effort, sandbox_mode, mcp_servers e skills.config.

O Codex identifica o agente personalizado pelo respetivo campo name. Fazer corresponder o nome do ficheiro ao nome do agente é a convenção mais simples, mas o campo name é a fonte definitiva.

Exemplos de agentes personalizados

Os melhores agentes personalizados são específicos e têm uma abordagem definida. Atribua a cada um uma função clara, uma superfície de ferramentas adequada a essa função e instruções que impeçam o desvio para tarefas adjacentes.

Exemplo 1: revisão de PR

Este padrão divide a revisão entre três agentes personalizados especializados:

• pr_explorer mapeia a base de código e recolhe evidências.
• reviewer procura riscos de correção, segurança e testes.
• docs_researcher consulta a documentação da framework ou da API através 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"

Esta configuração funciona bem para pedidos 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 da integração de frontend

Este padrão é útil para regressões da IU, fluxos instáveis no browser ou erros de integração que abrangem o código da aplicação e 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

Esta configuração funciona bem para pedidos 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.