AIエージェントのコンテキストコスト：繰り返すプロンプトとツール呼び出しの測定方法
マルチステップAIエージェントのコンテキストコストを測定・最適化する実践ガイド。ツールスキーマの分析、ベースライン測定、品質確認を扱います。
目次
Claude Code、Cline、Roo Code、独自のマルチステップパイプラインなどのAIエージェントを開発すると、コンテキストの蓄積とともにAPI利用量が増えることがあります。各リクエストの構成はクライアントに依存します。システムプロンプト、利用可能なツールスキーマ、メッセージ履歴、関数呼び出し結果が含まれる場合があります。
機能を失わずに予算を管理するには、固定したタスクでbaselineを取り、余分なトークンの主因を特定し、エージェント環境を一度に一変数だけ最適化します。
AIエージェントのコンテキスト構造：各ステップで何にトークンが使われるか
測定では、モデルに送るコンテキストを次の4つの観測可能な要素に分けます。
- システム指示とルール（System Prompt）： 基本的なスタイル要件、安全上の制約、リポジトリのコンテキスト。
- ツールスキーマ（Tool Schemas）： クライアントがリクエストに含める場合の、接続済み関数、パラメータ、データ型のJSON記述。
- メッセージ履歴（Message History）： タスクの進行に伴って蓄積する、以前のユーザーメッセージとエージェント応答。
- ツール出力（Tool Outputs）： 読んだファイルの内容、ターミナルコマンドのログ、APIダンプ。
最初のリクエストのサイズにステップ数を機械的に掛けないでください。各呼び出しのusageを出力します。履歴は増え、クライアントはデータを切り詰め、プロバイダーはcached tokensを別に計上することがあります。
コンテキストの発生源と最適化の比較表
| コンテキスト要素 | 測定するもの | 主な過剰支出リスク | 分離テストでの変更 |
|---|---|---|---|
| Tool Schemas | 実際に送信されたリストのサイズ | 共通セット内の未使用ツール | タスクに必要なtoolsだけ残す |
| Tool Outputs | 各結果のサイズ | 対象を絞った抜粋ではなくファイル全体を読む | 行範囲とログ量を制限する |
| ステップ履歴 | 呼び出しごとのinput増加 | 不要になった結果が蓄積する | クライアントが対応する履歴短縮を確認する |
| System Prompt | プレフィックスのサイズと安定性 | 指示の重複 | 必須ルールを保ったまま重複を削除する |
手順：baselineを測定して支出を減らす方法
まず現在のモデル料金を記録します。 baselineの計算には古い例の値ではなく、現在のBetterToken料金を使います。BetterTokenの現在の料金を見る
客観的に最適化するため、単一変数の測定方法を使います。
ステップ1. テスト用の制御タスクを固定する
再現可能なエンジニアリングシナリオを選びます。例は「リポジトリ内の検証関数を見つけ、エッジケースの処理を追加し、unit testを実行する」です。タスクには、pytest または bun test の終了コード0のような明確な完了基準が必要です。
ステップ2. Baselineを測定する（Input、Output、Cache）
標準のエージェント設定でタスクを実行し、ログまたは監視パネルに次を記録します。
- 実行したステップ数
- input tokensの合計
- output tokensの合計
- キャッシュされたトークン量（
cached tokens） - 現在の料金による金額
選択したモデルの現在の料金はBetterToken料金ページで確認します。Workspaceでは、受理されたリクエストについて、モデル、時刻、ステータス、input/output tokens、モデルが対応する場合のcached tokens、呼び出しのコストを確認できます。1つのエージェントステップが複数のリクエストを作る場合、リクエスト単位の記録を完成したステップ別内訳として扱わず、時刻と自分のクライアントのデータで対応付けます。
ステップ3. コンテキスト変数を1つ変更する
反復ごとに厳密に1つのパラメータだけを変えて、分離したテストを実行します。
- 実験A（Tool Filtering）： 制御タスクに必要なツールだけを残し、input tokensの差を測定します。
- 実験B（Output Truncation）： 2,000行すべてのダンプではなく、エラーの先頭50行にターミナル出力を制限します。
- 実験C（Prefix Stability）： モデルとendpointがprompt cachingをサポートする場合、システムプロンプトとツールスキーマの順序を変えず、実際のcached tokensデータを確認します。
ステップ4. 経済性と解決品質を評価する
最終的な指標を元のbaselineと比較します。制御タスクが同じ品質基準を引き続き満たし、測定した時間または支出が自分の実行セットで改善した場合にだけ、変更を採用します。
エージェント環境を設定するための推奨事項
- 役割ごとにツールセットを絞る： 読むだけのエージェントに書き込み機能は不要です。結果を損なわず実際のinputを減らせるか確認します。
- 安定したプレフィックスを維持する： cachingがサポートされる場合、共通ルールの順序を不要に変えず、割引を仮定する代わりにcached tokensを確認します。
- ループを制限する： 具体的なタスクに合う、有限の試行回数と明示的な停止条件を設定します。
境界ケースとよくある誤り
- 誤り：重要な検証スキーマを無効にすること。 ツールスキーマの説明を削りすぎると、モデルが無効なJSONを送り、繰り返しリクエストの連鎖を招くことがあります。
- 誤り：SNS上の節約の主張をうのみにすること。 コンテキスト最適化の効果は、リポジトリ構造と平均ファイルサイズに依存します。
- 誤り：透明なテレメトリーがないこと。 endpointがinput/cache tokensを分けた統計を返さない場合、仮定からキャッシュ利用を見積もらず、値をunknownとして記録します。
