コンテンツにスキップ
mild worksai-tools-kb

Subagents

facts ／Codex ／subagents

stable2 か月前 · 2026-08-09

概要

特化したエージェントを並列に起動し、その結果を 1 つの応答にまとめる仕組み。コードベース探索や多段の実装計画のように並列化しやすい複雑なタスクで使う。ローカルの Codex クライアントでは、タスクごとに異なるモデル設定と指示を持つ custom agent を定義できる。

仕様

提供状況

  • ChatGPT Work（web）では、subagent のワークフローとアクティビティが eligible なアカウントに対して公開される
  • ローカルクライアント（ChatGPT desktop app / Codex CLI / IDE extension）では、現行リリースが subagent ワークフローを既定で有効にしている
  • 各 subagent が自前でモデル呼び出しとツール実行を行うため、同等の単一エージェント実行よりトークンを多く消費する

サーフェスごとの起動と管理

サーフェス起動管理
ChatGPT Work（web）ほとんどの intelligence level では明示的に委譲を依頼する。Ultra では並列エージェントが速度・品質を実質的に改善する場合に ChatGPT が自発的に委譲できるSubagents を開くと読み取り専用の Active / Done 一覧。完了した subagent の詳細と結果を確認できる。個別の subagent を停止・操作するコントロールは無い
ChatGPT desktop app直接依頼するか、該当する AGENTS.md / skill の指示が求めたときに委譲するメインスレッドのアクティビティから subagent スレッドを開く。停止や誘導は Codex に直接依頼する
Codex CLI対話セッションで依頼する。AGENTS.md / skill の指示にも従う/agent で稼働中の agent スレッドを切り替えて確認する。停止・誘導は Codex に依頼する
IDE extension直接依頼するか AGENTS.md / skill の指示によるbackground-agent UI が利用可能な場合、composer の上にアクティブな subagent が表示される。パネルを展開して状態確認・全停止・個別スレッドを開ける
  • 多数のエージェントが動いているとき、Codex は要求された結果がすべて揃うまで待ってから統合した応答を返す
  • 良い subagent プロンプトは、作業の分割方法、全エージェントの完了を待つか、どんな要約・出力を返すかを説明するもの、とされている

モデルと reasoning effort の選択

  • model や model_reasoning_effort を固定しない場合、Codex がタスクに応じて知能・速度・価格のバランスを取る構成を選ぶことがある
  • ドキュメントが挙げるモデルの使い分け
    • gpt-5.6: 要求の厳しいエージェントの出発点。曖昧で多段、計画・ツール利用・検証・追跡が必要な作業に最も強い
    • gpt-5.6-terra: 深さより速度と効率を優先するエージェント向け。探索、read 中心のスキャン、大きなファイルのレビュー、補助資料の処理など
    • gpt-5.6-luna: 明確で反復的、あるいは大量の作業を扱う高速で範囲の狭いエージェント向け
  • model_reasoning_effort の水準: ultra / max / xhigh / high / medium / low
    • ultra、max、xhigh は 選択したモデルが対応している場合に限る
    • medium がほとんどのエージェントにとってバランスの取れた既定
  • reasoning effort を上げると応答時間とトークン使用量が増えるが、複雑な作業では品質が上がりうる

approvals と sandbox

  • ローカルクライアント（app / CLI / IDE）では、subagent は現在の sandbox policy を継承する
  • ChatGPT Work（web）は hosted 環境で subagent を動かし、ローカルの sandbox や approval-mode の操作を公開しない。subagent は親チャットで使えるツールを使う。website と connector の権限はツール個別のまま
  • desktop app と IDE extension では、composer 下で選んだ permission mode を subagent が継承する。委譲を依頼する前に親ターンの permission mode を選ぶ
  • CLI の対話セッションでは、メインスレッドを見ている間でも非アクティブな agent スレッドから承認要求が上がることがある。承認オーバーレイに発生元スレッドのラベルが出て、o でそのスレッドを開いてから承認・拒否・回答できる
  • 非対話フローや、新しい承認を提示できない実行では、新規の承認を要するアクションは失敗し、Codex は親ワークフローにエラーを返す
  • CLI では、子を spawn するときに親ターンのライブな runtime override（セッション中に対話的に設定した /permissions の変更や --yolo など）を再適用する。選択された custom agent ファイルが異なる既定を設定していても、こちらが適用される
  • custom agent 単位で sandbox 設定を上書きできる（read-only で動かすなど）

