apigee-agent-gateway-governance

エージェントゲートウェイサービス拡張としての Apigee

GCP エージェントゲートウェイ上で、Apigee プロキシを ext-proc コールアウト として接続します。このプロキシは API プロキシではなくプロセッサー です。バックエンドを持たず、ゲートウェイから渡された LLM リクエストとレスポンスを検査し、判定を返します。

プロキシを構築するのはあなたです。ユーザーではありません。

2 つのモードで 1 つのスキーマを使用します。何よりも先にどちらかを判断し、明示してください。 入力ファイルがある場合 → 本番モード：そのファイルが契約であり、すべての値はそこから取得します。フィールドの欠落や形式不正は、デフォルト値を使わず拒否します。入力ファイルがなく、ユーザーが実現したい結果を説明している場合 → 開発モード：文書化されたデフォルト値を適用し、所要時間を含む計画を提示して承認を得て、最初は ID と計測のみを設定し、最後に引き継ぎ用として apigee-agent-gateway-governance.yaml を書き出します。assets/apigee-agent-gateway-governance.example.yaml には、両モードで使用するスキーマが記載されています。

モード、デフォルト値、所要時間、コストの開示、および両モードを拘束するインターロックについては、references/modes.md を参照してください。開始前に必ず読んでください。

計画の ACTION 列に色を付けてください — 緑は REUSE、シアンは CREATE／RESERVE、黄色は APPEND／MODIFY です。すべての色については references/modes.md を参照してください。黄色は、その存在意義が最も明確な色です。ユーザーがすでに所有しているリソースが変更されることを示す唯一の合図だからです。プレーンテキストで表示すると、何かを変更する 1 行は、変更しない 12 行と見分けがつきません。そして、その 1 行こそが承認を得る理由です。

前提条件：エージェントの実行場所

何かを構築する前に確認してください。これによって、トラフィックがゲートウェイに到達できるかどうかが決まります。誤っていても表面化しないため、何も届いていないのに以下のすべての手順は成功してしまいます。

agent_gateway_config／agent_to_anywhere_config で作成する Agent Runtime を使用してください。 これがサポートされている方法であり、オーケストレーターがクライアント側の PSC、ルーティング、DNS、証明書の信頼設定を構築します。これには gcloud の操作手段もコンソール経由の手段もなく、エージェント作成時に SDK からのみ設定できます。バインディングについては Route traffic through Agent Gateway を、実例については references/networking-psc.md を参照してください。

エージェントの env_vars に GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES: "False" を設定してください。設定しないと、ユーザーコードの実行前にエージェント自身の sessions.create がすべて 401 エラーになります。 デプロイ時には検出できません。症状の全容と切り分けについては、references/gotchas.md の Agent Gateway を参照してください。

エージェントの実行場所については、これで前提が整います。ここでは、ゲートウェイとエージェントが正常に動作していることを前提とします。エージェントの構築方法を説明したり、求められていない非対応のコンピューティング環境を列挙したりしないでください。必要になった場合は、references/networking-psc.md に制約が記載されています。

ツールのバージョン

インストール済みであることや、最新であることを前提にしないでください。

ツール	最小バージョン	理由
gcloud	588.0.0	apigee apis import --from-template はこのバージョンで GA トラックに含まれます。それ以前の SDK では gcloud beta が必要です
google-cloud-aiplatform[agent_engines,adk]	>=2.1,<3	エージェントをゲートウェイにバインドする Agent Runtime クライアント
google-adk	>=2.9,<3	ADK でテスト用エージェントを構築する場合のみ必要

gcloud >= 588.0.0 では、すべてのフィーチャーに uid を設定し、テンプレートでは endpoints も targets も宣言しないでください。 現在、6 つすべてのフィーチャーに uid が設定されており、テンプレートではどちらも宣言されていないため、同梱されているバンドルは正しい状態です。ただし、どちらも現在は不可欠です。いずれかを壊してもコンパイルとデプロイは成功し、エラーも報告されません。仕組みと症状については、references/gotchas.md の Authoring (AFT) を参照してください。

gcloud version | head -1          # confirm >= 588.0.0
gcloud components update          # if older
pip install "google-cloud-aiplatform[agent_engines,adk]>=2.1,<3" "google-adk>=2.9,<3"

