Codexでサブエージェントの上限を64に引き上げ可能。最初に壊れるのはどこ？

今週、ある設定スニペットが出回っています。Codexのconfig.tomlでagents.max_concurrent_threads_per_session = 64を設定すると、1つのセッションが数十個のサブエージェントにファンアウトする、というものです。発端となった投稿では、デフォルトは3で、OpenAIが64をテストしたと主張されています。設定自体は実在します。しかしこの2つの数字はドキュメントには記載がなく、面白いのは上限そのものではありません。上限を引き上げたときに作業に何が起きるか、です。

本記事では、Codexのリファレンスに基づいてこの設定が実際に何をするのか、そして1人の人間が読み切れないほどのエージェントを1つのセッションで動かしたときに、順番に壊れていく3つのポイントを解説します。

TL;DR

agents.max_concurrent_threads_per_sessionは、Codexが同時に開いておく生成済みエージェントスレッドの数を制限します（プライマリスレッドは含みません）。リファレンスにはデフォルト値が公開されておらず、このキーが未設定の場合はCodexがデフォルトを選択するとだけ書かれています。サブエージェントはメインスレッドに要約を返し、メインスレッドはすべての完了を待ってから一度だけ返信します。またドキュメントは、読み取り中心の作業にはサブエージェントを推奨する一方で、並列の書き込み中心ワークフローは競合と調整のオーバーヘッドを生むと警告しています。上限を64に引き上げると、まさにこの2点が浮き彫りになります。共有ファイルと、誰も監査できない1つの統合返信です。SharklyはCodexをRuntimeとして実行し、並列性を1つ上のレベルに引き上げます。そこでは各実行が独自のワークツリー、独自のログ、独自のレビュー担当を持つTaskになります。

この設定が行うこと

ここではconfig.tomlの[agents]セクションにある3つのキーが重要です。以下の文言は設定リファレンスからの引用です。

関連する2つのキー、agents.default_subagent_modelとagents.default_subagent_reasoning_effortは、スポーン呼び出しで別途指定がない限り、生成されたエージェントが何で動作するかを設定します。

つまり、このスニペットは書かれたとおりに機能します。

[agents]
max_concurrent_threads_per_session = 64

リファレンスに書かれていないのは、デフォルト値が何かということ、そして何らかの値がテストされたということです。ドキュメントに別の記載がない限り、「デフォルトは3」「OpenAIが64をテストした」はベンダーの主張ではなく、ある投稿の主張として扱ってください。

サブエージェントガイドには、上限引き上げが良い考えかどうかを左右する2つの文が追加されています。結果について：「多数のエージェントが実行中の場合、Codexは要求されたすべての結果が揃うまで待ち、その後、統合されたレスポンスを返します。」適性について：サブエージェントは「探索、テスト、トリアージ、要約といった読み取り中心のタスク」に適しており、ガイドは「並列の書き込み中心ワークフロー」には注意を促しています。なぜなら、エージェントが同時にコードを編集すると競合が生じ、調整のオーバーヘッドが増えるからです。

これらを合わせて読めば、壊れる順番はおのずと見えてきます。

最初に壊れるもの：共有チェックアウト

1つのセッション内のサブエージェントは、別途設定しない限りセッションの作業ディレクトリを共有します。読み取りだけを行う64個のエージェントなら問題ありません。書き込みを行う4個のエージェントにとってはマージの問題になります。

失敗は劇的なものではありません。2つのサブエージェントが同じファイルを編集し、2番目の書き込みが勝ち、統合サマリーは両方のタスクが完了したと報告します。レビューがあればレビューで、なければ本番で気づくことになります。ドキュメントの競合と調整オーバーヘッドに関する警告は、このことを指しています。

解決策は、あらゆる並列エージェント構成が行き着くものです。作業単位ごとに1つの作業コピーを持たせるのです。Sharklyでは、各Task実行が独立したディレクトリを取得し、リポジトリを基盤とする作業では実行ごとに別々のgitワークツリーを使用します。これは分離されたワークツリーでの並列エージェントで扱っている仕組みです。1つのリポジトリに対して10個のTask、共有状態はゼロです。編集を行うRuntimeは引き続きCodexでかまいません。分離はその周囲で提供されます。

次に壊れるもの：統合された返信

Codexはすべてのサブエージェントを待ち、1つのレスポンスを返します。サブエージェントが4個なら便利です。64個になると、64件の作業を要約した1つのメッセージになり、それを書くのは各作業をディスパッチしたエージェント自身で、中間出力は畳み込まれて見えなくなります。

これはレビューには不向きな形です。レビュー担当者は、各作業単位が何に触れ、何を実行し、どこで止まったかを知る必要があり、それぞれを個別に承認または却下できる必要があります。要約の要約は、部分的に承認することができません。

SharklyはAgentの最終レスポンスをTaskに保存し、実行ごとの実行ログ（トリガー、開始と終了、ツール呼び出し、Runtimeイベント、失敗の詳細）を保持します。実行はコメントタイムラインとは別の専用タブに表示されます。64件の作業単位は、64個のログを伴う64個のTaskとなり、それぞれがレビュー可能で、それぞれが人が確認する場所に結果を返します。

