apigee-agent-gateway-governance

将 Apigee 用作 Agent Gateway 服务扩展

在 GCP Agent Gateway 上，将 Apigee 代理接入为 ext-proc 调用。该代理是处理器，而不是 API 代理：它没有后端，会检查网关传给它的大模型请求和响应，并返回判定结果。

由你构建代理，用户无需构建。

两种模式，共用一个架构。开始之前先决定模式，并明确说明。
存在输入文件 → 生产模式：输入文件就是契约，所有值都必须来自该文件；缺少字段或字段格式错误时应拒绝，而不是使用默认值。没有输入文件，且用户描述的是期望结果 → 开发模式：应用文档中的默认值，展示包含时长的计划并取得批准；先只配置身份和计量；最后写入 apigee-agent-gateway-governance.yaml 作为交接文件。assets/apigee-agent-gateway-governance.example.yaml 说明了两种模式共用的架构。

模式、默认值、时长、费用披露，以及约束两种模式的互锁机制：references/modes.md。开始之前请先阅读。

为计划的 ACTION 列着色——绿色 REUSE，青色 CREATE/RESERVE，黄色 APPEND/MODIFY；完整调色板见 references/modes.md。黄色最有意义：它是唯一一个表示现有用户资源将被修改的信号。以纯文本呈现时，修改资源的那一行会与其他十几行毫无区别——而那恰恰是需要审批的那一行。

前置条件：Agent 的运行位置

在构建任何内容之前先检查这一点。它决定流量能否到达网关；配置错误时不会有任何提示——下面的每一步都可能成功，但实际上没有流量到达。

使用 Agent Runtime，通过 agent_gateway_config / agent_to_anywhere_config 创建。这是受支持的路径，编排器会为你构建客户端侧 PSC、路由、DNS 和证书信任配置。这里没有 gcloud 命令，也没有控制台路径——只能在创建 Agent 时通过 SDK 配置。绑定方式请参阅通过 Agent Gateway 路由流量，完整示例见 references/networking-psc.md。

在 Agent 的 env_vars 中设置 GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES: "False"，否则每次调用都会返回 401，且发生在 Agent 自身的 sessions.create 上、用户代码运行之前。部署时不会显现此问题。完整症状和隔离方法见 references/gotchas.md 中的 Agent Gateway 部分。

除此之外，Agent 的运行位置已确定——前提是网关和 Agent 均可正常运行。不要主动解释如何构建它们，也不要列出不受支持的计算环境；如果确实相关，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 绑定到网关的 Agent Runtime 客户端
google-adk	>=2.9,<3	仅在使用 ADK 构建测试 Agent 时需要

在 gcloud >= 588.0.0 上：每项功能都必须保留其 uid，且模板绝不能声明 endpoints 或 targets。 目前全部六项功能都设置了 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，或使用已安装该依赖的 Python 3 运行；gcloud 自带的解释器不包含它，而 SDK 捆绑的 yaml 是 Python 2 版本。

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

执行模型

分为三个层次，选择哪一种并非风格问题：

层级	用途	原因
AFT YAML 模板	代理本身	受版本控制、可审查、可比较差异
gcloud	PSC、DNS、AuthzExtension、AuthzPolicy	有原生命令
REST（curl）	环境属性、环境组、部署、调试会话	目前没有对应的 gcloud 命令

客户只需维护一个输入文件 （assets/apigee-agent-gateway-governance.example.yaml）。它是受版本控制的制品。切勿手动编辑生成的代理：请重新生成。

使用脚本执行 Apigee 端的操作，不要手动执行。 以下步骤 1、3 和 4 有先后依赖关系，而且每一步失败时的报错看起来都像是另一个问题。scripts/deploy_proxy.sh 会执行这三步、保留属性映射、轮询异步操作，并在部署未能以 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 运行。

向量搜索标志是「每项声明了默认值的功能都要编辑默认值」这一规则的唯一例外。 这三个 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（一个列表，每种线缆形态对应一项）， gateway.manageNetworkConfig

