Skip to main content

Google ADK

Google Agent Development Kit builds Gemini agents in Python. Point its model at a Gemini LLM Registry entry and it runs under the gateway's policies, and an Agent Persona's MCP tools can be attached to the same agent.

Install​

pip install google-adk

Which setup do you need?​

What you getUse it when
LLM Registry entryThe model, governedYou only need model access
Agent PersonaThe model and the persona's MCP toolsYou want the agent to use tools as well

Which credentials you send depends on the entry's credential mode. If you haven't read which credentials your entry needs, start there.

caution

Configure the endpoint through client_kwargs, not http_options. Gemini(...) accepts an http_options argument without complaining and then ignores it, so your headers are dropped and requests go straight to Google. There is no error and no warning, and the gateway is bypassed entirely. Every snippet below sets http_options inside client_kwargs, which is the supported hook.

Connect to an LLM Registry entry​

Pick the credential mode on the entry's Provider Credential panel.

The gateway stores the Gemini credential, so no Gemini key leaves your machine. api_key carries your Agent Access Key instead.

from google.adk.agents import LlmAgent
from google.adk.models.google_llm import Gemini
from google.genai import types

BASE_URL = "https://<gateway-host>/llm/<url-prefix>"
AGENT_KEY = "<your-agent-access-key>"

agent = LlmAgent(
    name="gateway_agent",
    model=Gemini(
        model="<model-id>",
        base_url=BASE_URL,
        client_kwargs={
            "api_key": AGENT_KEY,
            "http_options": types.HttpOptions(base_url=BASE_URL),
        },
    ),
    instruction="Answer concisely.",
)

Connect through an Agent Persona​

ADK opens both connections from your own process, so the model and the tools are two independent legs. Each is configured separately on the same agent:

  • The model route, at https://<gateway-host>/p/<persona-id>/llm/<registry-entry-id>, on the Gemini model.
  • The tools socket, at https://<gateway-host>/p/<persona-id>/mcp, on an McpToolset.

One Agent Access Key covers both. The tools leg takes only X-Agent-Key and no provider credential, because the gateway attaches outbound authentication to the upstream API itself.

note

Two separate settings are in play here, and only one of them changes the code below.

  • The entry's credential mode — API Key or Passthrough — decides which credentials you send. This is what the tabs below switch between, exactly as on the route above.
  • The persona's own Inbound Authentication method — Interactive or Passthrough — decides how the persona identifies you. Either way an Agent Access Key is issued, and neither changes the configuration below.

Because a persona always identifies you by an Agent Access Key, the entry's third mode — Passthrough (No Agent Access Key) — has no tab here. It applies to the LLM Registry entry route only.

from google.adk.agents import LlmAgent
from google.adk.models.google_llm import Gemini
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.genai import types

BASE_URL = "https://<gateway-host>/p/<persona-id>/llm/<registry-entry-id>"
MCP_URL = "https://<gateway-host>/p/<persona-id>/mcp"
AGENT_KEY = "<your-agent-access-key>"

agent = LlmAgent(
    name="persona_agent",
    model=Gemini(
        model="<model-id>",
        base_url=BASE_URL,
        client_kwargs={
            "api_key": AGENT_KEY,
            "http_options": types.HttpOptions(base_url=BASE_URL),
        },
    ),
    instruction="Answer questions using the available tools.",
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url=MCP_URL,
                headers={"X-Agent-Key": AGENT_KEY},
            )
        )
    ],
)

Troubleshooting​

Calls succeed but never appear in gateway activity

Your headers were dropped. Check that http_options sits inside client_kwargs. Passing http_options directly to Gemini(...) is accepted silently and ignored, and the requests go to Google rather than through the gateway.

400 Missing or invalid Authorization header

The Gemini key was sent as x-goog-api-key. It needs to be an Authorization: Bearer header, as in the snippets above.

404 ... no longer available to new users

The model identifier isn't available on your account. gemini-flash-latest is a good one to test with. Confirm your choice with a real call rather than assuming from the Allowed Models list.

Requests fail with 400 "model is not specified"

The Gemini model exposes a use_interactions_api flag. Leave it off; that path does not currently work through the gateway.

Where to find each value​

PlaceholderWhere to find it
<gateway-host>Host from the entry's Overview tab, for example gw.aigateway.example.com
<url-prefix>The URL prefix field on the entry's Overview tab
<persona-id>The persona's ID on the Agent Persona page
<registry-entry-id>The LLM Registry entry's ID in the entry's URL
<model-id>A model identifier from the entry's Allowed Models list
<your-agent-access-key>Generate from the entry's Agent Access Keys step, or the persona's Connect flow. Plaintext is shown once.
<your-gemini-api-key>Your own Google Gemini API key, needed only in the passthrough modes

Tips​

  • Keep credentials out of your source. The snippets inline the values so the shape is clear, but read them from environment variables or a secret store in anything you commit.
  • Two URLs, two shapes. The model leg ends in /llm/<registry-entry-id>; the tools leg is the persona root plus /mcp. Copying one into the other is the most common setup mistake here.
  • Working in a different SDK? There are sibling guides for the Anthropic Python SDK and the OpenAI Python SDK.
Last updated on