Skip to content

Google ADK

Your ADK agents, tools and runners stay as they are. Give the model one setting and every call the agent makes goes through the gateway: checked against your policies, charged to the agent's team and recorded in Request logs. The same Gemini model class can call GPT and Claude models too, answered in the Gemini shape ADK already reads.

What it is

The google-adk package for Python. Its Gemini model class calls models through the google-genai SDK, in Gemini's generateContent format, which the gateway accepts at /v1beta/models/…. Its AnthropicLlm class calls them through the Anthropic SDK, in the Messages format, which the gateway accepts at /v1/messages. Either works; Gemini needs the least set-up.

The two settings

For the Gemini class (the Gemini API, not Vertex AI):

Setting Environment variable Constructor argument Value
Base address GOOGLE_GEMINI_BASE_URL Gemini(base_url=…) https://<your-gateway>, without a version (the SDK adds /v1beta/models/…)
Key GOOGLE_API_KEY Gemini(client_kwargs={"api_key": …}) The agent's Vidai key (starts vk_), never a provider's key
Backend GOOGLE_GENAI_USE_VERTEXAI=false The Gemini API format, which the key above works with

The SDK sends the key as x-goog-api-key, which the gateway accepts. Issue the key to the agent under Applications & agents (the agent's Keys section, Issue a key); its secret is shown once. The gateway's address and the base URL for each kind of SDK are under Connect your app on the Keys page and in System › Settings › Gateway.

export GOOGLE_GEMINI_BASE_URL="https://<your-gateway>"
export GOOGLE_API_KEY="vk_…"
export GOOGLE_GENAI_USE_VERTEXAI=false

For the AnthropicLlm class, the Anthropic SDK's own variables: ANTHROPIC_BASE_URL="https://<your-gateway>" and ANTHROPIC_API_KEY="vk_…".

A minimal call

import asyncio
from google.adk.agents import Agent
from google.adk.models import Gemini
from google.adk.runners import InMemoryRunner
from google.genai import types

agent = Agent(
    name="assistant",
    model=Gemini(model="gemini-3.5-flash", base_url="https://<your-gateway>"),
    instruction="Reply briefly.",
)

async def main():
    runner = InMemoryRunner(agent=agent, app_name="demo")
    session = await runner.session_service.create_session(app_name="demo", user_id="u1")
    message = types.Content(role="user", parts=[types.Part(text="Say hello in Dutch.")])
    async for event in runner.run_async(user_id="u1", session_id=session.id, new_message=message):
        if event.is_final_response():
            print(event.content.parts[0].text)

asyncio.run(main())

The same agent calls GPT or Claude: put a name such as gpt-4o-mini or claude-sonnet-4.5 in Gemini(model=…). The gateway translates the request for that provider and the answer back into the Gemini shape, streams and function calls included. Always wrap the name in Gemini(…) (or AnthropicLlm(…)): a bare string is resolved by ADK's own registry, which sends claude-… names to Vertex AI.

With AnthropicLlm instead:

from google.adk.models.anthropic_llm import AnthropicLlm

agent = Agent(name="assistant", model=AnthropicLlm(model="claude-sonnet-4.5"), instruction="Reply briefly.")

It reads ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY, and it too reaches every provider's models: the gateway translates Messages both ways. ADK's Claude class is for Claude on Vertex AI with Google credentials; use AnthropicLlm with the gateway.

Streaming

from google.adk.agents.run_config import RunConfig, StreamingMode

config = RunConfig(streaming_mode=StreamingMode.SSE)
async for event in runner.run_async(user_id="u1", session_id=session.id, new_message=message, run_config=config):
    if event.partial and event.content:
        print(event.content.parts[0].text, end="")

The Gemini class streams with :streamGenerateContent. A stream from GPT or Claude arrives as Gemini chunks. Vidai records the tokens and the cost either way.

Tool calls

Function tools (plain Python functions in tools=[…]) and agent hand-offs work on every provider the gateway translates to: ADK sends them as Gemini function declarations, and the model's function calls come back in the Gemini shape.

def get_weather(city: str) -> dict:
    """Weather for a city."""
    return {"city": city, "forecast": "sunny"}

agent = Agent(
    name="weather",
    model=Gemini(model="gpt-4o-mini", base_url="https://<your-gateway>"),
    instruction="Use the tool.",
    tools=[get_weather],
)

ADK's built-in tools that run inside Gemini (google_search, code execution) need a Gemini model. On another provider's model the call still succeeds: Google Search becomes that model's web search where it has one, otherwise it's dropped, and code execution is dropped; x-vidai-adapted names what was dropped (tools.googleSearch, tools.codeExecution).

Reading what the gateway did

ADK's events don't carry the response headers. Look the calls up in Request logs: filter Agent (or Key), Model or Path. Each call shows the model that answered, what translation or a guardrail changed, the routing rule or fallback that acted, and what it cost. To read the headers themselves (x-vidai-request-id, x-vidai-model), make the same call once with the google-genai SDK directly.

Errors

The gateway writes its errors in the Gemini format ({"error": {"code", "message", "status"}}), so the Gemini class raises the SDK's ClientError (4xx) or ServerError (5xx). The gateway's code is in the x-vidai-error-code header, which ADK doesn't pass on: take the status, then find the call in Request logs (filter Exact status or Why it failed).

Status Common gateway codes
401 missing_api_key, invalid_api_key, conflicting_auth_headers
403 api_key_disabled, model_not_allowed, denied_by_routing_rule, content_guardrail_blocked
404 model_not_found, endpoint_not_found
429 rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded
5xx ai_traffic_suspended, fallback_exhausted, upstream_timeout, upstream_unreachable

When the agent is suspended, or its key is switched off, its calls get api_key_disabled with a short reason (for example agent_suspended); treat the list of reasons as open-ended.

Model names

Use the names your organisation approved under Models in the Control room, within the agent's own list of models. GET /v1beta/models on the gateway lists exactly the models the key may call. An alias set by an admin works like any other name.

What goes through the gateway

Feature Through the gateway
Gemini class: generateContent, streaming, function tools, structured output Yes, to Gemini and Vertex AI models, and translated to OpenAI, Azure OpenAI and Anthropic models
AnthropicLlm class: Messages, streaming, tools Yes, to Anthropic models, and translated to the others
Live (bidirectional audio and video) agents No: the gateway doesn't carry Gemini's Live connection

Keep use_interactions_api off: it calls /v1beta/interactions, which the gateway doesn't serve. Live agents open a WebSocket to Gemini's BidiGenerateContent service, which the gateway doesn't carry either.

Check it works in a minute

export GOOGLE_GEMINI_BASE_URL="https://<your-gateway>"
export GOOGLE_API_KEY="vk_…"
export GOOGLE_GENAI_USE_VERTEXAI=false
export GOOGLE_GENAI_API_VERSION=v1beta   # google-genai 3.0 and later default to /v1
python -c "from google import genai; print(genai.Client().models.generate_content(model='gemini-3.5-flash', contents='ping').text)"

A short answer means the address and key are right; then run the agent above. ADK itself pins google-genai below 3.0, which still asks for /v1beta; a standalone pip install google-genai gets 3.0 or later, which asks for /v1 unless GOOGLE_GENAI_API_VERSION=v1beta is set. The calls show under the agent in Request logs within seconds.

Good to know

  • GOOGLE_GENAI_USE_VERTEXAI=true (or Google Cloud credentials in the environment) switches the SDK to Vertex AI and Google's own sign-in, which the gateway doesn't take; keep it false.
  • ADK retries only when you set Gemini(retry_options=…). A fallback chain may already have tried another model first; keep attempts low if you set it.
  • The gateway's own 429 has no Retry-After header; back off on your side.
  • An explicit base_url= wins over GOOGLE_GEMINI_BASE_URL. Leave the version out of it: the SDK adds /v1beta itself, so a trailing /v1 gives /v1/v1beta/….