/apigee-agent-gateway-governance

name: apigee-agent-gateway-governance
metadata:
  version: "1.0.0"
  category: AiAndMachineLearning
description: >-
  Stands up an Apigee API proxy that a Google Cloud Agent Gateway calls as an
  ext-proc (Service Extension) callout on an agent's LLM traffic, to meter
  token usage per model, extract caller identity, and apply Model Armor prompt
  screening or a semantic cache. Use when wiring Apigee in as an AI gateway
  behind an Agent Gateway, when an agent's model egress needs governing, or
  when a callout proxy returns no verdict and you need to find out why. The
  distinguishing question is whether Apigee forwards the traffic or only
  inspects it: this skill is inspect-only, and builds the proxy itself. Don't
  use it when Apigee is meant to receive a request and route it onward to a
  backend — including hosting an MCP server behind Apigee — which needs a proxy
  with a target instead. Don't use for governing the agent's calls to tools or
  MCP servers. Don't use for choosing or switching which model a request goes
  to. Don't use for creating the Agent Gateway itself, nor for Apigee hybrid.

Apigee as an Agent Gateway Service Extension

Wires an Apigee proxy in as an **ext-proc callout** on a GCP Agent Gateway. The proxy is a **processor, not an API proxy**: it has no backend, inspects the LLM request and response the gateway hands it, and returns a verdict.

You build the proxy; the user does not.

**Two modes, one schema. Decide which before anything else, and say which.** Input file present → **prod mode**: it is the contract, every value comes from it, and a missing or malformed field is a refusal, not a default. No input file and the user is describing an outcome → **dev mode**: apply the documented defaults, show a plan with durations and get approval, start with identity and metering only, write `apigee-agent-gateway-governance.yaml` at the end as the handoff. `assets/apigee-agent-gateway-governance.example.yaml` documents the schema both modes use.

Modes, defaults, durations, cost disclosure and the interlocks that bind both: `references/modes.md`. **Read it before you start.**

**Colour the plan's ACTION column** — green `REUSE`, cyan `CREATE`/`RESERVE`, yellow `APPEND`/`MODIFY`; full palette in `references/modes.md`. Yellow is the one that earns its place: it is the only signal that a resource the user already owns is being changed. Rendered plain, the one row that modifies something is indistinguishable from the dozen that do not — which is exactly the row the approval exists for.

Prerequisite: where the agent runs

Check this **before** building anything. It decides whether traffic can reach the gateway at all, and it is silent when wrong — every step below still succeeds while nothing arrives.

**Use Agent Runtime**, created with `agent_gateway_config` / `agent_to_anywhere_config`. It is the supported path and the orchestrator builds the client-side PSC, routing, DNS and cert trust for you. There is no `gcloud` surface for this and no console path — it is SDK-only, at agent creation time. See [Route traffic through Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-gateway-runtime-deploy.md.txt) for the binding, and `references/networking-psc.md` for a worked example.

**Set `GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES: "False"` in the agent's `env_vars`, or every invocation 401s** on the agent's own `sessions.create`, before user code runs. Deploy-time invisible. Full symptom and isolation: `references/gotchas.md`, Agent Gateway.

Where the agent runs is otherwise settled — the premise is a working gateway and a working agent. Do not explain how to build one or list unsupported compute unprompted; `references/networking-psc.md` has the constraints if it turns out to matter.

Tool versions

Do not assume these are installed or current.

Tool | Minimum | Why -------------------------------------------- | ----------- | --- `gcloud` | **588.0.0** | `apigee apis import --from-template` is on the GA track at this version; older SDKs need `gcloud beta` `google-cloud-aiplatform[agent_engines,adk]` | `>=2.1,<3` | Agent Runtime client used to bind the agent to the gateway `google-adk` | `>=2.9,<3` | only if you build the test agent with ADK

**On gcloud >= 588.0.0: every feature must keep its `uid`, and the template must never declare `endpoints` or `targets`.** All six features set `uid` today and the template declares neither, so the shipped bundle is correct — but both are load-bearing now, and breaking either one still compiles, still deploys, and reports nothing. Mechanism and symptoms: `references/gotchas.md`, under 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` needs PyYAML and names the interpreter if it is missing. `pip install pyyaml`, or run it with a Python 3 that has it; gcloud's bundled interpreter does not, and the SDK's vendored `yaml` is Python 2.

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

Execution model

Three layers, and the choice between them is not stylistic:

Layer | Used for | Why --------------------- | ------------------------------------------------------ | --- **AFT YAML template** | the proxy itself | version-controlled, reviewable, diffable **`gcloud`** | PSC, DNS, AuthzExtension, AuthzPolicy | native commands exist **REST (`curl`)** | env properties, envgroups, deployments, debug sessions | no `gcloud` equivalent today

The customer owns **one** input file (`assets/apigee-agent-gateway-governan