---

name: apigee-agent-gateway-governance metadata: version: "1.0.2" 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.

Usage Attribution

MUST READ: Before executing any gcloud, REST API, or MCP command, you MUST read and follow the instructions in Usage Attribution.

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 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-governance.example.yaml). It is the version-controlled artifact. Never hand-edit the generated proxy: regenerate it.

Run the Apigee-side sequence with the script, not by hand. Steps 1, 3 and 4 below are order-dependent and each fails in a way that reads as a different problem. scripts/deploy_proxy.sh does all three, preserves the properties map, polls the async operation, and exits non-zero if the deployment does not come up 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]

Run it without --yes first: it prints the plan and changes nothing. Show that plan, then re-run with --yes once the user agrees.

The vector-search flags are the one exception to "edit the default in every feature that declares it". Those three ids are substituted at deploy time and checked for leftovers; hand-editing them into feature-semantic-cache.yaml deploys fine, skips the check, and makes the file single-use.

scripts/ensure_gateway_connectivity.sh is the same idea for the gateway leg (step 0). It is the only part of this skill that modifies a resource the user already owns, so it applies nothing without --yes.

The steps are written out below so you can diagnose a failure, not so you can retype them.

Inputs you must resolve first

Environment prerequisites: references/setup.md — gcloud SDK (588+), project, billing, gcloud services enable, region, credentials, IAM. Nothing below creates any of it.

Prod: from the input file, then environment, then ask — never invent. Dev: apply the references/modes.md defaults, and ask only for what has none.

• project, region
• apigee.org, apigee.environment, apigee.envgroup, apigee.hostname, apigee.proxy
• network.vpc, network.subnet, network.networkAttachment
• gateway.name, gateway.matchPaths (a list, one entry per wire shape), gateway.manageNetworkConfig

matchPaths drives TWO artifacts; write both from the same list. The AuthzPolicy paths[].suffix gets one suffix per entry, verbatim with leading punctuation kept — it decides what the gateway routes to Apigee. The template's LLM_URI_MATCH gets one (request.uri Like "*<entry>*") clause per entry, OR-ed, leading : or / stripped — it decides what the proxy acts on once it arrives. The shipped two-entry default gives:

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

The AuthzPolicy is the outer gate and wins: a suffix list narrower than matchPaths means the missing shape never reaches Apigee at all. Derive both from the input file and never from the default when the file disagrees — the file is the reviewable contract and a mismatch is invisible once deployed.

A one-entry list is legitimate and governs one shape. Dropping an entry governs one fewer silently — deploys clean, zero transactions for the shape dropped — and narrows feature-normalize, Model Armor and the cache together. references/gotchas.md, Runtime.

semanticCache is a KNOWN ISSUE whenever it is on — warn, then build it. The key is the prompt embedding alone: no caller, no model, no shape. A hit therefore crosses callers — similar prompts share an answer — and one model behind one shape does not make it safe. With more shapes the first model to answer answers for the other too: empty HTTP 200 across shapes, wrong-model body within one. Warn whenever the cache is on, not only on multi-shape, then build. Wording: references/modes.md; mechanism: references/gotchas.md.

Each entry is a SUFFIX match. You write these, not the user — derive them from which endpoint their agent actually calls, and do not ask them to reason about suffixes. Vertex's OpenAI-compatible endpoint and api.openai.com need different entries, and getting it wrong governs nothing silently; the forms and the evidence are in references/gotchas.md, Runtime.

There is no apiShape field. Metering does not depend on the wire shape — the count is normalised in JS across both — so the field selected nothing and was removed. Adding a shape is an || branch in extract-model.js plus an entry in matchPaths.

Three places carry the callout hostname and all three must match — the Apigee envgroup, the AuthzExtension authority/service, and the private DNS A record. You set all three from one value: a build invariant to hold, not a question for the user. It becomes a topic only when a callout never lands, and then it is the first check. Build order matters alongside it — the AuthzExtension is inert until the host resolves and the proxy is deployed, so "the extension exists" is not evidence that leg works. references/gotchas.md, Runtime.

Workflow

0. Gateway: give it a route into the VPC

A gateway with no networkConfig has no route into the customer's VPC and cannot resolve the callout hostname. This skill builds it — network attachment, egress and DNS peering — so its absence is a build step, not a blocker, and should be reported that way. Do not open with an alarm about a resource you are about to create.

One thing here does need the user, and it is the reason this is step 0 rather than a silent prerequisite: attaching egress is one-way and affects traffic they already run. Settle it in the plan, before anything executes — see "Confirm everything up front" below. Capturing a known-good agent turn first is worth doing when they are nervous about a production gateway, because it separates "never worked" from "we broke it"; it is a precaution to offer, not a step to impose.

gcloud network-ser