Vertex AI Agent Builder¶
Agents you write in code and deploy to Vertex AI Agent Engine can send every model call through the gateway: each call is then checked against your policies, charged to the right team and recorded in Request logs, and the agent can use Claude or GPT as well as Gemini. Agents built in Google Cloud's no-code agent tools call Google's models directly and can't be pointed elsewhere; only the tools they call (your own code) can use the gateway.
What it is¶
| Part | Who calls the model | Through the gateway |
|---|---|---|
| An agent written with the Agent Development Kit (ADK), LangGraph or another framework, deployed to Agent Engine | Your code | Yes, with the framework's model pointed at the gateway |
| Agents built in the console without code (conversational agents, playbooks) | Google, with a Gemini model | No |
| A tool or webhook such an agent calls (a Cloud Run service, a function) that calls a model itself | Your code | Yes |
The two settings¶
ADK uses the Google GenAI SDK, which reads its address and key from the environment:
| Setting | Environment variable | Value |
|---|---|---|
| Base address | GOOGLE_GEMINI_BASE_URL |
https://<your-gateway> (no /v1beta: the SDK adds it) |
| Key | GOOGLE_API_KEY |
Your Vidai key (starts vk_), never a provider's key |
| Mode | GOOGLE_GENAI_USE_VERTEXAI |
FALSE, so the SDK uses a key rather than Google Cloud credentials |
ADK pins google-genai below 3.0, which asks for /v1beta. If you call google-genai 3.0 or later on its own, it
asks for /v1 by default: also set GOOGLE_GENAI_API_VERSION=v1beta.
The SDK sends the key as x-goog-api-key, which the gateway accepts. For a framework or tool that uses the OpenAI SDK,
use OPENAI_BASE_URL = https://<your-gateway>/v1 and OPENAI_API_KEY instead.
Keep the key in Secret Manager. The gateway's address is under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once.
A minimal call¶
An ADK agent, run locally first:
from google.adk.agents import Agent
root_agent = Agent(
name="helper",
model="gemini-3.5-flash",
instruction="Answer briefly.",
)
export GOOGLE_GENAI_USE_VERTEXAI=FALSE
export GOOGLE_GEMINI_BASE_URL="https://<your-gateway>"
export GOOGLE_API_KEY="vk_…"
adk run helper
When you deploy it to Agent Engine, pass the same three variables in env_vars (with the key from Secret Manager), so
the deployed agent calls the gateway too.
The agent can use any approved model, wrapped in ADK's Gemini class so the call stays in the Gemini format:
from google.adk.models import Gemini, then model=Gemini(model="claude-sonnet-4.5"). A bare "claude-…" name
would send ADK to the Anthropic SDK, which ignores these variables, and a bare "gpt-…" name isn't known to ADK. The
gateway translates the Gemini-format request for that provider and the answer back into the Gemini shape ADK reads.
Streaming¶
ADK's streamed answers (:streamGenerateContent) come back in the Gemini event format whichever provider answered.
Nothing to set.
Tool calls¶
ADK offers its tools to the model in each call; the model's function calls come back through the gateway on every
provider it translates to. Tools from MCP servers with dotted names (files.read) are renamed for providers that don't
allow dots and restored in the answer. In Request logs, the Tool filter under More filters finds the calls
that offered or called a tool by its name.
Reading what the gateway did¶
ADK doesn't show response headers. Find the agent's calls in Request logs: filter by Key or Model under More filters. Each call shows the model that answered, its cost, and which policy or rule acted on it. In code that calls the Google GenAI SDK directly, see Google GenAI SDK for Python.
Errors¶
The gateway writes its errors in the Gemini format, so ADK raises the SDK's usual ClientError or ServerError. The
common ones:
| Status | Gateway code | What to do |
|---|---|---|
| 401 | invalid_api_key, missing_api_key |
Check GOOGLE_API_KEY in the agent's environment |
| 403 | model_not_allowed, denied_by_routing_rule |
Use a model the key may call |
| 403 | content_guardrail_blocked |
A guardrail stopped the content |
| 404 | model_not_found |
Check the name against Models |
| 429 | rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded |
Slow down |
Match on the x-vidai-error-code header where you can read it, not on the message.
Model names¶
Use the names your organisation has approved, as listed under Models in the Control room. Through the gateway,
GET /v1beta/models lists exactly the models your key may call, in the Gemini shape.
What goes through the gateway¶
| On Google Cloud | Through the gateway |
|---|---|
| ADK and other framework agents on Agent Engine, Cloud Run or anywhere, with their model pointed at the gateway | Yes, to every provider your organisation has set up |
| Your tool code (Cloud Run, functions) with an SDK pointed at the gateway | Yes |
| No-code agents built in the console, and Gemini in Google Cloud's own products | No: Google calls its own models |
Check it works in a minute¶
Run adk run helper locally with the variables above and ask "Reply with exactly: ok". ok means the address and key
are right. The call shows in Request logs within seconds.
Good to know¶
- Agent Engine runs in Google's network: the gateway must be reachable from there.
- The gateway can itself call Gemini on Vertex AI once an admin adds Vertex AI as a provider, so the agent keeps Google's models while its calls are governed.
- Give each deployed agent its own key (an agent's key in Vidai works well) so each one's spend is apart.
- Agent Engine's own features that call a model for you (its memory and session features) call Google's models directly.