Codexの設定 - サブエージェントのソースを表示

== 概要 ==
OpenAI Codex CLIのサブエージェント機能は、専門化されたエージェントを並列に起動し、それぞれの結果を統合することで、複雑なタスクを効率的に処理する仕組みである。<br>
<br>
サブエージェントは現在のCodexリリースではデフォルトで有効になっており、ユーザが明示的に依頼した場合にのみ起動される。<br>
単純なタスクでは使用されず、並列性の高い作業にのみ呼び出される点が特徴である。<br>
<br>
サブエージェントが特に有用な用途は以下の通りである。<br>
* コードベース探索 (codebase exploration)
*: 複数のエージェントが並列でコードを調査し、結果をまとめる。
* 複数ステップの実装 (multi-step implementation)
*: 機能計画に基づいて、各ステップを別々のエージェントが担当する。
* PRレビュー
*: セキュリティ、バグ、コード品質等の観点を並列でレビューする。
<br>
<u>各サブエージェントは独自のモデルとツール実行を行うため、シングルエージェント実行と比較してトークン消費が増加する点に注意が必要である。</u><br>
<br><br>

== ビルトインエージェント ==
Codexには、下表に示す3種類のビルトインエージェントが用意されている。<br>
<br>
<center>
{| class="wikitable"
|+ ビルトインエージェント一覧
! エージェント名 !! 役割 !! 説明
|-
| <code>default</code> || 汎用フォールバック || 特定の役割が指定されない場合に使用される汎用エージェント
|-
| <code>worker</code> || 実装・修正特化 || コードの実装やバグ修正といった実行処理に焦点を当てたエージェント
|-
| <code>explorer</code> || コードベース探索特化 || コードベースの読み取りと探索に特化した、読み取り重視型エージェント
|}
</center>
<br>
同名のカスタムエージェントを定義することにより、ビルトインエージェントの動作を上書きできる。<br>
<br>
例えば、プロジェクト固有の <code>explorer</code> エージェントを定義すると、ビルトインの <code>explorer</code> より優先して使用される。<br>
<br><br>

== カスタムエージェントの定義 ==
ユーザは独自のカスタムエージェントを定義して、特定のタスクに最適化されたエージェントを作成できる。<br>
<br>
==== ファイル配置場所 ====
カスタムエージェントのファイルは、以下に示すディレクトリに配置する。<br>
<br>
* 個人用 (全プロジェクトで使用可能)
*: <u>~/.codex/agents/</u>
* プロジェクト用 (プロジェクト固有)
*: <u>.codex/agents/</u>
<br>
同名のエージェントが個人用とプロジェクト用の両方に存在する場合、プロジェクト用が優先される。<br>
<br>
==== 1ファイル1エージェント ====
カスタムエージェントは、1つのファイルが1つのエージェントを定義する形式をとる。<br>
ファイル名をエージェント名に合わせることが推奨される規約であるが、<code>name</code> フィールドが最終的な識別子として使用される。<br>
<br>
 # 例: コードレビュー用エージェントのファイル
 ~/.codex/agents/code_reviewer.toml
 
 # 例: プロジェクト用エージェントのファイル
 .codex/agents/reviewer.toml