3番目に壊れるもの：ループ内の人間

この上限は、サブエージェントが人を必要としたときに何が起きるかについては何も語っていません。1つのセッション内では、ブロックされたサブエージェントは、統合された待機の中で静かになった1つのスレッドにすぎません。メインスレッドがあなたの代わりに答えることはできず、64個のスレッドのうちどれが停止したのかも分かりません。

SharklyはTaskのステータスとAgentの作業状態を分けて保持します。開始済みのTaskは、作業中、人間の返信待ち、人間のレビュー待ち、エラーを表示できます。待機や失敗のシグナルは、担当者のInboxのPrimaryセクションに届き、Taskへの返信がそのスレッドをコンテキストとして後続の実行を開始します。詰まっているものは、検査できない待機の中でぶら下がるのではなく、あなたに知らせてくれます。

サブエージェントかTaskか？ 判断の分かれ目

作業が読み取り中心で、1つの答えに収束する場合は、1つのセッション内でCodexのサブエージェントを使いましょう。コードベースの探索、失敗のバッチのトリアージ、ドキュメント群の要約、テストスイートの実行などです。ガイドが推奨しているのはこうした用途であり、何も書き込みをしないのであれば、上限を高くしてもコストはかかりません。

作業単位がコードを書き込む場合、異なる人が異なる部分をレビューする場合、または実行の途中で人が答える必要がある場合は、それぞれをComputer上のAgentに割り当てた別々のTaskを使いましょう。SharklyはCodexの置き換えではありません。Codexは各Taskを実行するRuntimeです。違いは並列性がどこにあるかです。1つのセッションの統合された待機の中にあるのか、それとも、コンテキスト、進捗、ブロッカー、結果、人間のレビューが要求からリリースまで見える状態に保たれるボード全体にまたがっているのか、です。

上限を安全に引き上げる方法

max_concurrent_threads_per_sessionを引き上げるなら、Sharkly自身の並行処理ドキュメントがComputerについて説明している方法で行ってください。現在の構成が既存のワークロードを安定して処理できてから初めて引き上げるのです。並行度を高くすると、CPU、メモリ、ディスク、プロバイダーの容量、リポジトリの帯域幅をより多く消費するからです。SharklyのComputerには独自のタスク並行処理の上限があり、一時ディレクトリを使用するAgentはデフォルトでその半分になります。容量はComputer、Agentの並行度、ディレクトリの可用性によって制限され、その容量が満杯でもオンラインのAgentにキューされた作業が残っていることがあります。

人々が忘れがちなのがプロバイダーの容量です。1つのAPIキーに対して64個のスレッドは、同時にレート制限に達する64通りの方法です。そして「クォータを使い切った」を意味する429は、リトライしても解決しません。Sharklyの失敗実行ログは、プロバイダーの元のレスポンスを分かりやすいタイトルと並べて保持するので、誰かがリトライする前にその違いが分かります。

よくある質問

agents.max_concurrent_threads_per_sessionのデフォルト値は何ですか？ 設定リファレンスには記載されていません。キーが未設定の場合、Codexがデフォルトを選択すると書かれているだけです。SNSで出回っている数字はリファレンスに基づくものではありません。

上限を引き上げるとCodexは速くなりますか？ 読み取り中心のファンアウトでは、スレッドが多いほど早く終わります。書き込み中心の作業では、並行編集が競合と調整オーバーヘッドを生み、並列化で節約できる以上の時間がかかるとドキュメントは警告しています。

Codexのサブエージェントは別々のgitワークツリーで実行されますか？ サブエージェントガイドにはそのようには書かれていません。自分で分離を設定していない限り、作業ディレクトリを共有するものとして計画してください。

SharklyはCodexをどのように使用しますか？ Runtimeとしてです。Codexを実行しているComputerはそれを利用可能として報告し、そのComputer上のAgentに割り当てられたTaskはそれを介して実行され、各実行は独自の分離されたディレクトリまたはワークツリーで行われます。

SharklyのTask内でもサブエージェントを使用できますか？ はい。Runtimeが単独でできることはすべて、実行内でも機能します。Sharklyはその周囲にTask、分離、ログ、レビューを追加します。

まとめ

設定は実在し、スニペットも機能します。しかし、64件の並行編集を安全にするわけでも、1つの統合返信をレビュー可能にするわけでも、どのスレッドがあなたを待っているかを教えてくれるわけでもありません。これらが順番に壊れていく3つのポイントです。読み取り中心のファンアウトにはサブエージェントを使い続け、書き込み中心の並列作業は、各実行が独自のワークツリーと独自のレビュー担当を持つボードに載せましょう。Codexを載せたComputerを1台接続し、Agentを1つ作成して、何か地味な作業を割り当ててみてください。各概念はドキュメントでより詳しく解説しています：docs.sharkly.ai。