scripts/compile_check.py には PyYAML が必要です。見つからない場合は、必要なインタープリターを表示します。pip install pyyaml を実行するか、PyYAML がインストールされた Python 3 で実行してください。gcloud に同梱されているインタープリターには PyYAML がなく、SDK にベンダーとして含まれる yaml は Python 2 用です。

python3 scripts/compile_check.py assets/apigee-proxy-template.yaml

実行モデル

3 つのレイヤーがあり、どれを選ぶかは単なるスタイルの問題ではありません。

レイヤー	用途	理由
AFT YAML テンプレート	プロキシ自体	バージョン管理でき、レビュー可能で、差分を確認できる
gcloud	PSC、DNS、AuthzExtension、AuthzPolicy	ネイティブコマンドが用意されている
REST（curl）	env properties、envgroups、deployments、debug sessions	現時点では gcloud に相当するものがない

お客様が所有する入力ファイルは 1 つだけです （assets/apigee-agent-gateway-governance.example.yaml）。これがバージョン管理対象の成果物です。生成されたプロキシを手動で編集しないでください。再生成してください。

Apigee 側の一連の手順は、手作業ではなくスクリプトで実行してください。 以下のステップ 1、3、4 は順序に依存し、それぞれ異なる問題に見える形で失敗します。scripts/deploy_proxy.sh は 3 つすべてを実行し、properties マップを保持し、非同期オペレーションをポーリングします。また、デプロイが EXTENSIBLE として起動しない場合は、ゼロ以外の終了コードで終了します。

scripts/deploy_proxy.sh --org "$ORG" --env "$ENV" --proxy "$PROXY" \
  --template assets/apigee-proxy-template.yaml [--service-account "$SA"] --yes \
  [--index-endpoint-id ID --index-id ID --sc-project P --sc-region R --embeddings-model M]

まずは --yes を付けずに実行してください。計画が表示され、何も変更されません。その計画を提示し、ユーザーの同意を得てから --yes を付けて再実行してください。

ベクトル検索のフラグは、「宣言している各機能でデフォルト値を編集する」というルールの唯一の例外です。 この 3 つの ID はデプロイ時に置換され、未置換のものがないか確認されます。これらを feature-semantic-cache.yaml に手動で編集してもデプロイ自体は成功しますが、確認処理が省略され、ファイルが一度しか使えなくなります。

scripts/ensure_gateway_connectivity.sh も同じ考え方でゲートウェイ側の処理（ステップ 0）を行います。このスキルの中で、ユーザーがすでに所有しているリソースを変更するのはこの処理だけなので、--yes を付けない限り何も適用しません。

以下に手順を記載しているのは、失敗の原因を診断できるようにするためであり、手順を見ながら再入力するためではありません。

最初に解決する必要がある入力

環境の前提条件：references/setup.md — gcloud SDK（588 以降）、 プロジェクト、課金、gcloud services enable、リージョン、認証情報、IAM。以下の手順でこれらが作成されることはありません。

本番環境：入力ファイル、次に環境から取得し、それでも不明なら質問してください。決して推測しないでください。開発環境：references/modes.md のデフォルトを適用し、デフォルトがない項目だけ質問してください。

• project、region
• apigee.org、apigee.environment、apigee.envgroup、apigee.hostname、 apigee.proxy
• network.vpc、network.subnet、network.networkAttachment
• gateway.name、gateway.matchPaths（リスト。ワイヤー形式ごとに1エントリー）、 gateway.manageNetworkConfig

matchPaths は2つのアーティファクトを決定します。両方を同じリストから作成してください。 AuthzPolicy の paths[].suffix には、各エントリーにつき1つのサフィックスをそのまま設定し、先頭の記号も保持します。これはゲートウェイが Apigee にルーティングする対象を決定します。テンプレートの LLM_URI_MATCH には、エントリーごとに (request.uri Like "*<entry>*") 句を1つ設定して OR でつなぎ、先頭の : または / は取り除きます。これは Apigee に到達した後、プロキシが処理する対象を決定します。出荷時の2エントリーのデフォルトは次のとおりです。

