サブエージェント¶

Work mode と Codex は、専門化されたエージェントを並列で起動し、その結果を 1 つのレスポンスにまとめることで、サブエージェントワークフローを実行できます。これは、コードベースの探索や複数ステップの機能計画の実装など、高度に並列化できる複雑なタスクで特に役立ちます。

ローカルの Codex クライアントでは、タスクごとに異なるモデル構成や指示を持つカスタムエージェントを定義することもできます。

利用可能性¶

現在の Codex リリースでは、サブエージェントワークフローがデフォルトで有効になっています。サブエージェントのアクティビティは、ChatGPT デスクトップアプリ、Codex CLI、IDE 拡張機能に表示されます。

各サブエージェントは独自にモデル処理とツール処理を行うため、サブエージェントワークフローでは、同等の単一エージェント実行よりも多くのトークンを消費します。

アプリのチャットで Codex に、作業の独立した部分をサブエージェントに委任するよう依頼します。現在のローカル Codex リリースは、直接依頼した場合、または該当する AGENTS.md やスキルの指示で要求された場合に委任します。アプリには各サブエージェントのスレッドが表示されるため、その作業とメインチャットに返された概要を確認できます。

サブエージェントワークフローが役立つ理由¶

コンテキストウィンドウが大きくても、モデルには限界があります。要件、制約、判断を定義しているメインチャットに、探索メモ、テストログ、スタックトレース、コマンド出力などの中間生成物を大量に流し込むと、時間の経過とともにセッションの信頼性が低下する可能性があります。

これは、次のように説明されることがよくあります。

• コンテキスト汚染: 役立つ情報が、ノイズの多い中間生成物に埋もれます。
• コンテキストの劣化: チャットに関連性の低い詳細が蓄積すると、パフォーマンスが低下します。

背景については、Chroma の コンテキストの劣化 に関する解説を参照してください。

サブエージェントワークフローは、ノイズの多い作業をメインスレッドから移すことで役立ちます。

• メインエージェントは、要件、判断、最終出力に集中します。
• 探索、テスト、ログ分析のために、専門化されたサブエージェントを並列で実行します。
• サブエージェントからは、中間生成物そのものではなく概要を返します。

また、作業を独立して並列実行できる場合は時間を節約でき、タスクを限定された単位に分割することで、より大規模なタスクにも取り組みやすくなります。たとえば Codex は、数百万トークンのドキュメントの分析を小さな問題に分割し、要点を抽出してメインスレッドに返すことができます。

まずは、探索、テスト、トリアージ、要約など、読み取り中心のタスクに並列エージェントを使用してください。エージェントが同時にコードを編集すると競合が発生し、調整のオーバーヘッドが増える可能性があるため、書き込み中心の並列ワークフローにはより注意が必要です。

基本用語¶

Codex は、サブエージェントワークフローでいくつかの関連用語を使用します。

• サブエージェントワークフロー: Codex がエージェントを並列実行し、その結果を組み合わせるワークフローです。
• サブエージェント: 特定のタスクを処理するために Codex が起動する、委任されたエージェントです。
• エージェントスレッド: サブエージェントが作業を行うスレッドです。対応クライアントでは、このスレッドを開いて進行状況や結果を確認できます。

サブエージェントワークフローの起動¶

サブエージェントまたは並列エージェントによる作業を直接依頼します。該当するプロジェクトまたはスキルの指示によって要求された場合、Codex が委任することもあります。

実際には、手動で起動するには「2 つのエージェントを起動して」「この作業を並列で委任して」「項目ごとに 1 つのエージェントを使って」などの直接的な指示を使用します。各サブエージェントは独自にモデル処理とツール処理を行うため、サブエージェントワークフローでは、同等の単一エージェント実行よりも多くのトークンを消費します。

優れたサブエージェント用プロンプトでは、作業をどのように分割するか、続行する前にすべてのエージェントを待つかどうか、どのような概要または出力を返すかを説明します。

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.

モデルと推論の選択¶

エージェントごとに、適したモデルや推論設定が異なります。

モデルや model_reasoning_effort を固定しない場合、Codex はタスクに応じて知能、速度、価格のバランスが取れる構成を選択できます。高速スキャンでは gpt-5.6-terra を、より高度な推論が必要な場合は高い負荷の gpt-5.6 構成を優先することがあります。より細かく制御したい場合は、プロンプトでその選択を誘導するか、エージェントファイルで model と model_reasoning_effort を直接設定します。

Codex のほとんどのタスクでは、まず gpt-5.6 を使用してください。より軽いサブエージェント作業向けに、より高速で低コストのオプションが必要な場合は gpt-5.6-terra を使用します。ChatGPT Pro を利用していて、ほぼ即時のテキストのみの反復処理を行いたい場合は、研究プレビュー版の gpt-5.3-codex-spark も引き続き利用できます。

モデルの選択¶