組み込みエージェント

名前役割
default汎用のフォールバック
worker実装・修正に向いた実行中心
explorerread 中心のコードベース探索

custom agent

  • ~/.codex/agents/（個人）または .codex/agents/（プロジェクト）に独立した TOML ファイルを置く。1 ファイルにつき 1 エージェント
  • Codex はこれらのファイルを、spawn されるセッションの configuration layer として読み込む。したがって custom agent は通常の Codex セッション config と同じ設定を上書きできる
  • ドキュメントは、この方式が専用の agent マニフェストより重く感じられうること、フォーマットが今後変わりうることを明記している
  • 必須フィールド
フィールド型必須用途
namestringはいspawn・参照時に使う名前
descriptionstringはいこの agent をいつ使うべきかの人間向けの説明
developer_instructionsstringはい振る舞いを定義する中核の指示
  • model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config など、その他の config.toml のキーも書ける
  • Codex は name フィールドで custom agent を識別する。ファイル名を合わせるのが簡単な慣習だが、真の識別子は name
  • custom agent の名前が explorer などの組み込み agent と一致する場合、custom agent が優先される

設定の解決順

  • custom agent ファイルが model または model_reasoning_effort を設定していれば、ファイルの値が優先される
  • 設定していない場合は各設定を独立に解決する: 明示的な spawn 値 → 対応する [agents] の既定 → 親の値
  • spawn が別のモデルを選び、明示的な effort も設定済みの effort も無い場合は、そのモデルの既定 effort を使う
  • sandbox_mode、mcp_servers、skills.config などその他のセッション設定は、custom agent ファイルが省略していれば親から継承する

[agents] のグローバル設定

フィールド型必須用途
agents.enabledbooleanいいえmulti-agent ツールの有効・無効。既定 true
agents.max_concurrent_threads_per_sessionnumberいいえ同時に開ける spawned-agent スレッド数の上限（primary を除く）。未設定なら Codex が既定を選ぶ
agents.default_subagent_modelstringいいえspawn される agent の既定モデル
agents.default_subagent_reasoning_effortstringいいえspawn される agent の既定 reasoning effort
agents.interrupt_messagebooleanいいえagent のターンが中断されたときにモデルから見えるメッセージを記録する。既定 true
  • agents.max_threads は既存設定向けの legacy alias として使い続けられる
  • 明示的な spawn 値は agents.default_subagent_model と agents.default_subagent_reasoning_effort を上書きする

設定

.codex/config.toml
[agents]
max_concurrent_threads_per_session = 8
.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.
"""
# custom agent ファイルに MCP サーバーを持たせる例
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.
"""


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

制約・注意点

  • subagent ワークフローは同等の単一エージェント実行よりトークンを多く消費する
  • 公式ドキュメントは、まず探索・テスト・トリアージ・要約といった read 中心のタスクに並列エージェントを使うことを勧め、write 中心の並列ワークフローには注意するよう述べている（同時にコードを編集すると衝突と調整コストが増える）
  • custom agent ファイルのフォーマットは、オーサリングと共有の仕組みが成熟するにつれて変わりうる

関連

  • facts/codex/models.md
  • facts/codex/hooks.md
  • facts/codex/sandbox.md
  • facts/codex/permissions.md
  • facts/codex/configuration-reference.md
  • facts/codex/mcp.md
  • facts/codex/skills.md
  • facts/codex/agents-md.md