約 4 分で読めます

Claude Tool Runnerの上限設定とエラー傍受の設計

社内向けエージェントのツール呼び出しループを自前で書き、結果の返し方を間違えて400エラーを出した。あるいはツールが失敗し続けて、ループが止まらなかった。小さなチームほど、この種の「ループ周りの事故」に時間を取られます。SDKのTool Runnerは、その実装を肩代わりする仕組みです。ただし任せきりにすると、上限とエラーの扱いが見えなくなります。

Tool Runnerは何を肩代わりしてくれるのか

Tool Runnerは、ツール実行・結果の返送・会話状態の管理を自動化するSDKの機能です。2026年11月時点ではベータ版です。

公式ドキュメントによると、Tool Runnerは次の4点を自動で行います。

  • Claudeがツールを呼んだときに、そのツールを実行する
  • リクエストとレスポンスの往復を処理する
  • 会話の状態を管理する
  • 型の安全性と入力の検証を提供する

Python、TypeScript、C#、Go、Java、PHP、Ruby の各SDKで利用できます。ツールはPythonなら @beta_tool デコレータ、TypeScriptなら betaZodTool() で定義します。関数の型ヒントやdocstringからJSONスキーマが導かれるため、スキーマの手書きと実装のズレを減らせます。

手動ループで起きがちな形式ミスも減ります。tool_result ブロックは対応する tool_use の直後に置き、ユーザーメッセージの先頭側に並べる必要があります。この規則を自前で守る手間が、ランナー経由では不要になります。

自前ループとTool Runnerはどう使い分けるのか

承認フロー・独自ログ・条件付き実行が要るなら手動ループ、それ以外はTool Runnerが公式の推奨です。迷えばランナーから始めます。

公式ドキュメントは、人間による承認、独自のログ、条件付きの実行が必要な場合に手動ループを使うよう案内しています。中小企業の実務では、次の基準が使えます。

状況選ぶ方式
読み取り系ツールだけの社内Q&ATool Runner
書き込みや送信の前に担当者の承認が要る手動ループ
呼び出しごとに監査ログを残す義務がある手動ループ、またはランナーのループ介入
まず試作して効果を測りたいTool Runner

承認が要る処理を後から足す場合も、全面的な書き直しは不要です。ランナーはループの途中で制御を引き取る手段を持っています。ただし引き取った反復では、ランナーはその回のアシスタントメッセージとツール結果を履歴に追加しません。履歴を有効な状態に保つ責任は、書き手に移ります。

max_iterationsは何回に設定すべきか

ループはツール呼び出しが無くなるまで回ります。上限を決めるのは自分で、max_iterations を指定しないと歯止めがありません。

ランナーは、Claudeがツール呼び出しを含まない応答を返すまで、または max_iterations に達するまでループします。上限は設定した場合にだけ効きます。公式の例では10が使われています。

目安は、業務で想定される最大のツール呼び出し回数に、再試行の余地を足した値です。たとえば「在庫照会、価格照会、在庫引当」で3回なら、上限は6〜10回程度が出発点になります。上限に達した事実は必ずログへ記録します。上限到達が日常的に起きるなら、ツール定義かプロンプトに問題があります。

ループを引き取る場合も、max_iterations の指定が公式に求められています。引き取った側がループの終了条件を壊すと、ランナーが自動で抜けられなくなるためです。

ツールが失敗したらどうなり、どう傍受するのか

ツールが例外を投げると、ランナーは is_error: true の結果としてClaudeへ返します。スタックトレースは含まれません。

ランナーは例外を捕捉し、例外のメッセージ(Pythonでは型とメッセージ)を is_error: true の tool_result としてClaudeに返します。Claudeはその内容を踏まえて、別の方法を試すか、利用者へ状況を説明します。

運用で押さえる点は3つあります。

  1. ログは言語で異なる。 Pythonは未処理の例外をスタックトレース付きで標準の logging に出します。Go、Ruby、C#、PHPのSDKは失敗したツールをログに出さないため、ツール関数の内部で自分で記録します。
  2. エラーを途中で止めたいなら傍受する。 Pythonでは generate_tool_call_response() で結果を取り出し、is_error を確認してから送れます。TypeScriptも同様の方法を持ちます。
  3. SDKによっては傍受できない。 C#は結果の事前確認用フックがなく、BetaToolError を投げてエラー内容を制御します。Goは傍受が未対応で、ハンドラー内で捕捉して結果を返します。

エラー文は具体的に書くと復旧しやすくなります。「失敗」だけでなく、公式の例のように「レート制限を超過。60秒後に再試行」と次の行動まで含めます。

長い作業ではコンテキストをどう扱うのか

長時間のタスクでは、サーバー側コンパクションを context_management で有効にします。クライアント側の自動圧縮は非推奨です。

TypeScriptとRubyのランナーには、トークン使用量が閾値を超えると要約する機能があります。ただし両SDKとも、この方式は非推奨で、全SDKのランナーで使えるサーバー側コンパクション(context_management パラメータ)が推奨されています。compact_before_next_turn() による任意のタイミングの圧縮も用意されていますが、これと context_management の圧縮設定は併用しないよう公式に記載があります。

参考

まとめ

Tool Runnerは、ツール実行ループの定型部分を任せられるベータ機能です。採用の判断は、書き込み前の承認や監査ログが要るかどうかで決まります。使うと決めたら、max_iterations を必ず指定し、言語ごとのログの差を確認し、エラーを止めるか返すかを先に決めます。

エージェントのループ設計やエラー処理の見直しは、Kuu株式会社のAI導入伴走サービスでご相談いただけます。

関連記事

Claude stop_reason別の分岐設計とループ制御Message threadsで長い会話の送信量を減らす設計エージェント失敗タスクの隔離設計——DLQと再処理Claude Codeサブエージェント設計——権限を絞る書き方