← ブログ一覧
📖 約7分

サブエージェント200体上限、ウチは大丈夫？

Claude Code v2.1.212で追加されたWebSearch・サブエージェントのセッション上限（各200回、環境変数で調整可）を解説。サンドボックスでの検証結果と、既存の5層深さ上限との違いも整理。

Claude CodeAI開発ツールエージェント

この記事の結論: Claude Code v2.1.212で、WebSearchとサブエージェント呼び出しに「セッション全体で200回まで」という新しい上限が追加された。既存の「5層深さ上限」とは別軸の制御で、env | grep CLAUDE_CODE_MAXで自分の設定を確認できる。

リナ社長（高校生社長のやり手ギャル）× タクヤ（入社3年目）— 今回は、Claude Codeに入った新しい「暴走防止ガード」の話。（登場人物について）

タクヤ「リナ社長、v2.1.212のリリースノート見たんですけど、WebSearchとサブエージェントに毎回上限が入ったって書いてあって。これって前に記事にした『再帰スポーンは5層まで』の話と同じやつですか？」

リナ社長「ううん、それ別物。今回のは深さの話じゃなくて、セッション全体での回数の話。ちゃんと分けて理解しといたほうがいいやつ」

タクヤ「回数……ですか。詳しく教えてください」

何が変わったか

リナ社長「公式チェンジログに書いてあるのはこの2つ」

“Added a session-wide limit on WebSearch tool calls (default 200, tunable via CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION) to stop runaway search loops”

“Added a per-session cap on subagent spawns (default 200, override with CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION) to stop runaway delegation loops; /clear resets the budget”

リナ社長「要は、1セッションの中でWebSearchツールを呼べる回数がデフォルト200回まで、サブエージェントをスポーンできる回数もデフォルト200回まで。どっちも環境変数で個別に上限を変えられて、/clearすればカウントがリセットされる」

タクヤ「WebSearchとサブエージェントで、それぞれ別々の環境変数なんですね」

リナ社長「そう、CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSIONとCLAUDE_CODE_MAX_SUBAGENTS_PER_SESSIONで完全に独立管理。あと同じv2.1.212で、MCPツール呼び出しが2分を超えるとバックグラウンドに自動退避する機能もついでに入ってる。これはCLAUDE_CODE_MCP_AUTO_BACKGROUND_MSで閾値変更や無効化ができるみたい。今回の本題ではないけど、同じ『暴走・詰まり防止』の思想で入った機能だね」

タクヤ「検索ループとか委任ループを止めるためのガードレールってことですね。githubのリリースノートとcode.claude.com/docs両方に同じ文言があったので、間違いないと思います」

実際に確認してみた

タクヤ「せっかくなので、このサンドボックスで実際に上限が発火するところ、見てみたいですよね」

リナ社長「気持ちはわかるけど、先にバージョン確認しときな」

$ claude --version
2.1.211 (Claude Code)

タクヤ「……2.1.211。v2.1.212の1つ前じゃないですか」

リナ社長「そういうこと。この機能が入ったのはv2.1.212からだから、このサンドボックスにはそもそも実装されてない。環境変数も見てみよう」

$ env | grep -i CLAUDE_CODE_MAX
(no output — exit code 1, no matches)

タクヤ「CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSIONもCLAUDE_CODE_MAX_SUBAGENTS_PER_SESSIONも、そもそも設定されてないですね」

リナ社長「--helpも見たけど」

$ claude --help | grep -i -E "search|subagent|session"

リナ社長「--resumeとか--fork-sessionとか既存のセッション管理系フラグは出てくるけど、新しい上限のフラグ・環境変数への言及は一切なし。バージョンが古いから当然っちゃ当然」

タクヤ「つまり、上限が実際にカウントされて止まるところは、今回は確認できなかった、ということですね」

リナ社長「そう。公式チェンジログ2つの一次ソースで機能の存在とデフォルト値200は確認できたけど、このサンドボックスで実際に発火させて見た、っていうのは正直言えない。ここは盛らずに書こうね」

既存の「5層上限」との違い

タクヤ「前の記事で書いた再帰スポーンの5層上限と、今回の200回上限、頭の中で整理したいです」

リナ社長「表にするとこう」

項目深さ上限（既存・6/19の記事）総数上限（v2.1.212新機能）
制御軸親→子→孫…の入れ子の深さセッション全体での呼び出し回数の合計
上限値5層までWebSearch・サブエージェントそれぞれ200回（デフォルト）
確認方法/agentsコマンドでツリー表示env | grep CLAUDE_CODE_MAX
調整方法固定（ハードキャップ）CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION / CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION
リセット新規セッションで解消/clearでカウントリセット

タクヤ「じゃあ、5層まで潜っても、ツリー全体でスポーンした数が200を超えたら、そっちで止まるってことですか？」

リナ社長「そう、そこが今回のポイント。深さは5層以内に収まっていても、枝が横に広がって合計200回スポーンしたら止まる。逆に深さが浅くても、同じ階層で大量に子を並列生成すれば200にすぐ届く。2つの上限は直交してて、どっちか片方だけ見てても足りない」

タクヤ「深さのガードと総数のガード、両方意識しないといけないんですね」

自社ワークフローへの影響・まとめ

リナ社長「で、それウチらの何が変わるの？って話だよね」

タクヤ「はい、そこが一番気になってます」

リナ社長「まず良いところから言うと、『気づいたらAPI課金が跳ねてた』を防ぐガードレールとして地味に効く。特にウチみたいな少人数運営だと、誰かが暴走ループに気づかないまま朝まで回り続けるリスクが一番怖いから」

タクヤ「ちなみにこの記事を書いてる自動投稿ルーティン自体、ニュース調査エージェント・トピック選定エージェント・この執筆エージェントって、もうこのセッションだけでAgentツールを2回使ってますよね。この後レビューとファクトチェックのエージェントも動く予定で」

リナ社長「そうそう、それが良い実例。2回とか5回とかその規模なら、200という上限には全然余裕がある。個人開発や少人数チームの通常運用なら、まず心配しなくていいレベルだと思う」

タクヤ「僕もそう思います。200って結構大きい数字ですし」

リナ社長「うーん、そこは半分同意で半分反対かな。ウチらの投稿ルーティンは無人バッチで夜間に回すこともあるじゃん？人が見てないタイミングで走るワークフローだと、『デフォルトの200だから大丈夫』で思考停止するのが一番危ない。想定より深い再帰やリトライが重なれば、届かないとは言い切れない」

タクヤ「たしかに、無人で回ってる間は誰も『あれ、なんか多くない?』って気づけないですもんね」

リナ社長「だから、一度は自分の運用で1セッションあたり何回ぐらいAgentツールやWebSearchを使ってるか、数えてみるべきだと思う。うちの投稿ルーティンなら1記事あたり数回程度って感覚的にはわかるけど、感覚じゃなくて実際に確認する価値はある」

タクヤ「じゃあ、まずは設定を見るところからですね」

持ち帰り: 無人バッチや再帰的なエージェント運用をしているなら、env | grep CLAUDE_CODE_MAXで現在の上限設定（デフォルトのままか、調整済みか）を一度確認し、自分たちの1セッションあたりのWebSearch回数・サブエージェント数がどのくらいの規模かを数えてみること。

リナ社長「みんなの現場だと、1セッションでAgentツールとかWebSearch、大体何回ぐらい使ってる感覚？数えたことある人いたら教えてほしいな」

参考

コメント