apigee-agent-gateway-governance

Files (25)

• SKILL.md
• apigee-agent-gateway-governance.example.yaml · assets/
• apigee-proxy-template.yaml · assets/
• authz-extension.example.yaml · assets/
• authz-policy.example.yaml · assets/
• feature-identity.yaml · assets/
• feature-model-armor.yaml · assets/
• feature-normalize.yaml · assets/
• feature-semantic-cache.yaml · assets/
• feature-token-enforce.yaml · assets/
• feature-token-metering.yaml · assets/
• gotchas.md · references/
• modes.md · references/
• networking-psc.md · references/
• recipes.md · references/
• setup.md · references/
• verify.md · references/
• assess_integration.sh · scripts/
• compile_check.py · scripts/
• deploy_proxy.sh · scripts/
• ensure_apigee_environment.sh · scripts/
• ensure_gateway_connectivity.sh · scripts/
• ensure_vector_search.sh · scripts/
• read_debug_session.sh · scripts/
• teardown_vector_search.sh · scripts/

SKILL.md (first lines)

# 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](references/attribution.md).

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).

```bash
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.

```bash
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`:

```bash
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

From google/skills, Apache-2.0.

More from google/skills