概要
トークン管理ポリシーを使用すると、大規模言語モデル（LLM）のトークン使用量をモニタリングして正確に割り当て、エンタープライズ AI エージェントとアプリケーション全体で共有トークン予算を適用できます。
AI エージェントが LLM とやり取りする場合、1 秒あたりのリクエスト数や 1 分あたりのリクエスト数などのリクエスト数レート制限では、費用や容量を制御できません。LLM への 1 つの HTTP リクエストで、12 個から 100,000 個を超えるトークンが消費されることがあります。トークンレベルのガバナンスがないと、1 つのエージェント ループが暴走して、共有エンタープライズ モデルの割り当てを使い果たし、予期しないコストの急増を引き起こす可能性があります。AI 費用を管理するには、組織全体のユーザーと部門にモデル割り当て予算を設定する必要もあります。
トークン管理ポリシーを使用すると、次のことができます。
- エージェントとモデルのすべてのインタラクションで、入力トークン、出力トークン、キャッシュに保存されたトークンのトークン使用量を計算します。
- Gemini Enterprise Agent Platform またはその他のモデル ホスティング プラットフォームでホストされているモデル全体で、トークンの消費量と推定費用を、ビジネスに関連するグループ、AI アプリケーション、個々の Agent Identity に割り振ります。
- 共有トークン予算をリアルタイムで適用し、トークンプールの予算が使い果たされると、しきい値アラートを送信するか、HTTP
429 Too Many Requestsを返します。 - 詳細なオブザーバビリティ テレメトリーを Cloud Monitoring にエクスポートし、Cloud Logging でトークン使用量のアラートを集計する。
仕組み
図 1 は、トークン管理ポリシーがゲートウェイ レイヤで LLM リクエストとレスポンスを評価する方法を示しています。
トークン管理では、3 つのポリシー リソースが連携して、トラフィックの分類、トークン予算の適用、費用計算のカスタマイズを行います。
- トークン集計ポリシー（
TokenAggregationPolicy）: 受信したエージェントからモデルへのリクエストを分類し、トークン消費量を論理的なトークン グループに集計します。グループ化は、リソース階層（プロジェクト スコープ）、AI アプリケーション、個々のエージェント、宛先モデル、HTTP リクエスト ヘッダーで渡されるカスタムタグ（API キーを含む）に基づいて行うことができます。 - トークン予算ポリシー（
TokenBudgetPolicy）: トークン集計ポリシーで識別される 1 つ以上のトークン グループにトークン割り当てを適用するトークンプールを定義します。各トークンプールには、最大トークン数、定期的なリセット ウィンドウ（1 時間ごとまたは 1 日ごと）、ターゲット モデルのオプション リスト、アラートしきい値、適用モードを指定します。 - トークンあたりの費用ポリシー（
CostPerTokenPolicy）: Monitoring でgcp.token_management.token.estimated_cost指標の計算に使用されるデフォルトのモデルごとのトークン料金をオーバーライドします。デフォルトのモデル価格に対する割引率、または入力トークン、出力トークン、キャッシュに保存されたトークンに対して米ドルでカスタムのトークンあたりの料金を構成できます。
ポリシーの依存関係と作成順序
トークン管理では、同じターゲット スコープに接続されているポリシー リソース間で、次の順序で厳格な依存関係階層が適用されます。
- ターゲット スコープのトークン グループにリクエストを分類するには、まず
TokenAggregationPolicyを作成する必要があります。このポリシーは、トークンの使用状況をエージェント レベルで詳細に可観測性を確保するための最小要件です。 - （省略可）
TokenAggregationPolicyで識別されたトークン グループに対するトークンの使用を制限するには、TokenBudgetPolicyを構成する必要があります。 - （省略可）
CostPerTokenPolicyは、ターゲット スコープに対応するTokenBudgetPolicyが存在する場合にのみ作成できます。
ポリシーを削除する場合は、逆の順序で削除します。最初に CostPerTokenPolicy、次に TokenBudgetPolicy、次に TokenAggregationPolicy の順に削除します。
ルールの評価とデフォルトのマッチング
TokenAggregationPolicy 内では、ルールはリストに表示されている順序で評価され、最初に一致したルールが適用されます。
- 一致したトラフィック: エージェント リクエストがルールの送信元条件（AI アプリケーションまたはエージェント ID）と宛先条件（HTTP ヘッダーまたはモデル プロバイダ エンドポイント）に一致すると、そのトークンの使用量がそのルールのトークン グループ（
tokenGroup）に割り当てられます。 - キャッチオール ルール: ルールリストの最後に空の一致ブロックを含むルールを配置して、残りのすべてのトラフィックをデフォルトのトークン グループ（
Defaultなど）に割り当てることができます。 - 一致しないトラフィック: キャッチオール ルールが含まれておらず、リクエストがポリシー内のどのルールにも一致しない場合、トークンの消費は Monitoring のシステム
unmatchedグループに記録されます。 - 未定義のプール トラフィック: トークン予算ポリシー（
TokenBudgetPolicy）のTokenPoolで、特定のモデルにのみ適用を制限している場合、そのリストに含まれないモデルへのリクエストはブロックされず、Monitoring でプール名がundefinedに設定されて記録されます。
サポートされている環境とモデル
トークン管理ポリシーは、次の Agent Runtime、Agent Gateway デプロイ、モデルをサポートしています。
| コンポーネント | サポートされるオプション |
|---|---|
| AI エージェント ランタイム |
|
| Agent Gateway のデプロイ | Cloud de Confiance by S3NS プロジェクトの Secure Web Proxy: すべてのエージェントからモデルへのリクエストに下り（外向き）トークン ガバナンスを適用します。 |
| モデル |
任意のモデル プロバイダの Gemini、Anthropic、OpenAI API 互換モデル:
|
| 集計グループ |
|
ポリシー違反に対する措置のフロー
標準のレート制限では、バックエンドに到達する前に、すべてのリクエストが 1 ユニットとしてカウントされます。LLM 呼び出しでは、入力トークンと出力トークンの合計数は、モデルが応答した後にのみわかります。これに対処するため、Agent Gateway は各リクエストを 2 つのフェーズで処理します。
- 掲載期間の予算の事前チェック（リクエストパス）:
- エージェントは、Agent Gateway を介して LLM エンドポイントに推論リクエストを送信します。
- ゲートウェイは、
TokenAggregationPolicyと照合してリクエストを評価し、一致するtokenGroupを特定して、TokenBudgetPolicy内の関連するTokenPoolを検索します。 - プールのトークン予算が使い果たされ、厳格な適用が有効になっている場合、ゲートウェイは HTTP
429ステータス コードでリクエストを直ちに拒否します。プールに予算が残っている場合、またはアラートのみモードに構成されている場合、ゲートウェイはリクエストを LLM に転送します。
- トークンの調整とテレメトリー（レスポンス パス）:
- LLM エンドポイントが完了レスポンスを返すと、ゲートウェイはレスポンス ペイロードから実際の
input、output、cachedトークン数を抽出します。 - トークン管理では、消費されたトークンがプールの
maxTokens割り当てと照合されます。 - 更新された使用量が警告しきい値を超えるか、予算の 100% に達すると、ゲートウェイは Logging に警告を書き込みます。
- ゲートウェイは、エージェントごとのトークン消費量（
gen_ai.client.token.usage）と推定トークン費用（gcp.token_management.token.estimated_cost）の指標を Monitoring にエクスポートします。
- LLM エンドポイントが完了レスポンスを返すと、ゲートウェイはレスポンス ペイロードから実際の
出力トークン数は、LLM レスポンスが完了した後にのみ記録されます。その結果、プールが maxTokens に達する前に許可された同時リクエストが上限を超え、後続のリクエストが HTTP 429 でブロックされる可能性があります。予期しないスロットリングを回避するには、0.6 や 0.8 などの alertThreshold を設定して、厳格な適用を有効にする前に validateOnly: true で新しいポリシーをテストします。
関連するガバナンス コントロール
次の表に、トークン管理ポリシーが他の Agent Platform と Cloud de Confiance ガバナンス管理とどのように連携するかを示します。
| ガバナンス レイヤ | ポリシーまたはメカニズム | 目的 |
|---|---|---|
| アクセス制御 | Identity and Access Management（IAM）アクセス ポリシー | 特定の MCP サーバー、ツール、モデル エンドポイントへの接続を許可するエージェント ID（SPIFFE ID）を制御します。 |
| インテントとビジネスルール | セマンティック ガバナンス ポリシー | 提案されたツール呼び出しを、実行前に自然言語制約（NLC）とユーザーの意図に照らして評価します。 |
| コンテンツの安全性 | Model Armor | プロンプトとレスポンスをスキャンして、プロンプト インジェクション、ジェイルブレイク、機密データを検出します。 |
| リクエスト数レート制限 | サービス レート制限（RateLimitPolicy） |
1 秒または 1 分あたりの HTTP リクエスト数（countLimit）を制限することで、大量のリクエスト フラッドから上り（内向き）ロードバランサとプロキシを保護します。 |
| LLM トークンと費用のガバナンス | トークン管理ポリシー（TokenAggregationPolicy、TokenBudgetPolicy、CostPerTokenPolicy） |
LLM トークンの使用状況をモニタリングしてアトリビューションを行い、エージェント グループとモデル プロバイダ間で共有トークン予算（maxTokens）と費用オーバーライドを適用します。 |
制限事項
トークン管理ポリシーには次の制限があります。
- 特定のプロジェクト ターゲット スコープに接続できる
TokenAggregationPolicy、TokenBudgetPolicy、CostPerTokenPolicyはそれぞれ 1 つだけです。 - 各
TokenAggregationPolicyは最大 10 個の集計ルール（rules）をサポートし、各TokenBudgetPolicyは最大 10 個のトークンプールをサポートします。 - トークンプールは
HOURLYとDAILYのリセット期間をサポートしています。1 日の予算は太平洋時間の午前 0 時にリセットされます。 - Logging は、トークンプールが構成済みの
alertThresholdを超えた場合、またはmaxTokens（token_management_alert_logs）の 100% に達した場合にのみログエントリを生成します。