matchPaths 驱动两个产物；必须从同一列表生成两者。 AuthzPolicy 的 paths[].suffix 每项对应一个后缀，原样保留前导标点——它决定网关将请求路由到 Apigee 的路径。模板中的 LLM_URI_MATCH 为每项生成一个 (request.uri Like "*<entry>*") 子句，并用 OR 连接，去掉前导 : 或 /—— 它决定请求到达后代理对哪些请求执行操作。已提供的两项默认值会生成：

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

AuthzPolicy 是外层关卡，优先级更高：如果后缀列表比 matchPaths 窄，缺少的形态 就根本不会到达 Apigee。两者都要从输入文件生成；如果文件与默认值不一致，绝不能 使用默认值——输入文件是可审核的契约，部署后不匹配的问题将无从察觉。

列表只有一项也完全合理，它决定一种形态。删除一项就会悄无声息地少支持 一种形态——部署正常完成，但被删形态的事务数为零——并同时缩小 feature-normalize、Model Armor 和缓存的覆盖范围。参见 references/gotchas.md 中的 Runtime。

只要启用了 semanticCache，它就是已知问题——先警告，再构建。 键仅由提示词嵌入构成：不包含调用方、模型或形态。因此命中会跨调用方共享—— 相似提示词会共用答案——而在一种形态后面只有一个模型，并不能使其安全。形态增多 后，先作答的模型也会替其他模型作答：不同形态之间会出现空的 HTTP 200，同一形态内 则会出现错误模型的响应体。只要启用缓存就要警告，不仅限于多形态，然后继续构建。 措辞参见 references/modes.md；机制参见 references/gotchas.md。

每项都是后缀匹配。 这些后缀由你编写，而不是用户——根据其 Agent 实际调用的 端点推导出来，不要让用户自行判断后缀。Vertex 的 OpenAI 兼容端点与 api.openai.com 需要不同的条目，写错后会悄无声息地无法匹配；格式和依据见 references/gotchas.md 中的 Runtime。

没有 apiShape 字段。 用量计量不依赖线缆形态——JS 会统一计算数量——因此该 字段没有选中任何内容，已被移除。添加一种形态，需要在 extract-model.js 中增加 一个 || 分支，并在 matchPaths 中添加一项。

三个位置都记录了调用主机名，且三者必须一致——Apigee 环境组、 AuthzExtension 的 authority/service，以及私有 DNS A 记录。三者都使用同一个值： 这是必须维持的构建不变量，不是要向用户提出的问题。只有在调用始终无法到达时， 这才会成为排查重点，此时应首先检查。还要注意构建顺序——在主机解析成功且代理 部署完成之前，AuthzExtension 不会生效，因此“扩展已创建”并不能证明该调用链路 正常。参见 references/gotchas.md 中的 Runtime。

工作流

0. 网关：为它配置通往 VPC 的路由

没有 networkConfig 的网关无法路由到客户的 VPC，也无法解析外呼主机名。此技能会完成相关配置——网络连接、出站流量和 DNS 对等连接——因此，缺少这些配置是一个构建步骤，而非阻碍，应当这样说明。不要一开始就对一个你即将创建的资源发出警告。

这里有一件事确实需要用户决定，这也是它被列为第 0 步而非静默前提的原因：连接出站流量是单向操作，且会影响他们现有的流量。在执行任何操作之前，就在计划中敲定此事——参见下文“提前确认所有事项”。如果用户担心生产环境中的网关，先捕获一次已知正常的 Agent 交互记录很有价值，因为这样可以区分“从未正常工作”和“我们把它弄坏了”；这是可供选择的预防措施，不是必须执行的步骤。

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 策略，它与我们的策略共存，且 egress JWT 不需要它。你不会创建网关，因此应先评估，而不是想当然。参见 references/gotchas.md 中的 Agent Gateway。

