apigee-x-ai-gateway

Apigee X AI gateway

When to use

• Build, change or inspect an Apigee X AI gateway proxy. Deliver proxy files, operator setup steps and a test plan.
• Help an operator deploy or prepare pre-import steps. Infrastructure changes, including creating an organization, need approval.
• Anthropic-format conversion and streaming are not implemented. Reject streaming requests explicitly.

Dependencies and tools

• Use the pinned apigee-x-proxy-development skill throughout proxy work. If it is missing, stop and ask the user to install it.
• Open the exact reference before writing each policy, flow or condition, using the pinned dependency map. In the handoff, list each file with the reference you opened for it.
• Take syntax from the references. The gateway references and the development skill are the source of truth for policy XML, flows, conditions and variables. Availability, entitlement, quotas and pricing change over time: check them in current official documentation or with the user. If the development skill and official documentation disagree, follow the conflict guidance.
• Build only what the selected workflow describes. Read it in full first. If a request or detail isn't covered, say so and ask.
• Custom flow variables must not start with an Apigee-owned prefix (request., response., message., route., target., proxy., client., system., fault., error., apiproxy., environment., organization.). See custom flow variables.
• Tools: use terminal and file tools. Check apigeecli commands with --help; never invent flags or API calls.

Capability	Reference	Output
Vertex AI chat target	Vertex target	OpenAI-compatible Gemini endpoint, native Google auth, operator API/IAM setup
Routing	Routing	Alias, endpoint and auth mapping; bundle; route checks
Accumulated tokens	LLMTokenQuota	Product-sourced limit, counter scope, paired policies, counter tests
API keys and product configuration	API product setup	Operator-run product, developer, app and attribute steps with readback
Spending budget	Cost budget	Prices and budget on the API Product, cost calculation, paired cost counters, tests
Prompt bursts	PromptTokenLimit	Rate, trusted identity, complete prompt sources, failure tests
Prompt and response protection	Model Armor	Failure contract, template and identity readiness, safety tests
FAQ reuse	Semantic cache and trial checklist	Fixed configuration, answers safe for every caller, gated bundle
Missing Vertex dependencies	Operator setup	Guided creation; exact IDs and URLs before the ZIP

Shared gates

Location before commands

• Agree processing and storage locations for every regional dependency. Never infer a region; keep __APPROVED_REGION__ and __APPROVED_TEMPLATE_LOCATION__ until agreed.
• Check availability of each model, filter, embedding model and Vector Search separately, plus quotas and connectivity. With approved read access, read back exact resource names and locations.
• Never relocate, modify shared resources or weaken residency or filters. For Model Armor, follow the location mapping.

Privacy

• Keep configuration, credentials, private endpoints and raw test output outside Git.
• Never ask for secrets in chat or embed keys in XML, JavaScript or properties. Keep tokens out of command arguments and verbose traces.
• Mask copied native variables before capture. Never log authorization headers, sensitive prompts or raw responses. Strip internal routing metadata from responses.

Procedure

1. Discover. Read supplied configuration, then ask about all gaps at once, each with a recommendation. Confirm organization, environment, proxy name, base path, endpoints, models, formats, caller and backend authentication, streaming and test budget. Select external/KVM or Vertex AI explicitly; for Vertex read Vertex target before generating setup or target files. Agree aliases and unknown-model errors; recommend explicit rejection, never implicit fallback. Keep existing identifiers.
2. Approve and baseline. Confirm the project, ownership, changes, exposure and call limits. Get separate approval for reads, backend calls, setup and IAM, deployment, retained costs and trials. Probe approved backends with a small synthetic call and record the status, resolved model and usage. Resolve authentication failures with the user; never retry blindly.
3. Build incrementally.
   • Keep working proxies and operator changes. Write real files, native policies first.
   • Validate the model allowlist and translate aliases before the backend call. Keep caller and upstream authentication separate.
   • For fixed target URLs, set Boolean target.copy.pathsuffix=false in the TargetEndpoint request flow.
   • On every route, remove caller credential headers before inserting the backend credential.
   • Mark any file written without its reference as unverified and ask.
   • Check policies, attachment order, XML, references and ZIP structure.
4. Import and deploy as approved. Get separate approval for runtime credentials. Before the ZIP, supply the Vertex target, Model Armor and semantic cache handoffs that apply. Never run manual instructions yourself. Deploy only approved revisions. For progressive updates, include current-deployment inspection and explicit revision replacement in the operator handoff; use override=true for an approved replacement rather than requiring a separate undeploy. Read back configuration and readiness after each write.
5. Verify and hand off.
   • With every API-key proxy, deliver API product setup instructions for the generated proxy. For token quotas, list the product's LLM operation model names and explain that they are backend model IDs, not caller aliases.
   • For operator-run labs, print copyable curl test commands after deployment instructions, using the configured hostname, base path and aliases. Include secure key entry with no secrets in arguments or logs, small synthetic requests, output-token limits, expected status/body checks and an explicit maximum call count within the approved cost limit. Never use unbounded loops or automatic retries. The operator runs these commands; do not execute them yourself.
   • Cover each lab’s success and rejection cases. Explain how masked diagnostics attribute the policy and establish backend invocation or non-invocation; HTTP status alone is insufficient. Stop at the call limit and report unreproduced cases as unverified.
   • Run acceptance cases only when separately authorized; otherwise provide the operator-run commands. Report structural checks, direct-backend results and deployed-proxy results separately.
   • Report what was built and tested, retained resources and costs, and gaps.
   • No cleanup or publication without approval.

Verification boundary

• Read the error body, not just the status code. A fault-formatting policy can run and still leave Apigee's native fault on the wire, leaking a caller identity or policy name. See sanitized errors.
• Known limits (capability status): an unchanged passthrough tests upstream routing, not Apigee request mapping; non-streaming results say nothing about streaming; routing alone is not a complete gateway.