• gpt-5.6: 高度なエージェントにはこれを使用します。計画、ツール使用、検証、大規模なコンテキストにわたる実行継続が必要な、曖昧で複数ステップの作業に最も強みがあります。
• gpt-5.4: ワークフローが GPT-5.4 に固定されている場合に使用します。強力なコーディング、推論、ツール使用、より幅広いワークフローを組み合わせています。
• gpt-5.6-terra: 深さより速度と効率を重視するエージェントに使用します。探索、読み取り中心のスキャン、大きなファイルのレビュー、補助ドキュメントの処理などが該当します。メインエージェントに抽出した結果を返す並列ワーカーに適しています。
• gpt-5.3-codex-spark: ChatGPT Pro を利用している場合、レイテンシーが幅広い機能より重要なときに、ほぼ即時のテキストのみの反復処理を行う研究プレビュー版モデルとして使用します。

推論の負荷（model_reasoning_effort）¶

• ultra: 選択したモデルが対応している場合に、最も深い推論に使用します。
• max と xhigh: 選択したモデルがこれらのレベルに対応している場合に、特に高度な推論に使用します。
• high: 複雑なロジックの追跡、前提の確認、エッジケースの検討が必要なエージェント（たとえばレビュー担当やセキュリティ重視のエージェント）に使用します。
• medium: ほとんどのエージェント向けのバランスの取れたデフォルトです。
• low: タスクが単純で、速度が最も重要な場合に使用します。
• minimal と none: 選択したモデルがこれらの低レイテンシーレベルに対応しており、タスクにほとんど、またはまったく推論が必要ない場合に使用します。

推論の負荷を高くすると、応答時間とトークン使用量が増加しますが、複雑な作業の品質を向上させられます。詳しくは、モデル、設定の基本、設定リファレンスを参照してください。

agents.max_depth はネストを制御し、デフォルトは 1 です。これにより、ルートスレッドは直接の子を起動できますが、その子がさらに深い子孫を起動することはできません。

オーケストレーションとスレッド制御¶

ChatGPT または Codex は、エージェント間のオーケストレーションを処理します。これには、新しいサブエージェントの起動、追加指示のルーティング、結果の待機、エージェントスレッドの終了が含まれます。

多数のエージェントが実行されている場合、Codex は要求されたすべての結果が利用可能になるまで待機し、その後、統合したレスポンスを返します。

現在のローカル Codex リリースでは、直接依頼した場合、または該当するプロジェクトやスキルの指示がある場合にエージェントを起動します。

実際の動作を確認するには、プロジェクトで次のプロンプトを試してください。

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

サブエージェントの管理¶

• メインスレッドに表示されるアクティビティからサブエージェントスレッドを開き、その作業を確認します。
• Codex に直接依頼して、実行中のサブエージェントを誘導、停止、または完了したサブエージェントスレッドを閉じます。

承認とサンドボックスの制御¶

サブエージェントは現在のサンドボックスポリシーを継承します。

サブエージェントは、コンポーザーの下で選択されている権限モードを継承します。Codex に作業を委任する前に、親ターンの権限モードを選択してください。

個別のカスタムエージェントについて、サンドボックス構成をオーバーライドすることもできます。たとえば、読み取り専用モードで動作するよう明示的に指定できます。

カスタムエージェント¶

Codex には組み込みエージェントが付属しています。

• default: 汎用のフォールバックエージェントです。
• worker: 実装と修正に特化した実行重視のエージェントです。
• explorer: 読み取り中心のコードベース探索エージェントです。

独自のカスタムエージェントを定義するには、個人用エージェントの場合は ~/.codex/agents/ に、プロジェクトスコープのエージェントの場合は .codex/agents/ に、スタンドアロンの TOML ファイルを追加します。

各ファイルでは、1 つのカスタムエージェントを定義します。Codex は、起動されたセッションの構成レイヤーとしてこれらのファイルを読み込むため、カスタムエージェントは通常の Codex セッション構成と同じ設定をオーバーライドできます。専用のエージェントマニフェストよりも重く感じられる場合があります。また、作成と共有の方法が成熟するにつれて、形式が変わる可能性があります。

すべてのスタンドアロンのカスタムエージェントファイルでは、次を定義する必要があります。

• name
• description
• developer_instructions

nickname_candidates、model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config などのオプションフィールドは、省略すると親セッションから継承されます。

グローバル設定¶

グローバルなサブエージェント設定は、構成の [agents] 配下にあります。

注:

• agents.max_threads のデフォルト値は、未設定の場合 6 です。
• agents.max_depth のデフォルト値は 1 です。これにより、ルートスレッドは直接の子を起動できますが、その子がさらに深い子孫を起動することはできません。再帰的な委任が特に必要でない限り、デフォルト値を維持してください。この値を大きくすると、広範な委任指示が繰り返しファンアウトされ、トークン使用量、レイテンシー、ローカルリソース消費が増加する可能性があります。agents.max_threads は同時に開けるスレッド数を引き続き制限しますが、より深い再帰によるコストと予測可能性のリスクをなくすものではありません。
• agents.job_max_runtime_seconds はオプションです。未設定の場合、spawn_agents_on_csv はワーカーごとに 1800 秒の呼び出し単位のデフォルトタイムアウトを使用します。
• agents.interrupt_message のデフォルト値は true です。エージェントのコンテキストからモデルに見える中断メッセージを省略するには、false に設定します。
• カスタムエージェント名が explorer などの組み込みエージェントと一致する場合は、カスタムエージェントが優先されます。