空的 networkConfig 输出表示配置缺失，而且很容易被忽略：网关仍能完美处理普通 Agent 流量，因为这类流量会发往 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

无论哪种情况，都必须先有 networkConfig，才能开始 Apigee 工作——不是因为缺少它会导致错误，而是因为否则后续每个步骤都会成功，却不起任何作用。

使用脚本，而不是原始命令：import 会对整个资源执行 upsert，而手动编写的 YAML 会悄无声息地丢弃网关的 registries 和 protocols。原因以及 etag 和 PROTOCOL_UNSPECIFIED 的处理方式，参见 references/gotchas.md。

1. Apigee：启用环境

环境必须带有 apigee-service-extension-enabled=true。没有对应的 gcloud 标志；请 PATCH properties 映射。

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——两者可以共存；如果 Analytics 看起来缺失，那是单独的、按环境配置的附加组件。参见 references/gotchas.md。

使用专用环境，并且只关联一个 envgroup。 如果一个环境关联两个 envgroup，网关对每个请求都会返回 404，且不会调用扩展。这样也能让 / 基础路径保持空闲，代理正是使用此路径部署的。

scripts/ensure_apigee_environment.sh 会创建环境，将其关联到区域运行时实例，并创建和关联 envgroup——因此成功后，第 2 步也已完成。它会创建计费资源，且不带 --yes 时不会应用任何更改；相关同意应在计划中取得，而不是在这里取得。

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

该脚本支持幂等执行和断点续跑；如果环境已关联到其他 envgroup，或 envgroup 已存在于不同的主机名下，它会以退出码 2 拒绝执行。它还会处理操作手册中经常出错的三件事——创建时省略 type、需要四分钟且会锁定环境的实例关联操作，以及轮询操作，而不是过早成功的 GET。

2. Apigee：在 callout 主机名上配置 envgroup

如果已运行步骤 1 的脚本，则此步骤已完成。请验证，或手动为现有 envgroup 配置。主机名必须与 callout 主机完全一致，并且该组必须关联到 环境。

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

环境属于多少个 envgroup？ 如果超过一个，callout 将无法到达。deploy_proxy.sh 会在进行任何操作前检查这一点，并以状态码 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 会传入空的调用方参数映射，因此每个 feature 都会解析自己的默认值，而模板中同名参数的声明不会被读取。编辑模板不会产生任何变化，而且不会提示，编译仍会通过。实测：将模板中的 MA_CONTINUE_ON_ERROR 设为 DRY_RUN，最终仍会在一个 fail-closed 策略上部署 ENFORCE。LLM_URI_MATCH 在四个 feature 中都有声明，四处必须保持一致。scripts/compile_check.py 会在发现任何不一致时失败。没有 --parameters 标志。

要启用可选配方，请将其 feature 添加到模板的 features 列表中。请参阅 references/recipes.md。

输入文件中的 tokenMetering.models 不会生成任何内容。 它只记录已有的桶，不会创建桶。只有当桶在 feature-token-metering.yaml 中具有 LLMTokenQuota 步骤，并且有匹配的 *_TOKEN_LIMIT 参数时，它才是真实存在的。目前有三个：gemini-pro、gemini-flash 和 other——用于匹配名称中既不包含 pro 也不包含 flash 的任何模型。向列表中添加第四个条目不会统计任何内容；而且省略 other 会导致所有非 Gemini 模型的统计被静默关闭：计数会被提取，然后丢弃，整个事务中也没有任何 ratelimit 引用。添加模型需要修改 feature 文件，而不是配置。

4. 部署

先部署到 service-extension 环境，然后确认部署信息显示 proxyDeploymentType: EXTENSIBLE。

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

STANDARD 表示它不会管理 Agent 在 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。Apigee 实例的 consumerAcceptList 必须 包含你的项目，否则连接永远无法达到 ACCEPTED 状态。