((request.uri Like "*generateContent*") or (request.uri Like "*chat/completions*"))

AuthzPolicy は外側のゲートであり、優先されます。サフィックスのリストが matchPaths より狭いと、対象から漏れた形式は Apigee にまったく到達しません。両方とも入力ファイルから導出し、ファイルの内容がデフォルトと異なる場合にデフォルトを使ってはいけません。ファイルはレビュー可能な契約であり、デプロイ後に不一致を見つけることはできません。

エントリーが1つだけのリストも有効であり、1つの形式を対象とします。エントリーを削除すると、対象が1つ減ることが気づかれないまま適用されます。デプロイは正常に完了しますが、削除された形式のトランザクションはゼロになり、feature-normalize、Model Armor、キャッシュの対象も同時に狭まります。ランタイムについては references/gotchas.md を参照してください。

semanticCache が有効な場合は常に既知の問題です。警告してから構築してください。 キーはプロンプトの埋め込みのみであり、呼び出し元、モデル、形式は含まれません。そのため、キャッシュヒットは呼び出し元をまたぎます。類似するプロンプトは同じ回答を共有し、1つの形式の背後にモデルが1つだけあっても安全にはなりません。形式が複数あると、最初に回答したモデルの回答がほかの形式にも使われます。その結果、形式をまたいで空の HTTP 200 が返されたり、1つの形式内で誤ったモデルの本文が返されたりします。キャッシュが有効な場合は、複数形式かどうかにかかわらず警告してから構築してください。警告の文言については references/modes.md、仕組みについては references/gotchas.md を参照してください。

各エントリーはサフィックスマッチです。 これらはユーザーではなく、あなたが設定します。エージェントが実際に呼び出すエンドポイントから導出してください。ユーザーにサフィックスについて判断させないでください。Vertex の OpenAI 互換エンドポイントと api.openai.com には異なるエントリーが必要です。設定を誤ると、何も対象にならないまま気づかれません。形式と根拠については、ランタイムの references/gotchas.md を参照してください。

apiShape フィールドはありません。 計測はワイヤー形式に依存しません。カウントは JS で両方の形式に対応して正規化されるため、このフィールドでは何も選択できず、削除されました。形式を追加するには、extract-model.js に || 分岐を追加し、matchPaths にエントリーを追加します。

コールアウトのホスト名を保持する箇所は3つあり、すべて一致させる必要があります — Apigee envgroup、AuthzExtension の authority/service、プライベート DNS A レコードです。1つの値から3か所すべてを設定します。これは維持すべきビルド時の不変条件であり、ユーザーに尋ねる項目ではありません。問題になるのはコールアウトが一度も到達しない場合だけで、その際に最初に確認すべき項目です。これに加えて、ビルドの順序も重要です。ホストが名前解決でき、プロキシがデプロイされるまでは AuthzExtension は機能しないため、「拡張機能が存在する」ことは、その処理経路が動作する証拠にはなりません。ランタイムについては references/gotchas.md を参照してください。

ワークフロー

0. ゲートウェイ：VPC への経路を設定する

networkConfig がないゲートウェイには、顧客の VPC への経路がなく、コールアウトのホスト名を解決できません。このスキルで設定します — ネットワーク接続、エグレス、DNS ピアリングを設定するため、これは障害ではなくビルド手順であり、そのように報告してください。これから作成するリソースについて、警告から始めないでください。

ここでユーザーに確認が必要なことが一つあります。これが、これを前提条件として黙って済ませず、ステップ 0 とする理由です。エグレスの接続は一方向であり、すでに実行中のトラフィックに影響します。何かを実行する前に、計画の段階で確認してください — 下記の「すべてを事前に確認する」を参照してください。本番ゲートウェイに不安がある場合は、まず正常に動作したエージェントのターンを記録しておくと、「最初から動いていなかった」のか「こちらが壊した」のかを切り分けられるので有用です。これは提案する予防策であり、必須の手順ではありません。

gcloud network-services agent-gateways describe "$GATEWAY" \
  --location="$REGION" --project="$PROJECT" --format='value(networkConfig)'
gcloud network-security authz-policies list \
  --location="$REGION" --project="$PROJECT"

