Google Cloud Agent Registry¶

Supported in ADKPython v1.26.0Preview

The Agent Registry client library within Agent Development Kit (ADK) allows developers to discover, look up, and connect to AI Agents and MCP Servers cataloged within the Google Cloud Agent Registry. This enables dynamic composition of agent-based applications using governed components.

Use cases¶

Accelerated Development: Easily find and reuse existing agents and tools (MCP Servers) from the central catalog instead of rebuilding them.
Dynamic Integration: Discover agent and MCP Server endpoints at runtime, making applications more robust to changes in the environment.
Enhanced Governance: Utilize governed and verified components from the registry within your ADK applications.

Prerequisites¶

A Google Cloud project.
The Agent Registry API enabled in your Google Cloud project.
Authentication configured for your environment. You should log in using Application Default Credentials (gcloud auth application-default login).
Environment variables GOOGLE_CLOUD_PROJECT set to your project ID and GOOGLE_CLOUD_LOCATION set to the appropriate region (e.g., global, us-central1).
google-adk library installed.

For more information on connecting to Google Cloud from ADK agents, see Connect to Google Cloud and Agent Platform.

Installation¶

The Agent Registry integration is part of the core ADK library.

pip install google-adk

Required Dependencies¶

google.adk.integrations.agent_registry imports both the A2A SDK and the Agent Identity auth provider at module scope, so importing AgentRegistry raises ImportError on a core-only install. Install both the a2a and agent-identity extras:

pip install "google-adk[a2a,agent-identity]"

Use with Agent¶

The primary way to use the Agent Registry integration within an ADK agent is to dynamically fetch remote agents or toolsets using the AgentRegistry client.

from google.adk.agents.llm_agent import LlmAgent
from google.adk.integrations.agent_registry import AgentRegistry
import os

# 1. Initialization
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")

if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")

registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

# 2. Listing Resources
print("Listing Agents...")
agents_response = registry.list_agents()
for agent in agents_response.get("agents", []):
    print(f"  - {agent.get('name')} ({agent.get('displayName')})")

print("Listing MCP Servers...")
mcp_servers_response = registry.list_mcp_servers()
for server in mcp_servers_response.get("mcpServers", []):
    print(f"  - {server.get('name')} ({server.get('displayName')})")

# 3. Using a Remote A2A Agent
# Replace with the full resource name of your registered agent
agent_name = f"projects/{project_id}/locations/{location}/agents/YOUR_AGENT_ID"
my_remote_agent = registry.get_remote_a2a_agent(agent_name=agent_name)

# 4. Using an MCP Toolset
# Replace with the full resource name of your registered MCP server
mcp_server_name = f"projects/{project_id}/locations/{location}/mcpServers/YOUR_MCP_SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

# 5. Example Agent Composition
main_agent = LlmAgent(
    model="gemini-flash-latest", # Or your preferred model
    name="demo_agent",
    instruction="You can leverage registered tools and sub-agents.",
    tools=[my_mcp_toolset],
    sub_agents=[my_remote_agent],
)

Authentication for Google MCP Servers and Remote A2A Agents¶

Remote A2A Agents¶

If you are connecting to a Google A2A agent, you need to pass an httpx.AsyncClient configured with Google authentication headers to the get_remote_a2a_agent method.

Example:

import httpx
import google.auth
from google.auth.transport.requests import Request

class GoogleAuth(httpx.Auth):
    def __init__(self):
        self.creds, _ = google.auth.default()
    def auth_flow(self, request):
        if not self.creds.valid:
            self.creds.refresh(Request())
        request.headers["Authorization"] = f"Bearer {self.creds.token}"
        yield request

httpx_client = httpx.AsyncClient(auth=GoogleAuth(), timeout=httpx.Timeout(60.0))
remote_agent = registry.get_remote_a2a_agent(
    f"projects/{project_id}/locations/{location}/agents/YOUR_AGENT_ID",
    httpx_client=httpx_client,
)

Google MCP Servers¶

For Google MCP servers, authentication headers are automatically passed in. However, if automatic authentication is not working as expected, you can manually provide headers using the header_provider argument in the AgentRegistry constructor.

Example:

import google.auth
from google.auth.transport.requests import Request
from google.adk.integrations.agent_registry import AgentRegistry

def google_auth_header_provider(context):
    creds, _ = google.auth.default()
    if not creds.valid:
        creds.refresh(Request())
    return {"Authorization": f"Bearer {creds.token}"}

registry = AgentRegistry(
    project_id=project_id,
    location=location,
    header_provider=google_auth_header_provider
)

API Reference¶

The AgentRegistry class provides the following core methods:

list_mcp_servers(self, filter_str, page_size, page_token): Fetches a list of registered MCP Servers.
get_mcp_server(self, name): Retrieves detailed metadata of a specific MCP Server.
get_mcp_toolset(self, mcp_server_name): Constructs an ADK McpToolset instance from a registered MCP Server.
list_agents(self, filter_str, page_size, page_token): Fetches a list of registered A2A Agents.
get_agent_info(self, name): Retrieves detailed metadata of a specific A2A Agent.
get_remote_a2a_agent(self, agent_name): Creates an ADK RemoteA2aAgent instance for a registered A2A Agent.

Configuration Options¶

The AgentRegistry constructor accepts the following arguments:

project_id (str, required): The Google Cloud project ID.
location (str, required): The Google Cloud location/region, such as "global", "us-central1".
header_provider (Callable, optional): A callable that takes a ReadonlyContext and returns a dictionary of custom headers to be included in requests made by the McpToolset that get_mcp_toolset returns, to the target MCP server. This does not affect headers used to call the Agent Registry API itself, and it does not affect requests made by RemoteA2aAgent — for those, pass an authenticated httpx.AsyncClient to get_remote_a2a_agent, as shown in Remote A2A Agents.