Agent → 网关这段链路是上述前提条件，这里不会构建。

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 都是如此。请自行解析；把两个编号 都告诉用户并没有帮助。以防提示始终没出现，陷阱是：网关中的 serviceExtensionsServiceAccount 所用编号属于 Google 管理的租户项目，并非用户的 项目，而且这是屏幕上唯一显示的编号，所以很容易直接复制。填错编号也能成功导入， 但不会匹配任何目标。请从 assets/authz-policy.example.yaml 复制对应位置。

7. 验证

不能用 curl 测试——主机是内部的，代理需要网关的 IAP 出口 JWT。运行 scripts/read_debug_session.sh --arm，发起一轮对话，再用 --session 读取结果。 在这个范围很窄的后缀列表下，每轮对话中每种受治理形状应有一笔事务；仅凭 零笔事务不能说明 callout 没有运行——脚本会打印用于确认的探测结果。

硬性规则

每一步都要加条件门控——具体需要多严格取决于你的 AuthzPolicy。 未加门控的 continueOnError="false" 策略遇到任何不包含提示词的调用都会出错，并且 会中断 Agent 的对话轮次。这是这里历来最常见的故障。

后缀列表较窄时，只有模型调用会路由到 Apigee，因此大多不会触发这个问题。扩大策略 范围后，问题会立即出现：此时 ext-proc 会看到所有 Agent 出站流量——会话创建/读取、 appendEvent、OpenTelemetry 导出——一个单问题轮次测得 12 次调用，其中只有一次是模型 调用。无论如何都要为这些步骤加条件；条件开销很低，而且能让策略日后安全扩展。完整测量数据见：references/gotchas.md。

• 模型调用：(request.uri Like "*generateContent*")

切勿让自己的计量逻辑触发失败关闭。 JavaScript 和配额策略应保留 continueOnError="true"，以免计量错误中断大模型流量。

此技能默认进行计量，也可按需启用强制执行。 强制执行配置为 assets/feature-token-enforce.yaml：请求流中的 EnforceOnly 策略与响应流中的 CountOnly 部分共享各自的 SharedName。将其加入模板的功能列表。已在 ext-proc 流量上完成实时验证——超出预算的调用方会收到 429，模型不会被调用。

切勿用 CountOnly=false 代替：在响应流中，它无法进行门控（答案已经在线路上传输）， 还会冻结计数器，导致计量也一并丢失。

每次提供此选项时，都要说明两点。它会晚一个请求生效——触及上限的那一轮仍会完成， 因为只有模型返回后才能得知 token 成本。它还会按请求的模型进行分桶；在 OpenAI 别名下，该模型可能与计数侧计费所用的解析后模型不同。这两个陷阱都会表现为 “它从不拒绝”：references/gotchas.md。

将模型归一化到分桶。 使用兼容 OpenAI 的端点时，请求正文中的模型是别名，而响应 正文中的是解析后的名称（google/gemini-2.5-pro）。在响应路径上对原始名称做精确 匹配会失败。

jsonPath 的第三个参数必须为 true，这样才会返回标量。省略它时，配额策略收到的 是无法解析的节点。

参考资料

• references/modes.md — 请先阅读。 如何回答“你能做什么”、开发与生产模式、默认值、持续时间、费用说明、互锁机制，以及如何阅读评估报告

• scripts/assess_integration.sh — 只读。 设置状态摘要后附逐项检查表；--json 会包含这两部分。先说明摘要，并读出 Enforcement 行。规划前先运行：它决定 CREATE 还是 REUSE。TODO 是构建步骤，不代表失败；只有 FAIL 会以非零状态退出

• references/networking-psc.md — 两段网络连接、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；配额读取 agw.total_tokens，出于同样的原因，该值由计量功能自己的 JS 在响应路径上设置。

• scripts/ensure_apigee_environment.sh — 创建环境，将其关联到实例，创建并关联 envgroup。支持幂等操作，须通过 --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 启动会话（会在会话实际关闭时打印提示）并按 verify.md 检查清单读取会话，无需手动解析事务 JSON

• scripts/compile_check.py — 离线编译模板，无需组织