コンソールで作成されたゲートウェイには、すでに CUSTOM AuthzPolicy があります — IAP の REQUEST_AUTHZ ポリシーで、こちらのポリシーと共存し、エグレス JWT には不要です。ゲートウェイを作成することはないため、決めつけずに状態を確認してください。references/gotchas.md の Agent Gateway を参照してください。

networkConfig の出力が空の場合は未設定です。見落としやすい点に注意してください。通常のエージェントトラフィックは引き続き問題なく処理されます。その通信経路はパブリックな Google エンドポイントに向かい、VPC には入りません。失敗するのは Apigee のコールアウトだけです。

未設定の場合の動作は、gateway.manageNetworkConfig によって異なります。

• true — 下記のスクリプトを実行してください。ネットワーク接続を作成してから、ゲートウェイを読み取り・変更・書き込みし、エグレス接続と DNS ピアリングを追加します。これへの同意はここではなく、計画の段階で得てください。--yes によってその同意が引き継がれます。
• false — ユーザーは自分でこの変更を行うことを希望しています。スクリプトの実行コマンドを表示し、実行してもらってください。ゲートウェイを変更してはいけません。

scripts/ensure_gateway_connectivity.sh \
  --gateway "$GATEWAY" --project "$PROJECT" --region "$REGION" \
  --vpc "$VPC" --subnet "$SUBNET" --attachment "$ATTACHMENT" \
  --domain "$DNS_DOMAIN"            # add --yes only after the user agrees

どちらの場合も、Apigee の作業を始める前に networkConfig が存在している必要があります。未設定がエラーだからではなく、設定がなければ、その後の手順が成功しても何も制御できないためです。

生のコマンドではなく、スクリプトを使ってください。import はリソース全体をアップサートするため、手作業で作成した YAML ではゲートウェイの registries と protocols が気づかないうちに削除されます。その理由と、etag および PROTOCOL_UNSPECIFIED の処理については、references/gotchas.md を参照してください。

1. Apigee：環境を有効にする

環境には apigee-service-extension-enabled=true が設定されている必要があります。これを指定する gcloud フラグはありません。PATCH でプロパティマップを更新してください。

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV"

PATCH はマップ全体を置き換えます。 まず現在のマップを読み取り、保持するすべてのプロパティを再送してください。そうしないと、それらが気づかないうちに削除されます。

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV?updateMask=properties" \
  -d '{"properties":{"property":[{"name":"apigee-service-extension-enabled","value":"true"}]}}'

これによって Apigee Analytics が無効になることはありません。両者は共存します。アナリティクスが見当たらない場合は、環境ごとに別途追加するアドオンの問題です。references/gotchas.md を参照してください。

専用の環境を使用し、環境グループは必ず1つだけにしてください。 環境が2つの環境グループに所属すると、拡張機能が一度も呼び出されないまま、ゲートウェイはすべてのリクエストに対して 404 を返します。また、プロキシが使用する / のベースパスを空けておくこともできます。

scripts/ensure_apigee_environment.sh は環境を作成し、リージョンランタイムインスタンスに接続して、環境グループを作成・接続します。したがって、このスクリプトが成功すればステップ 2 も完了しています。課金対象のリソースを作成するため、--yes を指定しない限り何も適用しません。この同意はここではなく、計画の段階で得てください。

scripts/ensure_apigee_environment.sh \
  --org "$ORG" --env "$ENV" --region "$REGION" \
  --envgroup "$ENVGROUP" --hostname "$HOSTNAME"      # add --yes to apply

このスクリプトは冪等で、再開可能です。環境がすでに別の環境グループに所属している場合、または環境グループが別のホスト名で存在する場合は、終了コード 2 で処理を拒否します。また、手順書で見落とされがちな次の3点にも対応しています。作成時に省略されている type、環境をロックする4分間のインスタンス接続、そして早すぎる段階で成功する GET ではなく、オペレーションをポーリングすることです。

2. Apigee：呼び出しホスト名の envgroup

ステップ 1 のスクリプトを実行済みであれば、完了しています。既存の envgroup について確認するか、手動で設定してください。ホスト名は呼び出しホストと完全に一致し、グループは環境に関連付けられている必要があります。

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG/envgroups/$ENVGROUP/attachments"

