Codex サブエージェント（Subagents）

サブエージェント（Subagents）は Codex の高度な機能であり、大規模なタスクをより小さな部分に分解し、並列または順次処理できます。このセクションでは、サブエージェントの設定方法と使用方法について詳しく説明します。

サブエージェントとは？

サブエージェントは、Codex が並列に呼び出せる補助エージェントで、複雑なタスクの異なる部分を処理するために使用します。サブエージェントを設定することで、以下のことが可能になります：

  • 大規模なタスクを管理可能な部分に分解する
  • 複数の独立したタスクを並列処理する
  • さまざまなタイプのタスクに特化したエージェントを設定する
  • 大規模プロジェクトの処理効率を向上させる

サブエージェントは、複数のファイルや複数の独立したタスクを同時に処理する必要があるシナリオに特に適しています。

サブエージェントの設定

基本設定

サブエージェントの設定

# マルチエージェント機能を有効にする
[features]
multi_agent = true

# エージェントパラメータを設定する
[agents]
# 最大並列スレッド数
max_threads = 6

# 最大ネスト深度
max_depth = 1

# ジョブ最大実行時間（秒）
job_max_runtime_seconds = 1800

カスタムエージェントロール

設定内でカスタムエージェントロールを定義できます：

エージェントロールの定義

# コードレビューエージェントを定義する
[agents.reviewer]
description = "コードレビューと品質問題に特化"
nickname_candidates = ["Reviewer", "CodeChecker", "QualityBot"]

# 設定ファイルを参照することもできます
# config_file = "agents/reviewer.toml"

サブエージェントの使用

サブエージェントを手動で呼び出す

Codex では、以下の方法でサブエージェントを呼び出すことができます：

サブエージェントの呼び出し

# @ を使用してサブエージェントにメンションする
@reviewer で src をレビュー/auth.py ファイル

# /agents コマンドを使用する
/agents run reviewer --task "すべてのテストファイルをレビュー"

サブエージェントを自動的に使用する

Codex はタスクに応じてサブエージェントを自動的に選択して使用できます。たとえば、大規模なリファクタリングタスクでは、Codex は異なるモジュールを処理するために複数のサブエージェントを自動的に起動することがあります。

サブエージェントの動作原理

並列処理

タスクを独立した部分に分解できる場合、サブエージェントは並列に動作できます：

任务：审查整个代码库
  ├─ 子代理 1：审查 src/auth/ 目录
  ├─ 子代理 2：审查 src/api/ 目录
  ├─ 子代理 3：审查 src/utils/ 目录
  └─ 主代理：汇总结果

順次処理

タスクに依存関係がある場合、サブエージェントは順番に動作します：

任务：实现新功能
  └─ 子代理 1：创建数据模型
       └─ 子代理 2：创建 API 端点
            └─ 子代理 3：编写测试

ネスト深度

設定内の max_depth は、エージェントがネストできる層の数を制御します：

  • 深度 0：ルートセッション
  • 深度 1：直接のサブエージェント
  • 深度 2：サブエージェントのサブエージェント
max_depth は 1 または 2 に保つことをお勧めします。ネストが深すぎると複雑さとコストが増加します。

ツール呼び出し

サブエージェントは Codex のすべての標準ツールを使用できます：

  • ファイルの読み取りと編集
  • コマンドの実行
  • スキルの使用
  • MCP サーバーの呼び出し

結果の集約

メインエージェントはすべてのサブエージェントの結果を集約し、統一された出力を提供します。

エージェントロールの設定

カスタムエージェントロールの作成

エージェントロール設定ファイルの作成

# agents/tester.toml

description = "単体テストと統合テストの作成に特化"
nickname_candidates = ["Tester", "TestBot", "QABot"]

[behavior]
# エージェントの動作設定
test_framework = "pytest" # 優先するテストフレームワーク
include_coverage = true # カバレッジレポートを含めることを要求

メイン設定で参照する

エージェント設定の参照

[agents.tester]
config_file = "agents/tester.toml"

サブエージェントの監視

アクティブなエージェントの表示

アクティブなエージェントの表示

# Codex で表示する
/agents status

# 詳細情報を表示する
/agents list

エージェントの出力

Codex は各サブエージェントの出力を表示し、メインインターフェースで結果を集約します。

サブエージェントの実行中は進行状況インジケーターが表示され、タスク全体の状態を把握できます。

ベストプラクティス

タスクの分解

  • 大規模なタスクを独立したサブタスクに分解する
  • サブタスク間に強い依存関係がないことを確認する（並列実行可能な場合）
  • 各サブタスクに明確な入力と出力を定義する

設定の最適化

  • タスクの複雑さに応じて max_threads を調整する
  • さまざまなタイプのタスクに特化したエージェントロールを設定する
  • 適切な job_max_runtime_seconds を設定して長時間の実行を避ける

監視とデバッグ

  • サブエージェントの出力を定期的に確認する
  • /agents status を使用して全体の進捗を把握する
  • 必要に応じて特定のサブエージェントをキャンセルできる
サブエージェントは高度な機能です。Codex の基本操作に慣れてから使用することをお勧めします。

よくある質問

Q: サブエージェントとスキルの違いは何ですか？

サブエージェントは独立した AI エージェントであり、複雑な多段階タスクを実行できます。スキルは事前定義されたワークフローであり、特定のタイプのタスクに特化しています。

Q: サブエージェントは最大でいくつ同時に実行できますか？

max_threads で設定され、デフォルトは 6 です。実際に利用可能な数はサブスクリプションプランによって異なります。

Q: サブエージェントは私のファイルにアクセスできますか？

はい、サブエージェントはファイルの読み取りと変更ができますが、サンドボックスとセキュリティポリシーの制限を受けます。

Q: サブエージェントの問題をデバッグするにはどうすればよいですか？

/agents status を使用してエージェントの状態を確認し、それらの出力ログを確認して問題を特定します。

その他の拡張