Sous-agents
Utilisez des sous-agents dans ChatGPT et Codex, et configurez des agents Codex personnalisés
- Application de bureau ChatGPT Projets, fichiers et tâches plus longues sur ordinateur.
- ChatGPT sur le web Conversations, projets et Work dans votre navigateur.
- Codex CLI Codex dans votre terminal.
- Extension IDE Codex Codex dans votre éditeur.
ChatGPT Work et Codex peuvent exécuter des workflows de sous-agents en lançant des agents spécialisés en parallèle, puis en regroupant leurs résultats dans une seule réponse. Cela peut être particulièrement utile pour les tâches complexes hautement parallélisables, telles que l’exploration d’une base de code ou la mise en œuvre d’un plan de fonctionnalité en plusieurs étapes.
Dans les clients Codex locaux, vous pouvez également définir des agents personnalisés avec différentes configurations de modèle et instructions selon les tâches.
Disponibilité
ChatGPT Work présente les workflows de sous-agents et leur activité aux comptes éligibles.
Les versions actuelles de Codex activent les workflows de sous-agents par défaut. L’activité des sous-agents apparaît dans l’application de bureau ChatGPT, Codex CLI et l’extension IDE.
Comme chaque sous-agent effectue ses propres opérations avec le modèle et les outils, les workflows de sous-agents consomment davantage de jetons que des exécutions comparables avec un seul agent.
Dans ChatGPT Work, demandez à ChatGPT de déléguer des tâches indépendantes à des sous-agents. Les agents s’exécutent dans l’environnement hébergé de ChatGPT, et la conversation affiche leur activité et leurs résultats. À la plupart des niveaux d’intelligence, demandez la délégation explicitement. Avec Ultra, ChatGPT peut déléguer des tâches de manière proactive lorsque des agents travaillant en parallèle amélioreraient sensiblement la rapidité ou la qualité.
Dans une conversation de l’application, demandez à Codex de déléguer les parties indépendantes du travail à des
sous-agents. Les versions locales actuelles de Codex délèguent lorsque vous le demandez directement ou lorsque
les instructions AGENTS.md applicables ou celles d’un skill le demandent. L’application présente chaque
fil de sous-agent afin que vous puissiez examiner son travail et le résumé renvoyé à la conversation
principale.
Demandez à Codex d’utiliser des sous-agents dans une session CLI interactive. Codex peut aussi suivre
les instructions applicables de AGENTS.md ou de skills qui demandent une délégation. Utilisez
/subagents pour inspecter les fils des agents et passer de l’un à l’autre pendant leur exécution. Le fil principal
rassemble les résultats des sous-agents dans sa réponse finale.
Dans une conversation IDE, demandez à Codex de déléguer les parties indépendantes du travail à des sous-agents.
Codex peut également suivre les instructions AGENTS.md applicables ou celles d’un skill qui demandent une
délégation. Lorsque l’interface des agents en arrière-plan est disponible, les sous-agents actifs apparaissent
au-dessus de la zone de saisie. Développez le panneau pour consulter leur état, arrêter tous les
sous-agents actifs ou ouvrir le fil d’un sous-agent particulier.
Pourquoi les workflows de sous-agents sont utiles
Même avec de grandes fenêtres de contexte, les modèles ont des limites. Si vous surchargez la conversation principale (où vous définissez les exigences, les contraintes et les décisions) avec des résultats intermédiaires parasites, tels que des notes d’exploration, des journaux de test, des traces de pile et des sorties de commandes, la session peut perdre en fiabilité au fil du temps.
Ce phénomène est souvent décrit ainsi :
- Pollution du contexte : les informations utiles se retrouvent noyées dans des résultats intermédiaires parasites.
- Dégradation du contexte : les performances diminuent à mesure que la conversation se remplit de détails moins pertinents.
Pour en savoir plus, consultez l’article de Chroma sur la dégradation du contexte.
Les workflows de sous-agents permettent de déplacer les tâches parasites hors du fil principal :
- Maintenez l’agent principal concentré sur les exigences, les décisions et les résultats finaux.
- Exécutez des sous-agents spécialisés en parallèle pour l’exploration, les tests ou l’analyse des journaux.
- Renvoyez des résumés des sous-agents au lieu de résultats intermédiaires bruts.
Ils peuvent également faire gagner du temps lorsque le travail peut être exécuté indépendamment en parallèle, et ils facilitent la gestion des tâches de grande ampleur en les divisant en parties délimitées. Par exemple, Codex peut scinder l’analyse d’un document de plusieurs millions de jetons en problèmes plus petits et renvoyer des conclusions synthétiques au fil principal.
Pour commencer, utilisez des agents parallèles pour les tâches principalement axées sur la lecture, telles que l’exploration, les tests, le triage et la synthèse. Soyez plus prudent avec les workflows parallèles impliquant beaucoup d’écritures, car des agents qui modifient le code simultanément peuvent créer des conflits et accroître les coûts de coordination.
Termes fondamentaux
Codex emploie quelques termes connexes dans les workflows de sous-agents :
- Workflow de sous-agents : workflow dans lequel Codex exécute des agents en parallèle et combine leurs résultats.
- Sous-agent : agent délégué que Codex lance pour traiter une tâche précise.
- Fil d’agent : fil dans lequel un sous-agent effectue son travail. Les clients compatibles vous permettent d’ouvrir ces fils pour examiner la progression ou les résultats.
Déclencher des workflows de sous-agents
À la plupart des niveaux d’intelligence, demandez le recours à des sous-agents ou à des agents travaillant en parallèle directement. Ultra permet la délégation proactive : ChatGPT peut ainsi déléguer des tâches indépendantes adaptées sans demande distincte.
Demandez directement des sous-agents ou un travail parallèle entre agents. Codex peut également déléguer lorsque des instructions applicables du projet ou d’un skill le demandent.
En pratique, le déclenchement manuel consiste à utiliser des instructions directes telles que « lance deux agents », « délègue ce travail en parallèle » ou « utilise un agent par point ». Les workflows de sous-agents consomment davantage de jetons que des exécutions comparables avec un seul agent, car chaque sous-agent effectue ses propres opérations avec le modèle et les outils.
Une bonne instruction destinée aux sous-agents doit expliquer comment répartir le travail, si Codex doit attendre tous les agents avant de continuer, ainsi que le résumé ou le résultat à renvoyer.
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.Choisir les modèles et le niveau de raisonnement
Les différents agents nécessitent des paramètres de modèle et de raisonnement différents.
Dans ChatGPT Work, choisissez un modèle et un niveau d’intelligence dans la zone de saisie. Les niveaux d’intelligence disponibles peuvent inclure Light, Medium, High, Extra High et Max, selon le modèle sélectionné. Ultra est réservé aux comptes éligibles et aux modèles compatibles. Il utilise le niveau de raisonnement maximal et permet à ChatGPT de déléguer proactivement les tâches appropriées à des sous-agents.
Avec les autres niveaux d’intelligence, demandez explicitement des sous-agents lorsque vous souhaitez déléguer le travail en parallèle.
Si vous ne configurez ni modèle de sous-agent ni model_reasoning_effort, le
sous-agent hérite du modèle et de l’effort de raisonnement de l’agent parent. Si une demande explicite
de création ou une valeur par défaut de [agents] sélectionne un modèle sans
niveau d’effort de raisonnement explicite ou configuré, le sous-agent utilise l’effort de raisonnement par défaut
de ce modèle. Pour équilibrer intelligence, rapidité et coût pour chaque tâche,
demandez un modèle ou un effort de raisonnement précis dans votre prompt,
configurez les valeurs par défaut de [agents] dans config.toml, ou définissez model et
model_reasoning_effort directement dans le fichier de l’agent personnalisé.
Par exemple, utilisez gpt-6-luna pour des analyses rapides ou une configuration de gpt-6.1-sol avec un effort accru pour les raisonnements plus exigeants.
Choix du modèle
gpt-6.1-sol: Commencez par ce modèle pour les agents chargés de tâches exigeantes. Utilisez-le pour les tâches ambiguës en plusieurs étapes qui nécessitent de la planification, l’utilisation d’outils, de la validation et un suivi jusqu’à leur achèvement dans un contexte plus large.gpt-6-luna: Utilisez ce modèle pour les agents rapides au périmètre restreint qui traitent des tâches claires, répétables ou à grand volume.
Effort de raisonnement (model_reasoning_effort)
Pour GPT-6.1 Sol, utilisez un effort de raisonnement pris en charge par votre client et le
modèle sélectionné. Pour les réglages explicites du modèle, commencez par high pour GPT-6 Luna ou low
pour GPT-6 Astra. Adaptez ce réglage à la tâche en choisissant un niveau pris en charge par le modèle sélectionné.
ultra: Utilisez ce niveau pour le raisonnement le plus approfondi lorsque le modèle sélectionné le prend en charge.maxetxhigh: Utilisez ces niveaux pour les raisonnements particulièrement exigeants lorsque le modèle sélectionné les prend en charge.high: Utilisez ce niveau lorsqu’un agent doit suivre une logique complexe, vérifier des hypothèses ou examiner des cas limites (par exemple, les agents de revue ou spécialisés en sécurité).medium: Offre un équilibre entre rapidité et profondeur.low: Utilisez ce niveau lorsque la tâche est simple et que la rapidité prime.
Un effort de raisonnement plus élevé augmente le temps de réponse et la consommation de jetons, mais peut améliorer la qualité des tâches complexes. Pour plus de détails, consultez Modèles, Notions de base de la configuration et Référence de configuration.
Orchestration et contrôle des fils
ChatGPT ou Codex gère l’orchestration entre les agents, notamment le lancement de nouveaux sous-agents, l’acheminement des instructions de suivi, l’attente des résultats et la fermeture des fils d’agents.
Lorsque de nombreux agents sont en cours d’exécution, Codex attend que tous les résultats demandés soient disponibles, puis renvoie une réponse consolidée.
Avec la plupart des niveaux d’intelligence, ChatGPT lance des agents après une demande directe. Avec Ultra, ChatGPT peut également déléguer de manière proactive lorsque le travail en parallèle est utile.
Les versions locales actuelles de Codex lancent des agents après une demande directe ou lorsqu’une instruction applicable du projet ou d’un skill le demande.
Pour voir ce fonctionnement en action, essayez l’instruction suivante dans votre projet :
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 codeGérer les sous-agents
Ouvrez Subagents pour afficher les listes Active et Done en lecture seule. Sélectionnez un sous-agent ayant terminé pour examiner ses détails et son résultat. La barre latérale Web affiche l’activité des sous-agents ; elle ne fournit aucune commande permettant d’arrêter ou d’orienter un sous-agent particulier.
- Ouvrez un fil de sous-agent depuis l’activité affichée dans le fil principal afin d’examiner son travail.
- Demandez directement à Codex d’orienter un sous-agent en cours d’exécution, de l’arrêter ou de fermer les fils de sous-agents terminés.
- Utilisez
/subagentsdans la CLI pour passer d’un fil d’agent actif à l’autre et inspecter le fil en cours. - Demandez directement à Codex de réorienter un sous-agent en cours d’exécution, de l’arrêter ou de fermer les fils des agents ayant terminé.
- Lorsque le panneau des agents en arrière-plan est disponible, développez-le pour consulter leur état, arrêter les sous-agents actifs ou ouvrir le fil d’un sous-agent.
- Demandez directement à Codex de réorienter un sous-agent en cours d’exécution, de l’arrêter ou de fermer les fils des agents ayant terminé.
Approbations et contrôles de l’environnement isolé
Les sous-agents héritent de votre politique actuelle d’environnement isolé.
ChatGPT Work exécute les sous-agents dans son environnement hébergé et ne propose pas de bac à sable Codex local ni de réglage du mode d’approbation. Les sous-agents utilisent les outils disponibles dans la conversation parente. Les autorisations des sites web et des connecteurs restent propres à chaque outil.
Les sous-agents héritent du mode d’autorisation sélectionné sous la zone de saisie. Choisissez le mode d’autorisation du tour parent avant de demander à Codex de déléguer le travail.
Dans les sessions CLI interactives, les demandes d’approbation peuvent provenir de fils d’agents inactifs,
même lorsque vous consultez le fil principal. La fenêtre d’approbation
affiche le libellé du fil source, et vous pouvez appuyer sur o pour ouvrir ce fil avant
d’approuver, de refuser ou de répondre à la demande.
Dans les flux non interactifs, ou lorsqu’une exécution ne peut pas présenter une nouvelle demande d’approbation, une action nécessitant une nouvelle approbation échoue et Codex transmet l’erreur au workflow parent.
Les sous-agents héritent des paramètres actuels du bac à sable et d’approbation du tour parent,
y compris des modifications effectuées avec /permissions ou --yolo. Un fichier d’agent personnalisé
ne peut pas remplacer ces paramètres.
Les sous-agents héritent du mode d’autorisation sélectionné sous la zone de saisie. Choisissez le mode d’autorisation du tour parent avant de demander à Codex de déléguer des tâches.
Configurez les contrôles du bac à sable et des approbations dans la session parente. Les instructions personnalisées peuvent demander à un agent de ne rien modifier, mais elles ne créent pas de bac à sable distinct en lecture seule.
Agents personnalisés
Codex est fourni avec des agents intégrés :
default: agent généraliste utilisé comme solution de secours.worker: agent axé sur l’exécution pour les implémentations et les corrections.explorer: agent d’exploration de bases de code principalement axé sur la lecture.
Pour définir vos propres agents personnalisés, ajoutez des fichiers TOML autonomes sous
~/.codex/agents/ pour les agents personnels ou sous .codex/agents/ pour les agents limités
au projet.
Chaque fichier définit un agent personnalisé. Les agents personnalisés peuvent modifier les paramètres du modèle et les instructions, ou désactiver les fonctionnalités prises en charge. Ils héritent des autorisations, du fournisseur et des MCP servers du parent ; un fichier d’agent personnalisé ne peut pas remplacer ces paramètres.
Chaque fichier autonome d’agent personnalisé doit définir :
namedescriptiondeveloper_instructions
Si un fichier d’agent personnalisé définit model ou model_reasoning_effort, la valeur du
fichier est prioritaire. Avant d’appliquer le fichier, Codex détermine chaque paramètre
à partir d’une valeur explicite à la création, puis de la valeur par défaut [agents] correspondante, puis de
la valeur du parent. Si une demande de création explicite ou une valeur par défaut [agents]
sélectionne un modèle sans préciser d’effort de raisonnement, Codex utilise
l’effort par défaut de ce modèle. Un fichier d’agent personnalisé qui définit uniquement model
conserve cet effort déterminé précédemment. Définissez également model_reasoning_effort dans le
fichier si le modèle sélectionné ne prend pas en charge cet effort ou si vous souhaitez en utiliser un
autre. Les skills sont hérités du parent, et un agent personnalisé peut désactiver
des skills individuellement avec skills.config.
Paramètres globaux
Les paramètres globaux des sous-agents se trouvent toujours sous [agents] dans votre configuration.
| Champ | Type | Obligatoire | Rôle |
|---|---|---|---|
agents.enabled |
boolean | Non | Activer ou désactiver les outils multi-agents. |
agents.max_concurrent_threads_per_session |
number | Non | Limiter le nombre de fils d’agents générés ouverts simultanément, hors agent principal. |
agents.default_subagent_model |
string | Non | Définir le modèle par défaut des agents générés. |
agents.default_subagent_reasoning_effort |
string | Non | Définir l’effort de raisonnement par défaut des agents générés. |
agents.interrupt_message |
boolean | Non | Enregistrer un message visible par le modèle lorsqu’un tour d’agent est interrompu. |
Remarques :
agents.enabledest défini par défaut surtrue. Définissez-le surfalsepour désactiver les outils multi-agents.- Lorsque vous ne définissez pas
agents.max_concurrent_threads_per_session, Codex choisit la valeur par défaut. Les configurations existantes peuvent continuer à utiliseragents.max_threadscomme alias historique. - Les valeurs explicites définies lors de la création remplacent
agents.default_subagent_modeletagents.default_subagent_reasoning_effort. agents.interrupt_messageest défini par défaut surtrue. Définissez-le surfalsepour omettre le message d’interruption visible par le modèle dans le contexte de l’agent.- Si le nom d’un agent personnalisé correspond à celui d’un agent intégré tel que
explorer, votre agent personnalisé est prioritaire.
Schéma du fichier d’agent personnalisé
| Champ | Type | Obligatoire | Rôle |
|---|---|---|---|
name |
string | Oui | Nom d’agent utilisé par Codex pour créer cet agent ou y faire référence. |
description |
string | Oui | Indications destinées aux utilisateurs sur les cas où Codex doit utiliser cet agent. |
developer_instructions |
string | Oui | Instructions principales qui définissent le comportement de l’agent. |
Utilisez model, model_reasoning_effort, model_reasoning_summary et
model_verbosity pour personnaliser le comportement du modèle.
Consultez la référence de configuration pour connaître leurs
valeurs acceptées.
Pour réduire les capacités d’un agent personnalisé, définissez les clés de fonctionnalité prises en charge sur false :
features.shell_tool, features.apps, features.plugins,
features.memories ou features.request_permissions_tool. Désactivez des skills
individuellement avec skills.config ou les skills intégrés avec
skills.bundled.enabled = false. Définissez skills.include_instructions = false pour
omettre le bloc automatique d’instructions sur les skills. Les exigences gérées restent applicables.
Les autres paramètres de session, notamment sandbox_mode, approval_policy,
model_provider et mcp_servers, ne remplacent pas la configuration parente
lorsqu’ils figurent dans un fichier d’agent personnalisé. Le niveau de service suit également la préférence de la session
racine. Configurez les MCP servers dans la session parente pour que l’agent
puisse les utiliser.
Codex identifie l’agent personnalisé grâce à son champ name. Faire correspondre le nom du fichier à
celui de l’agent est la convention la plus simple, mais le champ name fait foi.
Exemples d’agents personnalisés
Les meilleurs agents personnalisés ont un périmètre restreint et des choix bien affirmés. Attribuez à chacun une tâche claire, une palette d’outils adaptée à cette tâche et des instructions qui l’empêchent de s’écarter vers des travaux connexes.
Les exemples utilisent GPT-6.1 Sol lorsque le compte avec lequel vous êtes connecté ou votre espace de travail y donne accès. S’il n’est pas disponible, choisissez un modèle que vous pouvez utiliser.
Exemple 1 : revue de PR
Ce modèle répartit la revue entre trois agents personnalisés spécialisés :
pr_explorercartographie la base de code et rassemble des éléments probants.reviewerrecherche les risques liés à l’exactitude, à la sécurité et aux tests.docs_researcherconsulte la documentation du framework ou de l’API au moyen d’un MCP server dédié.
Configuration du projet (.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.
"""
Cette configuration convient bien aux prompts tels que :
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.Exemple 2 : débogage de l’intégration frontend
Ce modèle est utile pour les régressions d’interface utilisateur, les parcours instables dans le navigateur ou les bugs d’intégration qui concernent à la fois le code de l’application et le produit en cours d’exécution.
Configuration du projet (.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 = falseCette configuration convient bien aux prompts tels que :
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.