環境はいくつの envgroup に属していますか？ 2 つ以上あると、呼び出しは到達しません。deploy_proxy.sh は何かに触れる前にこれを検証し、該当する envgroup 名を表示して終了コード 2 で終了します。assess_integration.sh もこの問題を報告します。エラーが発生した場合は、表示された内容をそのまま受け取ってください。問題は環境にあり、スクリプトにはありません。

3. テンプレートからプロキシをビルドする

gcloud apigee apis import organizations/$ORG/apis/$PROXY \
  --from-template=assets/apigee-proxy-template.yaml

各 features: エントリは、作業ディレクトリではなく、テンプレートファイル自体が置かれているディレクトリを基準に解決されます。そのため、ファイル名だけを指定する場合はテンプレートと同じディレクトリに置く必要があります（features/feature-identity.yaml のようなサブパスも使用できます）。assets/ がフラットなのは慣例であり、コンパイラーの要件ではありません。ただし、features: を更新せずにファイルを移動すると、インポート時に FileNotFoundError がそのまま発生します。

アクセス権があることを確認済みの組織で Permission denied on resource ... (or it may not exist) が表示される場合、原因はアクセス権ではなく認証情報です。コンテキスト対応アクセスが有効な場合、デフォルトの gcloud 認証情報は拒否されます。代わりに ADC トークンを渡してください。

CLOUDSDK_AUTH_ACCESS_TOKEN=$(gcloud auth application-default print-access-token) \
  gcloud apigee apis import ...

パラメーターを変更するには、テンプレートではなく、そのパラメーターを宣言しているすべての FEATURE の default を編集してください。gcloud apigee apis import は呼び出し元のパラメーターマップを空の状態で渡すため、各機能はそれぞれのデフォルト値を解決し、同じ名前のテンプレート側の宣言は読み込まれません。テンプレートを編集しても何も変わらず、エラーも出ません。コンパイルは引き続き成功します。実際に、テンプレート内の MA_CONTINUE_ON_ERROR を DRY_RUN に設定したところ、フェイルクローズのポリシーでは ENFORCE が適用されました。LLM_URI_MATCH は 4 つの機能で宣言されているため、4 つすべての値を一致させる必要があります。scripts/compile_check.py は不一致があると失敗します。--parameters フラグはありません。

オプションのレシピを有効にするには、その機能をテンプレートの features リストに追加します。references/recipes.md を参照してください。

入力ファイルの tokenMetering.models は生成に使われるものではありません。 どのバケットが存在するかを記述するものであり、バケットを作成するものではありません。バケットが実際に機能するのは、feature-token-metering.yaml に LLMTokenQuota ステップがあり、それに対応する *_TOKEN_LIMIT パラメーターが存在する場合だけです。バケットは gemini-pro、gemini-flash、other の 3 つです。other は、名前に pro も flash も含まないすべてのモデルを対象とするフォールバックです。リストに 4 つ目のエントリを追加しても、トークン計測は行われません。また、other を省略すると、Gemini 以外のすべてのモデルが、通知なしにトークン計測の対象外になります。カウントは抽出されたあと破棄され、トランザクション内のどこにも ratelimit の参照がありません。モデルを追加するには、設定ではなく機能ファイルを編集してください。

4. デプロイする

サービス拡張環境にデプロイし、デプロイ結果に proxyDeploymentType: EXTENSIBLE と表示されることを確認してください。

curl -s -H "Authorization: Bearer $TOKEN" \
  ".../environments/$ENV/deployments"

STANDARD の場合、エージェントから Apigee の外部にあるツールへの送信通信は制御されません。

いずれかのポリシーが Google API（Model Armor、埋め込み、Vector Search など）を呼び出す場合は、サービスアカウントを指定してデプロイしてください。指定しないと、MISSING_SERVICE_ACCOUNT でデプロイが拒否されます。

curl -X POST -H "Authorization: Bearer $TOKEN" \
  ".../apis/$PROXY/revisions/$REV/deployments?override=true&serviceAccount=$DEPLOY_SA"

5. ネットワーク