<br>
==== Markdownフロントマター形式 ====
カスタムエージェントの定義ファイルは、TOML形式で記述する。<br>
また、YAML形式のフロントマターで記述することもできる。<br>
<br>
TOMLフロントマター形式のサンプルを以下に示す。<br>
<br>
===== コードレビュー用エージェント =====
 <syntaxhighlight lang="toml">
 name = "code_reviewer"
 description = "PR reviewer focused on correctness, security, and missing tests. Use when reviewing code changes."
 model = "gpt-5.4-mini"
 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.
 Do not make code changes.
 """
 </syntaxhighlight>
<br>
===== テストランナー用エージェント =====
 <syntaxhighlight lang="toml">
 name = "test_runner"
 description = "Specialized agent for running and analyzing test results. Use when verifying test coverage or debugging test failures."
 model = "gpt-5.4-mini"
 model_reasoning_effort = "medium"
 developer_instructions = """
 Execute test suites and analyze results.
 Report failures with clear reproduction steps and root cause analysis.
 Suggest improvements to test coverage when gaps are identified.
 """
 </syntaxhighlight>
<br>
===== ドキュメント生成用エージェント =====
 <syntaxhighlight lang="toml">
 name = "doc_generator"
 description = "Documentation specialist for verifying APIs and generating documentation. Use when creating or updating docs."
 model = "gpt-5.4-mini"
 model_reasoning_effort = "medium"
 sandbox_mode = "read-only"
 developer_instructions = """
 Analyze code and generate clear, accurate documentation.
 Confirm APIs and framework behavior before documenting.
 Return concise answers with exact references when available.
 Do not make code changes.
 """
 
 [mcp_servers.openaiDeveloperDocs]
 url = "https://developers.openai.com/mcp"
 </syntaxhighlight>
<br>
==== 必須 / 任意フィールド ====
下表に、カスタムエージェント定義ファイルのフィールドを示す。<br>
<br>
<center>
{| class="wikitable"
|+ カスタムエージェントのフィールド一覧
! フィールド名 !! 型 !! 必須 !! 説明
|-
| <code>name</code> || 文字列 || 必須 || エージェントの識別子<br>エージェントを呼び出す際に使用される。
|-
| <code>description</code> || 文字列 || 必須 || このエージェントをいつ使用すべきかのガイダンス<br>親エージェントがこれを読んで判断する。
|-
| <code>developer_instructions</code> || 文字列 || 必須 || エージェントの動作を定義するコア指示<br>役割、手順、禁止事項等を記述する。
|-
| <code>nickname_candidates</code> || 文字列配列 || 任意 || UIでの表示用ニックネームの候補リスト<br>省略すると自動生成される。
|-
| <code>model</code> || 文字列 || 任意 || 使用するモデル<br>省略すると親セッションの設定を継承する。
|-
| <code>model_reasoning_effort</code> || 文字列 || 任意 || モデルの推論努力レベル<br>(<code>low</code>, <code>medium</code>, <code>high</code>)<br>省略すると継承する。
|-
| <code>sandbox_mode</code> || 文字列 || 任意 || サンドボックスモード<br>省略すると親セッションの設定を継承する。
|-
| <code>mcp_servers</code> || オブジェクト || 任意 || MCPサーバの設定<br>省略すると継承する。
|-
| <code>skills.config</code> || オブジェクト || 任意 || スキル設定の有効 / 無効化<br>省略すると継承する。
|}
</center>
<br><br>

== 継承される設定 ==
カスタムエージェントで明示的に記載しないフィールドは、親セッションの設定を引き継ぐ。<br>
これにより、プロジェクト全体の共通設定を変更するだけで全エージェントに反映できる。<br>
<br>
<center>
{| class="wikitable"
|+ 親セッションから継承される設定項目
! 設定項目 !! 説明
|-
| <code>model</code> / <code>model_provider</code> || 使用するモデルとプロバイダの指定
|-
| <code>model_reasoning_effort</code> || モデルの推論努力レベル
|-
| <code>sandbox_mode</code> || サンドボックスポリシー
|-
| <code>mcp_servers</code> || MCPサーバの設定とツールアクセス権限
|-
| <code>skills.config</code> || スキル設定の有効/無効化
|-
| <code>shell_environment_policy</code> || サブプロセス実行コンテキストのシェル環境ポリシー
|}
</center>
<br>
カスタムエージェントで設定を上書きした場合、そのエージェントのみに適用され、親セッションの設定は変更されない。<br>
<br><br>

== サンドボックスモードと承認の継承 ==
サブエージェントは、スポーン時に親セッションの現在のサンドボックスポリシーを継承する。<br>
<br>
親ターンのライブランタイムオーバーライドはスポーン時に再適用される。<br>
対話型セッション中の <code>/approvals</code> の変更や <code>--yolo</code> フラグの設定も、サブエージェントに適用される。<br>
<br>
個別のカスタムエージェントで <code>sandbox_mode</code> を明示的に設定することにより、親の設定とは独立した動作を固定できる。<br>
<br>
以下に、<code>sandbox_mode</code> を <code>read-only</code> に固定する例を示す。<br>
<br>
 <syntaxhighlight lang="toml">
 name = "pr_explorer"
 description = "Read-only codebase explorer for gathering evidence before changes are proposed."
 model = "gpt-5.4-mini"
 sandbox_mode = "read-only"
 developer_instructions = """
 Stay in exploration mode.
 Trace the real execution path, cite files and symbols, and avoid proposing fixes.
 """
 </syntaxhighlight>
<br>
上記の例では、親セッションがどのようなサンドボックス設定でも、このエージェントは常に <code>read-only</code> で動作する。<br>
<br>
非インタラクティブフローでは、新たな承認が必要なアクションは失敗し、エラーが親ワークフローに返される。<br>
<br><br>

== エージェントの管理 ==
==== /agentコマンド ====
CLIでは <code>/agent</code> コマンドを使用して、アクティブなエージェントスレッド間の操作を行う。<br>
<br>
主な操作を以下に示す。<br>
* スレッドの切り替え
*: アクティブなエージェントスレッド間を切り替える。
* スレッドの検査
*: 進行中のエージェントスレッドの状態を確認する。
* エージェントの停止
*: 実行中のサブエージェントに直接指示を送り、停止させる。
* スレッドのクローズ
*: 完了したエージェントスレッドをクローズする。
<br>
==== 承認オーバーレイ ====
非アクティブなエージェントスレッドから承認リクエストが来た場合、オーバーレイ表示で通知される。<br>
<br>
オーバーレイにはソーススレッドのラベルが表示される。<br>
<code>o</code> キーを押下することにより、対応するスレッドを開いて詳細を確認してから、承認・拒否・回答を選択できる。<br>
<br>
 <syntaxhighlight lang="bash">
 # /agentコマンドの使用例
 
 /agent                # アクティブなスレッド一覧を表示
 /agent switch 2       # スレッド2に切り替え
 /agent close 3        # スレッド3をクローズ
 </syntaxhighlight>
<br><br>

== グローバル設定 ==
==== [agents]セクション ====
サブエージェントのグローバル設定は、<u>config.toml</u> の <code>[agents]</code> セクションに記述する。<br>
<br>
設定可能な項目を以下に示す。<br>
* <code>max_threads</code>
*: 同時にオープンできるエージェントスレッドの最大数
*: デフォルト値は6である。
*: <br>
* <code>max_depth</code>
*: サブエージェントのスポーン可能な入れ子の深さ。
*: デフォルト値は1であり、直接の子エージェントのスポーンは許可するが、それ以上の深いネストは防ぐ。
*: <br>
*: 深いネストはトークン消費、レイテンシ、リソース消費の増加を招くため、特に必要でない限りデフォルト値を維持することを推奨する。
*: <br>
* <code>job_max_runtime_seconds</code>
*: <code>spawn_agents_on_csv</code> ジョブにおける1ワーカー当たりのタイムアウト秒数
*: 設定しない場合、デフォルトは1800秒 (30分) である。
<br>
<code>[agents]</code> セクションの設定サンプルを以下に示す。<br>
<br>
 <syntaxhighlight lang="toml">
 [agents]
 # 同時オープン可能なスレッドの最大数 (デフォルト: 6)
 max_threads = 6
 
 # スポーン可能な入れ子の最大深度 (デフォルト: 1)
 # ルートセッションは深度0から開始される
 max_depth = 1
 
 # spawn_agents_on_csvジョブのワーカー当たりのタイムアウト秒数 (デフォルト: 1800)
 job_max_runtime_seconds = 1800
 
 # カスタムエージェント定義の例
 [agents.reviewer]
 description = "Find correctness, security, and test risks in code."
 config_file = "./agents/reviewer.toml"
 nickname_candidates = ["Athena", "Ada"]
 </syntaxhighlight>
<br>
<code>max_threads</code> は同時オープン可能なスレッド数を制限するが、深いネストによるコストと予測困難性のリスクは <code>max_depth</code> で管理する。<br>
<br><br>

== 推奨モデル ==
サブエージェントを利用する際は、メインタスクとサブエージェントで異なるモデルを使い分けることでコストと性能のバランスを最適化できる。<br>
<br>
<center>
{| class="wikitable"
|+ 用途別推奨モデル
! 用途 !! 推奨モデル !! 理由
|-
| メインセッション (ほとんどのタスク) || gpt-5.5 || 最高の推論能力<br>利用可能な場合はこちらを使用する。
|-
| メインセッション (gpt-5.5が未提供の場合) || gpt-5.4 || gpt-5.5が利用できない環境での代替モデル。
|-
| サブエージェント (高速・低コスト) || gpt-5.4-mini || 軽量で高速<br>単純な調査や分析タスクに最適。
|-
| コードベース探索 (ChatGPT Pro向け) || gpt-5.3-codex-spark || 探索に特化した軽量モデル。
|}
</center>
<br>
サブエージェントで重い処理が不要な場合は <u>gpt-5.4-mini</u> を割り当てることにより、トークン消費を抑制しつつ並列処理の恩恵を受けられる。<br>
<br><br>

== 実例ワークフロー ==
==== PRレビューの並列化 ====
サブエージェントの最も典型的な利用例は、PRレビューの並列化である。<br>
<br>
以下に示す観点ごとに1つのエージェントをスポーンして、全結果を待機してから統合サマリーを返すパターンが公式ドキュメントで紹介されている。<br>
<br>
並列化する6つの観点を以下に示す。<br>
* Security issue (セキュリティ上の問題)
* Code quality (コード品質)
* Bugs (バグ)
* Race (競合状態)
* Test flakiness (テストの不安定性)
* Maintainability of the code (コードの保守性)
<br>
公式ドキュメントのプロンプト例を以下に示す。<br>
<br>
 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
<br>
上記のプロンプトを実行すると、Codexは6つのサブエージェントを並列に起動し、各エージェントが独立してレビューを実施する。<br>
全エージェントの結果が揃った後、統合されたサマリーが返される。<br>
<br><br>

== カスタムエージェント定義例 ==
==== コードレビュー用エージェント ====
コードの正確性、セキュリティ、テストカバレッジのレビューを専門とするエージェントの定義例を以下に示す。<br>
<br>
* ファイル名の例
*: <u>.codex/agents/reviewer.toml</u>
*: <syntaxhighlight lang="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.
 """
 </syntaxhighlight>
