Subagentes
Utilize subagentes no ChatGPT e no Codex e configure agentes Codex personalizados
- Aplicação de computador do ChatGPT Projetos, ficheiros e tarefas mais longas no computador.
- ChatGPT na Web Conversas, projetos e Work no seu navegador.
- Codex CLI O Codex no seu terminal.
- Extensão do Codex para IDE O Codex no seu editor.
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
O ChatGPT Work disponibiliza fluxos de trabalho com subagentes e a respetiva atividade às contas elegíveis.
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.
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 mostra a sua atividade e os resultados. Na maioria dos níveis de inteligência, peça a delegação explicitamente. Com Ultra, o ChatGPT pode delegar trabalho proativamente quando agentes em paralelo melhorarem substancialmente a velocidade ou a qualidade.
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.
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
/subagents 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.
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
Na maioria dos níveis de inteligência, peça subagentes ou trabalho de agentes em paralelo diretamente. Ultra permite a delegação proativa, pelo que o ChatGPT pode delegar trabalho independente adequado sem um pedido separado.
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.
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.
Se não configurar um modelo de subagente ou model_reasoning_effort, o
subagente herda o modelo e o esforço de raciocínio do agente principal. Se um pedido explícito
de criação ou uma predefinição de [agents] selecionar um modelo sem um
esforço de raciocínio explícito ou configurado, o subagente utiliza o esforço de raciocínio
predefinido desse modelo. Para equilibrar inteligência, velocidade e preço em cada tarefa,
peça um modelo ou esforço de raciocínio específico no seu pedido,
configure as predefinições de [agents] em config.toml ou defina model e
model_reasoning_effort diretamente no ficheiro do agente personalizado.
Por exemplo, utilize gpt-6-luna para análises rápidas ou uma configuração de gpt-6.1-sol com maior esforço para raciocínios mais exigentes.
Escolha do modelo
gpt-6.1-sol: Comece por este modelo para agentes com tarefas exigentes. Utilize-o para trabalho ambíguo, com várias etapas, que exija planeamento, utilização de ferramentas, validação e acompanhamento até à conclusão num contexto mais amplo.gpt-6-luna: Utilize para agentes rápidos, com âmbito restrito, que realizem trabalho claro, repetível ou de grande volume.
Esforço de raciocínio (model_reasoning_effort)
Para GPT-6.1 Sol, utilize um esforço de raciocínio suportado pelo seu cliente e pelo modelo
selecionado. Para definições explícitas do modelo, comece com high para GPT-6 Luna ou low
para GPT-6 Astra. Ajuste em função da tarefa, utilizando um nível suportado pelo modelo selecionado.
ultra: Utilize para o raciocínio mais aprofundado quando o modelo selecionado suportar este nível.maxexhigh: Utilize para raciocínios especialmente exigentes quando o modelo selecionado suportar estes níveis.high: Utilize quando um agente precisar de seguir uma lógica complexa, verificar pressupostos ou analisar casos limite (por exemplo, agentes de revisão ou focados em segurança).medium: Equilibra velocidade e profundidade.low: Utilize quando a tarefa for simples e a velocidade for o mais importante.
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.
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.
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 codeGerir subagentes
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.
- 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.
- Utilize
/subagentsna CLI para alternar entre as conversas de agentes ativas e inspecionar a conversa em curso. - Peça diretamente ao Codex para orientar um subagente em execução, pará-lo ou fechar conversas de agentes concluídas.
- Quando o painel de agentes em segundo plano estiver disponível, expanda-o para inspecionar o estado, parar subagentes ativos ou abrir a conversa de um subagente.
- Peça diretamente ao Codex para orientar um subagente em execução, pará-lo ou fechar conversas de subagentes concluídas.
Aprovações e controlos do sandbox
Os subagentes herdam a política de sandbox atual.
O ChatGPT Work executa subagentes no seu ambiente alojado e não disponibiliza uma 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.
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.
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.
Os subagentes herdam as definições atuais de sandbox e de aprovação do turno principal,
incluindo alterações efetuadas com /permissions ou --yolo. Um ficheiro de agente personalizado
não pode substituir essas definições.
Os subagentes herdam o modo de permissões selecionado abaixo do campo de composição. Escolha o modo de permissões do turno principal antes de pedir ao Codex para delegar trabalho.
Defina os controlos de sandbox e de aprovação na sessão principal. As instruções de agentes personalizados podem pedir a um agente que evite alterações, mas não criam uma sandbox separada 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. Os agentes personalizados podem alterar as definições do modelo e as instruções ou desativar capacidades suportadas. Herdam as permissões, o fornecedor e os MCP servers da sessão principal; um ficheiro de agente personalizado não pode substituir essas definições.
Cada ficheiro autónomo de agente personalizado tem de definir:
namedescriptiondeveloper_instructions
Se um ficheiro de agente personalizado definir model ou model_reasoning_effort, o valor no
ficheiro tem precedência. Antes de aplicar o ficheiro, o Codex determina cada definição
a partir de um valor explícito de criação, depois do valor predefinido correspondente de [agents] e, por fim,
do valor da sessão principal. Se um pedido explícito de criação ou um valor predefinido de [agents]
selecionar um modelo e nenhum dos dois fornecer um esforço de raciocínio, o Codex utiliza
o esforço predefinido desse modelo. Um ficheiro de agente personalizado que defina apenas model
preserva este esforço previamente determinado. Defina também model_reasoning_effort no
ficheiro se o modelo selecionado não suportar esse esforço ou se pretender um
esforço diferente. As competências são herdadas da sessão principal e um agente personalizado pode desativar
competências individuais com skills.config.
Definições globais
As definições globais dos subagentes continuam em [agents] na sua configuração.
| Campo | Tipo | Obrigatório | Finalidade |
|---|---|---|---|
agents.enabled |
boolean | Não | Ativar ou desativar as ferramentas multiagente. |
agents.max_concurrent_threads_per_session |
number | Não | Limitar os threads de agentes iniciados abertos em simultâneo, excluindo o principal. |
agents.default_subagent_model |
string | Não | Definir o modelo predefinido para os agentes iniciados. |
agents.default_subagent_reasoning_effort |
string | Não | Definir o esforço de raciocínio predefinido para os agentes iniciados. |
agents.interrupt_message |
boolean | Não | Registar uma mensagem visível para o modelo quando o turno de um agente é interrompido. |
Notas:
agents.enabledtem como valor predefinidotrue. Defina-o comofalsepara desativar as ferramentas multiagente.- Se deixar
agents.max_concurrent_threads_per_sessionpor definir, o Codex escolhe o valor predefinido. As configurações existentes podem continuar a utilizaragents.max_threadscomo alias legado. - Os valores explícitos de iniciação substituem
agents.default_subagent_modeleagents.default_subagent_reasoning_effort. agents.interrupt_messagetem como valor predefinidotrue. Defina-o comofalsepara 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
| Campo | Tipo | Obrigatório | Finalidade |
|---|---|---|---|
name |
string | Sim | Nome de agente que o Codex utiliza ao iniciar ou referir este agente. |
description |
string | Sim | Orientação destinada a pessoas sobre quando o Codex deve utilizar este agente. |
developer_instructions |
string | Sim | Instruções principais que definem o comportamento do agente. |
Utilize model, model_reasoning_effort, model_reasoning_summary e
model_verbosity para personalizar o comportamento do modelo.
Consulte a referência de configuração para conhecer os
valores aceites.
Para reduzir as capacidades de um agente personalizado, defina as chaves de funcionalidades suportadas como false:
features.shell_tool, features.apps, features.plugins,
features.memories ou features.request_permissions_tool. Desative competências
individuais com skills.config ou competências incluídas com
skills.bundled.enabled = false. Defina skills.include_instructions = false para
omitir o bloco automático de instruções de competências. Os requisitos geridos continuam a aplicar-se.
Outras definições da sessão, incluindo sandbox_mode, approval_policy,
model_provider e mcp_servers, não substituem a configuração da sessão principal
quando incluídas num ficheiro de agente personalizado. O nível de serviço também segue a preferência
da sessão de raiz. Configure os MCP servers na sessão principal para que o agente
os possa utilizar.
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.
Os exemplos utilizam GPT-6.1 Sol quando a conta com que iniciou sessão ou o espaço de trabalho tem acesso. Se não estiver disponível, escolha um modelo que possa utilizar.
Exemplo 1: revisão de PR
Este padrão divide a revisão entre três agentes personalizados especializados:
pr_explorermapeia a base de código e recolhe evidências.reviewerprocura riscos de correção, segurança e testes.docs_researcherconsulta a documentação da framework ou da API através de um MCP server 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:
name = "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.
"""
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
[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:
name = "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 = falseEsta 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.