ここで扱うのは、ゲートウェイ → Apigee の経路だけです。Apigee インスタンスのサービスアタッチメントへの PSC エンドポイントと、プライベート DNS A レコードが必要です。references/networking-psc.md を参照してください。接続が ACCEPTED に到達するには、Apigee インスタンスの consumerAcceptList にプロジェクトが含まれている必要があります。

エージェント → ゲートウェイ の経路は上記の前提条件であり、ここでは構築しません。

6. ゲートウェイをバインドする

AuthzExtension の次に AuthzPolicy を、この順序で設定します。ホストの解決とプロキシのデプロイが完了してから、一度だけ行ってください。それまでは、この拡張機能は無効です。

両方のドキュメント本文はアセットとして用意されています。コピーして値を置き換えてください。内容を独自に作成しないでください — assets/authz-extension.example.yaml と assets/authz-policy.example.yaml です。 これらには、重要なフィールドであり、明白なデフォルト値がない項目が含まれています。 wireFormat: EXT_PROC_GRPC、failOpen、authority／service のペア、 metadata の本文フラグ、そしてポリシーの customProvider／httpRules のネスト構造です。

gcloud service-extensions authz-extensions import $AUTHZ_EXT \
  --source=authz-extension.yaml --location=$REGION --project=$PROJECT
gcloud beta network-security authz-policies import $AUTHZ_POLICY \
  --source=authz-policy.yaml --location=$REGION --project=$PROJECT

ポリシーのリソースパスに使うのは、ID ではなくプロジェクト番号です — target.resources と customProvider.authzExtension.resources の両方が対象です。番号は自分で解決してください。ユーザーに2つの番号を説明しても役に立ちません。呼び出しが届かない場合に備えた注意点です。ゲートウェイの serviceExtensionsServiceAccount にある番号は Google 管理のテナントプロジェクトのもので、相手のものではありません。画面に表示される番号はそれだけなので、そのままコピーするのが自然です。間違った番号でもインポートは正常に完了し、対象は何もありません。assets/authz-policy.example.yaml の値をコピーしてください。

7. 検証する

curl ではテストできません — ホストは内部向けであり、プロキシはゲートウェイの IAP エグレス JWT を要求します。scripts/read_debug_session.sh --arm を実行してターンを進め、--session で読み戻してください。このように範囲を絞ったサフィックスリストでは、制御対象の各形状につき、1ターンあたり1つのトランザクションが想定されます。ゼロだからといって、呼び出しが停止しているとは限りません — スクリプトが判定に必要なプローブを表示します。

厳守事項

各ステップにゲートを設けてください — どれほど厳格にするかは AuthzPolicy によります。 ゲートのない continueOnError="false" ポリシーは、プロンプトを持たない呼び出しで障害を起こし、エージェントのターンを中断します。これは、これまで最もよく見られた失敗です。

サフィックスリストを絞れば、Apigee にルーティングされるのはモデル呼び出しだけなので、この問題はほとんど起きません。ポリシーの範囲を広げると、たちまち発生します。ext-proc がすべてのエージェントのエグレス、つまりセッションの作成／読み取り、appendEvent、OpenTelemetry のエクスポートを参照することになります。単一の質問のターンで合計12回の呼び出しが計測され、そのうちモデル呼び出しは1回でした。どの場合もステップにゲートを設けてください。条件の追加コストはわずかで、後からポリシーの範囲を安全に広げられるようになります。計測の全容については、references/gotchas.md を参照してください。

• モデル呼び出し：(request.uri Like "*generateContent*")

独自のメータリングで、決してフェイルクローズにしないでください。 メータリングの不具合で LLM のトラフィックが中断されないよう、JavaScript ポリシーとクォータポリシーでは continueOnError="true" を維持してください。

このスキルはデフォルトでメータリングを行い、要求に応じて強制できます。 強制には assets/feature-token-enforce.yaml を使用します。これは、レスポンスフローの CountOnly 側と SharedName を共有する、リクエストフローの EnforceOnly ポリシーです。テンプレートの機能リストに追加してください。ext-proc トラフィックでのライブ検証済みです。予算超過の呼び出し元には 429 が返され、モデルは呼び出されません。

代替策として CountOnly=false を提案してはいけません。レスポンスフローではゲートとして機能できず（回答はすでに送信済みです）、カウンターが停止してメータリングも失われます。

