Message Batches APIの設計制約——ツールループが壊れる理由と適切な使いどころ【CCA Foundations対策】

Anthropic Academyの「Claude Code in Action」コースをもとに解説しています。

Message Batches APIはAPIコストを50%削減できる。しかし処理に最大24時間かかる場合があり、ポーリングが必要になる。この制約は「遅延の問題」として理解されがちだが、本質はアーキテクチャ上の制約だ。

この記事でわかること：

Message Batches APIの「fire-and-forget」モデルとは何か
ツール呼び出しループがBatch APIと根本的に非互換な理由
「遅延が許容できれば使える」という誤解を解く
適切なユースケースと判断基準

Batch APIの仕組み：fire-and-forget

通常の同期APIでは、リクエストを送ると処理が完了するまでコネクションが維持され、結果が返ってくる。

Batch APIは異なる。リクエストをまとめて投げると「バッチを受け付けた」という確認だけが返り、処理はバックグラウンドで非同期に進む。結果はポーリングで取りに行く。

同期API:  [リクエスト] → [Claude処理] → [結果] （同一コネクション）

Batch:    [リクエスト群] → [受付確認]
                              ↓ バックグラウンド処理
           ... 数分〜24時間後 ...
          [ポーリング] → [完了確認] → [結果取得]

このfire-and-forgetの構造が、特定のワークフローとの非互換を生む。

ツール呼び出しループが壊れる理由

ツールを使うワークフローを考える。Claudeはファイルを分析し、足りない情報があれば関連ファイルを追加で読み込み、ツール結果を受け取って分析を続ける。

[Claude分析] → [ツール呼び出し: get_file("imports.ts")]
                    ↓
             [ツール実行してファイル内容を返す]
                    ↓
             [Claude: 内容を受け取って分析を継続]
                    ↓
             [ツール呼び出し: get_file("base-class.ts")]
                    ↓
             ...繰り返し...
                    ↓
             [最終的な分析結果]

このループの核心は「ツール結果を受け取ったClaudeが次のステップを決める」点にある。ツール実行とClaudeの推論が交互に行われる。

Batch APIにはこのループを支える仕組みがない。バッチリクエストを送った後、処理の途中でツールを実行して結果を返すエンドポイントが存在しない。「ツールを呼び出したいのでツール実行して結果を返してください」という中間のやりとりを挟む設計になっていないのだ。

つまり問題は遅延ではなく、ミッドリクエストでのツール実行というアーキテクチャそのものが非対応ということだ。

「処理が遅くてもいいならBatch APIでツールループが動く」——これは誤り。24時間待っても動かない。ループ自体が成立しない。

「遅延の問題」と「アーキテクチャの問題」を区別する

よくある混同パターンとして：

pre-mergeフック（PRのマージをブロックする）でツール呼び出しを使う
ツールで関連ファイルを動的に読み込んで分析を続けるワークフロー

前者は「ブロッキング」なのでBatch APIが使えない（遅延の問題）。後者は「ツールループ」なのでBatch APIが使えない（アーキテクチャの問題）。両方を「遅延が問題」と混同すると、「遅延を許容できれば後者は使える」という誤った結論になる。

適切なユースケース

Batch APIが機能するのは「1回のリクエスト・1回のレスポンス」で完結するタスクだ。

ユースケース	Batch API	理由
夜間の技術的負債レポート生成	✅ 適切	latency許容・ポーリング設計済み
週次セキュリティ監査	✅ 適切	スケジュール実行・翌日参照でよい
テストケースの一括生成	✅ 適切	ツールループ不要・バッチで処理可能
pre-mergeブロッキングチェック	❌ 不適切	開発者が待機中・遅延許容不可
動的なファイル読み込みを伴うレビュー	❌ 不適切	ツールループが必要
リアルタイムユーザーサポート	❌ 不適切	即時応答が必要

判断のポイントを2つに絞ると：

処理結果を誰かがブロックして待っているか　→ 待っていればBatch不可（遅延の問題）
Claude処理の途中でツール実行が必要か　→ 必要ならBatch不可（アーキテクチャの問題）

どちらもNoならBatch APIのコスト削減が活かせる。

まとめ

Message Batches APIはfire-and-forgetモデル。ミッドリクエストでのツール実行をサポートしない
ツール呼び出しループとBatch APIは「遅延の問題」ではなく「アーキテクチャ上の非互換」
適切なユースケース：latency-tolerant・ポーリング対応済み・ツールループ不要のバッチ処理
判断軸：「誰かが待っているか」＋「途中でツール実行が必要か」の2点で判断する

次の記事（claude-api-17）はエージェントの信頼性設計——プログラム的前提条件とfew-shotツール選択——を解説する。