カスタムエージェントファイルのスキーマ¶

カスタムエージェントファイルには、model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config など、その他のサポートされる config.toml キーも含められます。

Codex は、name フィールドによってカスタムエージェントを識別します。ファイル名をエージェント名と一致させるのが最も簡単な慣例ですが、正しい情報源となるのは name フィールドです。

表示用ニックネーム¶

起動されたエージェントに読みやすい表示名を Codex から割り当てたい場合は、nickname_candidates を使用します。これは、同じカスタムエージェントのインスタンスを多数実行し、同じエージェント名を繰り返すのではなく、UI に異なるラベルを表示したい場合に特に役立ちます。

ニックネームは表示専用です。Codex は引き続き name によってエージェントを識別し、起動します。

ニックネーム候補は、空でない一意な名前のリストである必要があります。各ニックネームには、ASCII 文字、数字、スペース、ハイフン、アンダースコアを使用できます。

例:

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]

実際には、ChatGPT デスクトップアプリ、Codex CLI、IDE 拡張機能で、エージェントのアクティビティが表示される場所にニックネームを表示できます。一方、基盤となるエージェントの種類は reviewer のままです。

カスタムエージェントの例¶

優れたカスタムエージェントは、対象範囲が狭く、明確な方針を持ちます。それぞれに明確な役割、その役割に合ったツールの範囲、隣接する作業へ逸脱しないための指示を与えてください。

例 1: PR レビュー¶

このパターンでは、レビューを 3 つの目的に特化したカスタムエージェントに分割します。

• pr_explorer はコードベースをマッピングし、根拠を収集します。
• reviewer は正確性、セキュリティ、テストのリスクを探します。
• docs_researcher は専用の MCP サーバーを通じて、フレームワークまたは API のドキュメントを確認します。

プロジェクト構成（.codex/config.toml）:

[agents]
max_threads = 6
max_depth = 1

.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.4"
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.4-mini"
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"

この構成は、次のようなプロンプトに適しています。

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.

サブエージェントで CSV バッチを処理する（実験的）¶

このワークフローは実験的であり、サブエージェントのサポートの進展に伴って変更される可能性があります。1 つの作業項目につき 1 行という形で対応付けられる、類似したタスクが多数ある場合は spawn_agents_on_csv を使用します。Codex は CSV を読み取り、行ごとに 1 つのワーカーサブエージェントを起動し、バッチ全体の完了を待って、統合した結果を CSV にエクスポートします。

これは、次のような反復的な監査に適しています。

• 行ごとに 1 つのファイル、パッケージ、またはサービスをレビューする
• インシデント、PR、移行対象のリストを確認する
• 類似した入力を多数処理し、構造化された概要を生成する

このツールは次を受け取ります。

• ソース CSV 用の csv_path
• {column_name} プレースホルダーを使用する、ワーカープロンプトテンプレート用の instruction
• 特定の列から安定した項目 ID を取得する場合の id_column
• 各ワーカーに固定形式の JSON オブジェクトを返させる場合の output_schema
• ジョブ制御用の output_csv_path、max_concurrency、max_runtime_seconds

各ワーカーは report_agent_job_result を正確に 1 回呼び出す必要があります。結果を報告せずにワーカーが終了した場合、Codex はエクスポートされた CSV のその行をエラーとして記録します。

プロンプトの例:

Create /tmp/components.csv with columns path,owner and one row per frontend component.

Then call spawn_agents_on_csv with:
- csv_path: /tmp/components.csv
- id_column: path
- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result."
- output_csv_path: /tmp/components-review.csv
- output_schema: an object with required string fields path, risk, summary, and follow_up

これを codex exec を通じて実行すると、バッチの実行中、Codex は stderr に 1 行の進行状況更新を表示します。エクスポートされた CSV には元の行データに加えて、job_id、item_id、status、last_error、result_json などのメタデータが含まれます。

関連するランタイム設定:

• agents.max_threads は、同時に開いたままにできるエージェントスレッド数を制限します。
• agents.job_max_runtime_seconds は、CSV ファンアウトジョブのワーカーごとのデフォルトタイムアウトを設定します。呼び出し単位の max_runtime_seconds オーバーライドが優先されます。
• sqlite_home は、Codex がエージェントジョブとエクスポートされた結果に使用する SQLite ベースの状態を保存する場所を制御します。

例 2: フロントエンド統合のデバッグ¶

このパターンは、UI のリグレッション、不安定なブラウザフロー、アプリケーションコードと実行中のプロダクトをまたぐ統合バグに役立ちます。

プロジェクト構成（.codex/config.toml）:

[agents]
max_threads = 6
max_depth = 1

.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.4-mini"
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.4"
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

この構成は、次のようなプロンプトに適しています。

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.