提案する際は、必ず2点を伝えてください。リクエストより1回遅れて適用されます — トークンコストが分かるのはモデルの回答後なので、上限を超えたターンは完了します。また、リクエストされたモデルでバケット分けされます。OpenAI のエイリアスを使う場合、これは計測側で課金対象となる解決済みモデルと異なることがあります。「拒否されない」という同じ症状につながる2つの落とし穴については、references/gotchas.md を参照してください。

モデルをバケットに正規化してください。 OpenAI 互換エンドポイントでは、モデルはリクエスト本文内のエイリアスであり、解決済みの名前はレスポンス本文にあります（google/gemini-2.5-pro）。レスポンスパスで名前をそのまま完全一致させても失敗します。

jsonPath には、スカラーを返すための第3引数 true が必要です。 これがないと、クォータポリシーは解析できないノードを受け取ります。

参考資料

• references/modes.md — 最初に読んでください。「何ができますか」という質問への回答、開発環境と本番環境、デフォルト設定、所要時間、コストの開示、インターロック、評価レポートの読み方

• scripts/assess_integration.sh — **読み取り専用です。**セットアップ状況の概要に続いてチェックごとの表を表示します。--json には両方が含まれます。最初に概要を示し、Enforcement の行を読み上げてください。計画を立てる前に実行してください。CREATE と REUSE のどちらにするかを判断します。TODO はビルド手順であり、失敗ではありません。終了コードが 0 以外になるのは FAIL の場合のみです

• references/networking-psc.md — 2 つのネットワーク経路、PSC、DNS、受け入れ条件

• references/recipes.md — Model Armor とセマンティックキャッシュ

• references/verify.md — デバッグセッションとチェックリストスクリプト

• references/setup.md — SDK、プロジェクト、課金、API、リージョン、認証、IAM

• references/gotchas.md — 63 の失敗パターンとその症状

• assets/apigee-agent-gateway-governance.example.yaml — 入力コントラクト

• assets/apigee-proxy-template.yaml — AFT テンプレート。機能は priority によってマージされ、すべてその隣に配置されます：feature-identity.yaml（10）、feature-normalize.yaml（15）、feature-model-armor.yaml（20）、feature-semantic-cache.yaml（30）、feature-token-metering.yaml（50）。

• assets/authz-extension.example.yaml、assets/authz-policy.example.yaml — ステップ 6 の本文です。コピーして値を置き換えてください。パスにはプロジェクトの番号を使用します

  リクエストボディから読み取る内容は、最初に必要とする機能の内部ではなく、優先度 15 で一度だけ正規化されます。 LLM_URI_MATCH は共有されているため、これを広げると、これに依存するすべての機能が同時に有効になります。フェイルクローズ動作をする Model Armor も含まれます。Model Armor とキャッシュはどちらも agw.user_prompt を読み取ります。同じ理由で、クォータはメータリング機能独自の JS によってレスポンス経路で設定される agw.total_tokens を読み取ります。

• scripts/ensure_apigee_environment.sh — 環境を作成し、インスタンスに接続して、環境グループを作成・接続します。冪等で、--yes が必要です

• scripts/ensure_gateway_connectivity.sh — ゲートウェイから VPC へのルートを設定します。読み取り・変更・書き込みを行い、--yes が必要です

• scripts/ensure_vector_search.sh — semanticCache が有効な場合のみ実行します。インデックスとエンドポイントを構築し、一方にもう一方をデプロイして、ドメインを読み戻します。--yes が必要です。約 34 分かかり、継続的に課金されます

• scripts/teardown_vector_search.sh — その課金を停止する唯一の手段です。リビジョンから SCL-lookup が削除されるまで実行を拒否します。--yes が必要です

• scripts/deploy_proxy.sh — Apigee 側の手順です。冪等で、--dry-run に対応しています

• scripts/read_debug_session.sh — セッションを --arm で設定し（実際に終了したときに表示）、トランザクション JSON を手作業で解析する代わりに、verify.md のチェックリスト形式で読み戻します

• scripts/compile_check.py — 組織を必要とせず、テンプレートをオフラインでコンパイルします