<br>
==== テストランナー用エージェント ====
テストスイートの実行と結果分析に特化したエージェントの定義例を以下に示す。<br>
<br>
* ファイル名の例
*: <u>.codex/agents/test_runner.toml</u>
*: <syntaxhighlight lang="toml">
 name = "test_runner"
 description = "Specialized agent for running and analyzing test results. Use when verifying test coverage or debugging test failures."
 model = "gpt-5.4-mini"
 model_reasoning_effort = "medium"
 developer_instructions = """
 Execute test suites and analyze results.
 Report failures with clear reproduction steps and root cause analysis.
 Suggest improvements to test coverage when gaps are identified.
 """
 </syntaxhighlight>
<br>
==== ドキュメント生成用エージェント ====
APIや仕様を確認しながらドキュメントを生成するエージェントの定義例を以下に示す。<br>
<br>
MCPサーバを活用して外部ドキュメントへのアクセスを可能にしている。<br>
<br>
* ファイル名の例
*: <u>.codex/agents/docs_researcher.toml</u>
*: <syntaxhighlight lang="toml">
 name = "docs_researcher"
 description = "Documentation specialist verifying APIs and framework behavior. Use when creating or updating docs."
 model = "gpt-5.4-mini"
 model_reasoning_effort = "medium"
 sandbox_mode = "read-only"
 developer_instructions = """
 Analyze code and generate clear, accurate documentation.
 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"
 </syntaxhighlight>
<br><br>

== コスト考慮 ==
サブエージェントは各自が独立してモデルとツール実行を行うため、シングルエージェント実行と比較してトークン消費が大幅に増加する。<br>
<br>
コスト管理のために、以下の点を考慮することを推奨する。<br>
* 並列化が真に必要な場合のみサブエージェントを使用する。
*: 単純なタスクは従来のシングルエージェントで対応する。
*: <br>
* サブエージェントには軽量モデル (<code>gpt-5.4-mini</code>) を割り当てる。
*: 重い推論が不要な探索・調査タスクには特に有効である。
*: <br>
* <code>max_threads</code> を適切な値に設定する。
*: デフォルト値の 6 は多くのケースで適切な上限となる。
*: <br>
* <code>max_depth</code> は 1 (デフォルト) を維持する。
*: 深いネストはトークン消費、レイテンシ、リソース消費を指数的に増加させる可能性がある。
<br><br>

== IDE Extension対応状況 ==
サブエージェント機能は、現時点ではCLIとCodexアプリでのみサポートされている。<br>
<br>
* CLI
*: フル対応
*: <code>/agent</code> コマンドによるスレッド操作が可能。
* Codexアプリ
*: フル対応
*: サブエージェントの活動がGUIで可視化される。
* IDE Extension (VS Code、JetBrains等)
*: 現時点では未対応
*: 対応は、coming soonとして案内されている。
<br><br>

== 注意事項と推奨事項 ==
サブエージェントを効果的に活用するための注意事項とベストプラクティスを以下に示す。<br>
<br>
==== max_depth=1を維持 ====
<u><code>max_depth</code> のデフォルト値は <code>1</code> であり、特別な理由がない限り変更しないことを推奨する。</u><br>
<br>
この値を増やすと、広い委譲指示が繰り返しのファンアウトを引き起こし、トークン消費、レイテンシ、ローカルリソース消費が増加する。<br>
<br>
==== 明示的な役割定義 ====
各エージェントの <code>developer_instructions</code> に明確な責務を記述することが重要である。<br>
<br>
* 良い例
*: <syntaxhighlight lang="toml">
 developer_instructions = """
 Review code like an owner.
 Prioritize correctness, security, behavior regressions, and missing test coverage.
 Do not make code changes.
 """
 </syntaxhighlight>
*: <br>
* 曖昧な記述は避けるべきである。
*: <syntaxhighlight lang="toml">
 developer_instructions = """
 Help with code tasks.
 """
 </syntaxhighlight>
<br>
==== 高リスク操作の承認戦略 ====
読み取りのみを行うエージェントには <code>sandbox_mode = "read-only"</code> を明示的に設定することにより、意図しないファイル変更やコマンド実行を防止できる。<br>
<br>
<u>承認が必要な操作を行うエージェントを定義する場合は、<code>/approvals</code> の設定と組み合わせて運用することを推奨する。</u><br>
<br><br>

== 関連ページ ==
* [[Codexの設定 - 機能]]
* [[Codexの設定 - AGENTS.md]]
* [[Codexの設定 - SKILL]]
* [[Codexの設定 - MCPサーバ]]
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,電気回路,電子回路,基板,プリント基板
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]