要点
- Codex CLIのサブエージェント機能を使うと、設計と最終判断を親エージェント（GPT-6 AstraまたはGPT-6 Sol）に、境界が明確な作業を子エージェント（GPT-6 Luna）に分担できます。
-
.codex/config.tomlの[agents]にdefault_subagent_model = "gpt-6-luna"を置くだけの最小構成と、.codex/agents/*.tomlでLuna専用のカスタムエージェントを定義する実務構成の2段階があります。 - 親には委譲対象・作業境界・完了条件・結果待ちを明示する必要があり、同じファイルを複数の子に同時編集させると差分が衝突します。
- セットアップを自動化するPythonスクリプトも紹介します。
はじめに
この記事は、Codex CLIでマルチエージェント開発を試したいエンジニアを対象にしています。Codexのサブエージェント設定を使い、設計や最終判断を親エージェントに、境界が明確な作業を子エージェントに任せる方法を解説します。
たとえば「会議室予約アプリにキャンセル機能を追加する」という要求なら、AstraまたはSolが仕様・変更範囲・受け入れ条件を決めます。Lunaには、API実装、画面の小さな変更、テスト用データの確認など、範囲と完了条件を明示した仕事を渡します。親が子の結果を読み、統合と最終検証を担当する流れです。
GPT-6世代の現在のCodexでは、サブエージェントのモデル指定が以前より簡単になっています。2026年5月時点の [agents] の主な項目は、同時スレッド数の上限（max_threads）と入れ子の深さの上限、そして役割ごとの定義でした。子を起動するときにモデルを明示したり、役割ごとの設定でモデルを変えたりはできましたが、[agents] に子の既定モデルを一括で決める項目はありませんでした。現在は default_subagent_model の1行で子の既定モデルを決められます。役割ごとの定義は、必要なときだけ追加すれば済みます。なお max_threads は max_concurrent_threads_per_session に名前が変わり、旧名も引き続き使えます。
本記事は2026年9月26日時点で確認できた公式資料をもとに作成しています。製品の展開状況、設定項目、利用可能なモデルは更新されるため、導入時はリンク先の最新版を確認してください。
1. 仕組みと役割分担
Codexのサブエージェントは独立したコンテキストで作業し、親が委譲・結果の回収・統合を行います。Codex CLI、IDE拡張、対応するアプリで利用できます。ローカルCodexではカスタムエージェントごとにモデルと指示を設定できます。
| 担当 | 向いている仕事 | 選択の目安 |
|---|---|---|
| Astra（親） | 曖昧な要求の整理、広い変更の設計、トレードオフと最終判断 | 複雑で要求の解釈が難しい案件 |
| Sol（親） | 通常の実装計画、委譲、統合、レビュー | 日常の開発では最初の選択肢 |
| Luna（子） | コード探索、明確な小規模実装、定型的なチェックや要約 | 入力、変更対象、完了条件が明確な仕事 |
この表はモデルの使い分けをもとにした実務上の提案です。公式のモデル選択ドキュメントでは、Solは複雑なコーディング、Lunaは範囲が明確で繰り返しの多いタスク、Astraは最も難しい仕事に位置付けられています。
親と子を分ける効果は、並行処理に加えて、探索ログやテスト出力で親の会話を埋めにくいことです。一方で各エージェントは個別にトークンを使います。同じファイルを複数の子に同時編集させると競合するため、まず探索の並行化から始め、編集の所有範囲を分けるとよいでしょう。
2. 最小構成: 親Sol／子Luna
2-1. プロジェクト設定
リポジトリ直下に .codex/config.toml を作ります。これはプロジェクト用の例で、Codexが信頼済みと認識するプロジェクトで読み込まれます。全プロジェクトで共通にしたい場合は ~/.codex/config.toml を使います。
[agents]
enabled = true
default_subagent_model = "gpt-6-luna"
default_subagent_reasoning_effort = "high"
max_concurrent_threads_per_session = 3
default_subagent_model は子の既定モデルです。max_concurrent_threads_per_session は、親を除いて同時に開いておける子スレッドの上限を指します。推論レベルの出発点として、公式資料はGPT-6 Lunaでは high、GPT-6 Solでは medium、GPT-6 Astraでは low を挙げています。小さい作業で過剰だと感じたら、実測して下げてください。
2-2. 親モデルを選んで起動
# 通常の実装案件
codex -m gpt-6-sol
# 要件が曖昧・横断的で、より強い判断が必要な案件
codex -m gpt-6-astra
CLIの対話中なら /model でも親のモデルを切り替えられます。アプリでは入力欄のモデル選択を使います。表示と利用可否は、プラン・クライアント・ワークスペースの設定や展開状況で変わります。
2-3. 親への依頼文
このリポジトリに会議室予約のキャンセル機能を追加してください。
あなたは監督役として仕様の確認、タスク分割、統合、最終検証を担当してください。
独立して進められるコード探索と小さな実装は、Lunaのサブエージェントに委譲してください。
各エージェントには対象ファイル、完了条件、編集の可否を明示してください。
同じファイルを複数のエージェントに同時編集させないでください。
必要な子の結果を待ち、差分と変更に見合ったテスト結果を確認してから最終報告してください。
受け入れ条件を満たすまで実装・検証・修正を続け、確認を求めるのは破壊的・不可逆な操作の前だけにしてください。
現在のローカルCodexでは、明示的な委譲依頼や、適用される AGENTS.md／スキルの指示を契機に子を起動します。なお、ChatGPTのUltraインテリジェンスレベルでは、依頼がなくても適した独立作業を自発的に委譲することがあります。CLIでは /agent で各スレッドの進捗を確認できます。
この設定は原則として子の既定値をLunaにします。レビューだけSolにしたい場合は、明示的なspawn指定か、次節のSol専用カスタムエージェントを使ってください。カスタムエージェントの model 設定は、spawn時の指定や既定値より優先されます。
3. 実務構成: Luna専用エージェント
作業役を名前で固定すると、親が毎回モデルや責任範囲を説明する手間が減ります。.codex/agents/ の各TOMLには name、description、developer_instructions が必須です。
3-1. 探索担当: Luna／読み取り専用
name = "luna_explorer"
description = "予約フローと影響範囲を調べる読み取り専用エージェント。"
model = "gpt-6-luna"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
親が指定した機能に関係する実際のコード経路を調べる。
広い走査より、的を絞った検索とファイル読み込みを優先する。
変更を加えず、関連ファイル、主要シンボル、制約、未確認事項を簡潔に返す。
推測は事実と区別し、可能ならファイル名と行を示す。
"""
3-2. 実装担当: Luna／範囲を限定して編集
name = "luna_implementer"
description = "親が指定したファイルと受け入れ条件だけを実装する作業役。"
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
親が指定したファイルだけを担当する。
指示に対象や完了条件がなければ、推測で範囲を広げず親へ返す。
境界外の変更が必要なら親へ理由を返す。
最小限の実装と、変更した挙動の検証を行い、変更ファイル、テスト結果、残課題を報告する。
同時進行の他エージェントが所有するファイルは編集しない。
"""
編集権限は親の実行環境や承認設定にも従います。カスタムエージェントで権限を強められると仮定せず、親の権限設定と実行時の承認を確認してください。
3-3. レビュー担当: Sol／読み取り専用（任意）
name = "sol_reviewer"
description = "実装差分の正しさ、回帰、テスト不足を確認するレビュー担当。"
model = "gpt-6-sol"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
仕様と差分を照合し、実害のある問題を優先する。
各指摘に根拠となるファイル、再現条件、修正案を付ける。
コードは編集しない。問題がなければ確認範囲と残るリスクを返す。
"""
親をAstraにして、探索・実装をLuna、レビューをSolにする三段階構成も可能です。ただし子のSolがさらにLunaを監督する階層まで増やす必要は、通常はありません。ここでは、Astra／Solの親が最終責任を持つ単純な構成を扱います。
3-4. カスタムエージェントを指定する依頼文
あなたが設計と最終統合を担当してください。
まず luna_explorer に既存の予約状態遷移とAPIの関連箇所を調査させてください。
調査結果を踏まえ、変更範囲を限定して luna_implementer に実装を委譲してください。
実装完了後、sol_reviewer に差分を読ませ、指摘は重要度順にファイル参照付きで返させてください。
子の結果を待ち、あなた自身で仕様とテスト結果を確認して報告してください。
カスタムエージェントはローカルCodex向けの機能です。ChatGPT Workの画面上で同じTOMLファイルを直接設定できると考えず、利用するクライアントの設定方法を確認してください。
4. 簡単セットアップ手順
ここまでの設定をまとめて用意するスクリプトを紹介します。setup_codex_supervisor.py はリポジトリ内にLuna用のカスタムエージェント2種を作成し、AGENTS.md に監督・委譲の方針を追記します。起動時にはCLIオプションで親モデルと子の既定モデルを指定します。既存の .codex/config.toml は書き換えません。既存のエージェント定義や、自動生成した指示ブロックが異なる内容の場合は、上書きせず停止します。リポジトリ直下に AGENTS.override.md がある場合も停止します。
以下を setup_codex_supervisor.py として保存し、対象リポジトリ直下に置いてください。Python 3.9以降の標準ライブラリだけで動きます。--setup-only を指定した場合はCodex CLIを起動しません。
setup_codex_supervisor.py 全文
#!/usr/bin/env python3
"""Set up a Sol/Astra supervisor and Luna subagents for a local Codex project.
Usage:
python3 setup_codex_supervisor.py --setup-only
python3 setup_codex_supervisor.py --parent sol
python3 setup_codex_supervisor.py --parent astra -- "Implement cancellation"
"""
from __future__ import annotations
import argparse
import os
from pathlib import Path
import shutil
import sys
START = "<!-- codex-supervisor:start -->"
END = "<!-- codex-supervisor:end -->"
AGENTS_BLOCK = f"""\
{START}
## Codex subagent workflow
- The parent agent owns requirements, task boundaries, integration, and final verification.
- Delegate code exploration to `luna_explorer` when it spans two or more
independent areas, running those explorations in parallel. Delegate small
implementation tasks to `luna_implementer` when the target files and
acceptance criteria can be stated up front. Keep short tasks that gain nothing
from delegation in the parent thread. For dependent steps, do not run them in
parallel; delegate each one after receiving the result it depends on.
- Give each subagent the target, allowed files, acceptance criteria, and expected
report. Do not assign the same file to concurrent writers.
- Wait for delegated results. Inspect the actual diff, and run checks
appropriate to the change; broaden testing only when failures or unresolved
concerns justify it.
- Keep implementing, verifying, and fixing until the acceptance criteria are met.
Ask for confirmation only before destructive or irreversible operations.
{END}
"""
AGENT_FILES = {
"luna_explorer.toml": '''name = "luna_explorer"
description = "Read-only codebase explorer for bounded questions."
model = "gpt-6-luna"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Investigate only the question from the parent. Make no edits.
Prefer fast, targeted search and file reads over broad scans.
Return relevant files and symbols, evidence, unresolved questions, and a
concise summary. Separate observed facts from inferences.
"""
''',
"luna_implementer.toml": '''name = "luna_implementer"
description = "Implement a small, explicitly scoped change."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Work only within the files and acceptance criteria specified by the parent.
If the target or acceptance criteria are not specified, do not guess and
expand scope; return the question to the parent instead.
Do not edit files owned by another active agent. If the scope must expand,
return the reason to the parent before making an out-of-scope change.
Report changed files, checks for the changed behavior, and unresolved issues.
"""
''',
}
def plan_writes(repo: Path) -> list[tuple[Path, str]]:
override = repo / "AGENTS.override.md"
if override.exists():
raise ValueError(
f"{override} があるため停止しました。\n"
"同じ階層では AGENTS.override.md が AGENTS.md より優先され、"
"追記した方針が読み込まれません。方針を手動で統合してください。"
)
agents_dir = repo / ".codex" / "agents"
writes: list[tuple[Path, str]] = []
conflicts: list[str] = []
for name, content in AGENT_FILES.items():
path = agents_dir / name
if path.exists():
if not path.is_file() or path.read_text(encoding="utf-8") != content:
conflicts.append(str(path))
else:
writes.append((path, content))
instructions = repo / "AGENTS.md"
if instructions.exists():
if not instructions.is_file():
conflicts.append(str(instructions))
else:
current = instructions.read_text(encoding="utf-8")
if START in current or END in current:
if current.count(START) != 1 or current.count(END) != 1:
conflicts.append(str(instructions))
else:
block = current[current.index(START) : current.index(END) + len(END)]
if block != AGENTS_BLOCK.strip():
conflicts.append(str(instructions))
else:
separator = "" if not current else ("\n" if current.endswith("\n") else "\n\n")
writes.append((instructions, current + separator + AGENTS_BLOCK))
else:
writes.append((instructions, "# AGENTS.md\n\n" + AGENTS_BLOCK))
if conflicts:
raise ValueError(
"既存の内容が異なるため、上書きせず停止しました:\n- "
+ "\n- ".join(conflicts)
+ "\n内容を確認し、手動で統合してください。"
)
return writes
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--repo", type=Path, default=Path.cwd(), help="対象リポジトリ (既定: 現在のディレクトリ)")
parser.add_argument("--parent", choices=("sol", "astra"), default="sol")
parser.add_argument("--setup-only", action="store_true", help="ファイルを生成して終了")
parser.add_argument("prompt", nargs=argparse.REMAINDER, help="-- の後にCodexへ渡す依頼文")
args = parser.parse_args()
repo = args.repo.expanduser().resolve()
if not repo.is_dir():
parser.error(f"ディレクトリがありません: {repo}")
if not args.setup_only and shutil.which("codex") is None:
parser.error("codex コマンドが見つかりません。--setup-only なら設定ファイルだけ作成できます。")
try:
writes = plan_writes(repo)
except (ValueError, OSError, UnicodeError) as exc:
parser.error(str(exc))
for path, content in writes:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(content, encoding="utf-8")
print(f"作成・追記: {path}")
if not writes:
print("設定済みです。既存ファイルに変更はありません。")
if args.setup_only:
return 0
prompt = args.prompt[1:] if args.prompt[:1] == ["--"] else args.prompt
command = [
"codex",
"-m", f"gpt-6-{args.parent}",
"-c", "agents.enabled=true",
"-c", 'agents.default_subagent_model="gpt-6-luna"',
"-c", 'agents.default_subagent_reasoning_effort="high"',
"-c", "agents.max_concurrent_threads_per_session=3",
]
if prompt:
command += ["--", " ".join(prompt)]
print(f"起動: gpt-6-{args.parent} (親) + gpt-6-luna (子)", flush=True)
os.chdir(repo)
os.execvp(command[0], command)
return 0
if __name__ == "__main__":
sys.exit(main())
# スクリプトを対象リポジトリ直下に置いてから実行
python3 setup_codex_supervisor.py --setup-only
# Solを親として起動する（依頼は起動後の対話画面で入力する）
python3 setup_codex_supervisor.py --parent sol
# Astraを親として起動し、同時に最初の依頼を送る（依頼文は省略できる）
python3 setup_codex_supervisor.py --parent astra -- "会議室予約のキャンセル機能を実装して"
# 別ディレクトリのリポジトリに適用
python3 setup_codex_supervisor.py --repo /path/to/repo --setup-only
--setup-only はファイルを生成するだけで、Codexは起動しません。--parent を付けると、スクリプトが codex -m gpt-6-sol（または gpt-6-astra）に -c agents.default_subagent_model="gpt-6-luna" などを付けて起動し、そのまま同じターミナルで通常のCodex CLIの対話画面に切り替わります。依頼文は省略でき、省略すると空の対話画面が開きます。-- の後ろに依頼文を書くと、起動と同時にそれが最初のメッセージとして送られ、Codexがすぐ作業を始めます。これは codex 自体が起動時に最初の依頼を受け取れる仕組みをスクリプトが中継しているだけで、以降は同じ画面で普段どおりやり取りできます。-c の指定はその起動にだけ効くため、スクリプトを通さずに codex を起動するときも同じ構成にしたい場合は、2節の .codex/config.toml も設定してください。
生成されるファイル構成は次のとおりです。
repo/
├── AGENTS.md
├── setup_codex_supervisor.py
└── .codex/
└── agents/
├── luna_explorer.toml
└── luna_implementer.toml
AGENTS.mdには何を書くか
継続して同じ分担を使うなら、AGENTS.md に方針を書くのが適切です。親が要件・統合・最終検証を担当し、独立して範囲が明確な仕事をLunaへ渡す条件、ファイルの所有範囲、結果を待つことを短く記述します。AGENTS.md はプロジェクトに置ける持続的な指示で、子のモデル名そのものはカスタムエージェントのTOMLか起動設定で指定します。
## Codex subagent workflow
- 親は要件、作業境界、統合、最終検証を担当する。
- 独立した領域が2つ以上ある探索は luna_explorer へ並列に委譲し、
対象ファイルと受け入れ条件を示せる小さな実装は luna_implementer に
委譲する。委譲しても利点のない短い作業は親が行う。依存する工程は並列に
せず、先行する結果を受け取ってから委譲する。
- 子には対象、編集可能なファイル、受け入れ条件、報告形式を伝える。
- 同じファイルを複数の子に同時編集させない。
- 子の結果を待ち、親が実際の差分を確認し、変更に見合ったテストを実行する。
失敗や未解決の懸念がある場合だけ検証範囲を広げる。
- 受け入れ条件を満たすまで実装・検証・修正を続け、確認を求めるのは
破壊的・不可逆な操作の前だけにする。
付属スクリプトは、既存の AGENTS.md があれば専用ブロックを追記し、再実行しても重複させません。プロジェクト固有の指示と衝突する場合は、人が方針を統合してください。同じ階層に AGENTS.override.md があると、Codexはそちらを優先して AGENTS.md を読み込みません。スクリプトがリポジトリ直下の AGENTS.override.md を見つけて停止するのはこのためです。下位ディレクトリに AGENTS.override.md がある場合も、その指示の適用関係を確認してください。
AGENTS.md はプロジェクト全体の指示として、親（Astra／Sol）も読み込みます。子への細かい制約はカスタムエージェントのTOMLに置き、AGENTS.md 自体は親の役割・委譲条件・検証方針を短く書くにとどめます。Sol・Lunaに役立つ指示をAstraのAGENTS.mdにそのまま残すと、Astraを縛りすぎて途中で止まる原因になります。
「ルール」にも書くべきか
Codexの .codex/rules/*.rules は、サンドボックス外で実行するコマンドの許可・確認・禁止を指定する実行ポリシーです。モデル選択や委譲方針はそこに記述しません。「このコマンドは承認を必要とする」といった別の要件がある場合にだけ使います。
| 設定先 | 担当すること |
|---|---|
.codex/config.toml／起動時 -c
|
子の既定モデル、推論レベル、同時スレッド数 |
.codex/agents/*.toml |
役割ごとのモデル、権限、具体的な作業指示 |
AGENTS.md |
プロジェクト全体の委譲条件、作業分担、検証方針 |
.codex/rules/*.rules |
コマンド実行に対する許可・確認・禁止 |
5. 会議室予約アプリの実践例
機能要件を「予約者は開始時刻までキャンセル可能。キャンセル後は空き枠に戻る。二重操作でも状態が壊れない」とします。以下の切り分けは実装例であり、実際のテーブル名やAPIパスは既存リポジトリに合わせてください。
| 順序 | 担当 | 指示する仕事 | 親への返却物 |
|---|---|---|---|
| 1 | 親 Astra／Sol | 現状と要件を照合し、受け入れ条件を決定 | 作業分担・変更境界 |
| 2 | Luna explorer | 予約状態、認可、空き枠計算、既存テストを探索 | ファイルと状態遷移の一覧 |
| 3 | Luna implementer | 指定されたAPI／DB更新の小範囲を実装 | 差分、検証結果、判断を要する点 |
| 4 | 親 または Sol reviewer | 権限、開始時刻判定、競合、回帰を確認 | 具体的な指摘 |
| 5 | 親 Astra／Sol | 修正を統合し、適切なテストと最終報告 | 完成した変更と確認結果 |
親がLunaに渡す作業指示の例
担当: キャンセルAPIの実装
目的: 予約者本人が開始時刻前に予約をキャンセルできるようにする。
変更対象: 既存の予約APIの関連ファイルと、その単体テストだけ。
前提: 既存の認証と予約Repositoryを使う。DBスキーマや画面は変更しない。
受け入れ条件:
1. 本人以外のキャンセルは拒否する。
2. 開始時刻以降は拒否する。
3. 同じ予約への再試行は既存のAPI規約と整合させる。
4. 状態更新と空き枠の扱いが既存のトランザクション規約に従う。
結果報告: 変更ファイル、判断した仕様、実行したテスト、残る懸念。
境界外の変更が必要になったら実装を広げず、親へ相談する。
実装の前に、探索結果を使ってファイル所有者を決めるのがポイントです。画面とAPIを並行実装できる場合でも、同じ型定義やスキーマを両者に触らせると衝突しやすいため、共通契約は親が先に決めます。
親が最後に確認する項目
- 要件と実際の状態遷移が一致するか。認可チェックが抜けていないか。
- 開始時刻のタイムゾーン、同時キャンセル、空き枠復帰の一貫性。
- 子の報告だけでなく、実際の差分と重要なテスト結果を確認したか。
- 変更範囲外のファイルを子が触っていないか。
6. GPT-6世代での指示の書き方
OpenAIのブログ「Rethinking skills and prompts for GPT-6 Astra」によると、モデルが賢くなったことで、以前必要だった手取り足取りの指示が不要になり、細かすぎる指示はかえって結果を悪くしうるとされています。同ブログは、Sol・Lunaに役立つ指示がAstraには制約になりすぎることがあるため、どのモデルが読む指示かを意識するよう求めています。ここでの見直し対象は、親が読むAGENTS.mdと依頼文で、特にAstraを親にするときに効いてきます。子（Luna）への指示は、対象・完了条件・報告形式を狭く具体的に書く従来の方針のままで問題ありません。
- 委譲する条件は具体的に書きます。GPT-6 Astraのガイドによると、Astraはこちらが望むほど委譲しないことがあります。「役立つときに委譲する」ではなく、「独立した領域が2つ以上あれば並列に委譲する」のように判断できる形にします。
- 完了条件を先に決め、満たすまで続けさせます。Astraは最初の実装ができた段階で、作業が残っていても確認を求めて戻ることがあります。着手前に受け入れ条件を示し、それを満たすまで続けるよう伝えます。
- テストは変更に見合った範囲にします。以前のモデルにはテストを促す指示が必要でしたが、Astraは自分から検証します。同じ指示を残すと、過剰なテストにつながります。
- 親を止めうる指示は
AGENTS.mdではなく子のTOMLに置きます。ガイドによると、AstraはAGENTS.mdなどの指示に敏感で、曖昧な指示があると早い段階で作業を止めることがあります。「判断に迷ったら上位へ確認」のような文言は、子のカスタムエージェント定義に書きます。
7. 失敗しやすい点と運用ルール
| 症状 | 原因・対処 |
|---|---|
| 子がLunaにならない | 設定ファイルの場所とTOMLを確認する。カスタムエージェントの model は既定値より優先される。明示spawn値や親からの継承も確認する。 |
| 子が起動しない | 「サブエージェントに委譲」と明示する。agents.enabled とクライアントの対応状況を確認する。 |
| Lunaの品質が揺れる | 依頼を狭め、入力・対象ファイル・完了条件・出力形式を具体化する。曖昧な判断は親へ戻す。 |
| 差分が衝突する | 担当ファイルを分ける。共通スキーマや共有型は親が先に決める。依存する工程は順番に進める。 |
| 費用や時間が増える | 独立性のない細切れ作業まで子にしない。並列化の利点と追加トークンを実測する。 |
| レビュー漏れ | 親が受け入れ条件に照らして差分と重要なテストを確認する。必要ならSolのレビュー担当を追加する。 |
モデルの優先順位は、カスタムエージェントのファイル内設定が最上位です。その前段では、明示spawn指定、[agents] の既定値、親からの継承の順に解決されます。モデルだけ切り替えた際は、推論レベルとの整合にも注意してください。
APIのモデル単価と、ChatGPTサインインで使うCodexのクレジットやプラン上の利用量は、同じ計算方法とは限りません。子の数を増やすほど総使用量が増える傾向があり、最適な分担は同じ実タスクで品質・時間・使用量を測って決めてください。
8. Agents APIを使う場合
自作サービスからCodexのマネージドハーネスを利用するなら、Agents APIで親の model と multi_agent を設定できます。以下は公式ドキュメントの例で、親Astraが2つのリリースノートをそれぞれ子に分析させ、結果を1つの要約にまとめます。分析対象は input に本文ごと渡します。子のモデルをLunaへ固定する設定例ではないため、Codex CLIの [agents]／カスタムエージェント設定とは区別してください。
import OpenAI from "openai";
const client = new OpenAI();
const events = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions:
"Delegate each release to a separate subagent. Ask each to extract customer-visible changes and required migration steps using only its release notes. Wait for both results, then combine them into one release summary with release labels. Do not invent missing details.",
multi_agent: { enabled: true, max_concurrent_subagents: 2 },
},
environment: { type: "none" },
input:
"Release A: Search now supports filtering by date. Existing queries continue to work. Release B: The export endpoint now returns a download URL instead of file bytes. Update clients to fetch that URL.",
stream: true,
});
for await (const event of events) {
console.log(JSON.stringify(event));
}
APIで独自の厳密なモデルルーティングを実装したい場合は、親子それぞれをアプリ側で別のモデル呼び出しとして管理する設計もあります。ただしその場合は、タスク配布・ツール権限・再試行・結果統合を自分のアプリ側で設計する必要があります。上のAgents API例は「子=Luna」を保証するものではありません。
まとめ
親を gpt-6-sol または gpt-6-astra で起動し、子の既定値を [agents] でLunaにするか、Luna専用カスタムエージェントを定義します。プロンプトでは委譲対象・作業境界・完了条件・結果待ちを明示し、親が差分とテストを確認して最終判断を行う流れが基本です。
最初は「Solが監督、Lunaが探索と小さな実装」を試し、曖昧な要件や横断的な判断が増えるときに親をAstraへ切り替える構成が扱いやすいでしょう。親をAstraにする場合は、委譲条件と完了条件を具体的に書き、テストを促す指示を控える6章の書き方も併せて見直してください。
参考資料
-
Subagents（OpenAI Codex ドキュメント） — 委譲の起動方法、モデル継承、
[agents]、カスタムエージェント、権限。 - Models（OpenAI Codex ドキュメント） — CLIでのモデル指定、アプリでの切り替え、利用可否。
- Model selection（OpenAI Developers ドキュメント） — Astra、Sol、Lunaの用途。
- Config Basics（OpenAI Codex ドキュメント） — 設定ファイルの基本。
- Agents API: Multi-agent（OpenAI Developers ドキュメント） — マネージドハーネスでの委譲。
- AGENTS.md（OpenAI Codex ドキュメント） — 永続的な指示とプロジェクトでの適用。
- Rules（OpenAI Codex ドキュメント） — コマンド実行ポリシー。
- Rethinking skills and prompts for GPT-6 Astra（OpenAI Developers ブログ） — モデルが賢くなったことに合わせた指示の見直し方。
- GPT-6 Astra ガイド（OpenAI Developers ドキュメント） — GPT-6 Astraのプロンプティングガイド。