Google Cloud Agent Registry¶
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_PROJECTset to your project ID andGOOGLE_CLOUD_LOCATIONset to the appropriate region (e.g.,global,us-central1). - ADK installed for your language, as described in Installation.
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.
Required dependencies¶
The google.adk.integrations.agent_registry module 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:
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 Agent Registry 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],
)
package main
import (
"cmp"
"context"
"fmt"
"log"
"os"
"google.golang.org/genai"
"google.golang.org/adk/v2/agent"
"google.golang.org/adk/v2/agent/llmagent"
"google.golang.org/adk/v2/agentregistry"
"google.golang.org/adk/v2/cmd/launcher"
"google.golang.org/adk/v2/cmd/launcher/full"
"google.golang.org/adk/v2/model/gemini"
"google.golang.org/adk/v2/tool"
)
func main() {
ctx := context.Background()
// 1. Initialization
projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
if projectID == "" {
log.Fatal("GOOGLE_CLOUD_PROJECT environment variable not set.")
}
location := cmp.Or(os.Getenv("GOOGLE_CLOUD_LOCATION"), "global")
registry, err := agentregistry.New(ctx, agentregistry.Config{
ProjectID: projectID,
Location: location,
})
if err != nil {
log.Fatalf("Failed to create the registry client: %v", err)
}
// 2. Listing Resources. The All* iterators fetch pages on demand and
// report a failed page fetch as a single (nil, error).
fmt.Println("Listing Agents...")
for a, err := range registry.AllAgents(ctx) {
if err != nil {
log.Fatalf("Failed to list agents: %v", err)
}
fmt.Printf(" - %s (%s)\n", a.Name, a.DisplayName)
}
fmt.Println("Listing MCP Servers...")
for s, err := range registry.AllMCPServers(ctx) {
if err != nil {
log.Fatalf("Failed to list MCP servers: %v", err)
}
fmt.Printf(" - %s (%s)\n", s.Name, s.DisplayName)
}
// 3. Using a Remote A2A Agent
// Replace with the full resource name of your registered agent
agentName := fmt.Sprintf("projects/%s/locations/%s/agents/YOUR_AGENT_ID", projectID, location)
myRemoteAgent, err := registry.RemoteAgent(ctx, agentName)
if err != nil {
log.Fatalf("Failed to resolve the remote agent: %v", err)
}
// 4. Using an MCP Toolset
// Replace with the full resource name of your registered MCP server
mcpServerName := fmt.Sprintf("projects/%s/locations/%s/mcpServers/YOUR_MCP_SERVER_ID", projectID, location)
myMCPToolset, err := registry.MCPToolset(ctx, mcpServerName)
if err != nil {
log.Fatalf("Failed to connect to the MCP server: %v", err)
}
// 5. Example Agent Composition
model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{})
if err != nil {
log.Fatalf("Failed to create the model: %v", err)
}
rootAgent, err := llmagent.New(llmagent.Config{
Name: "demo_agent",
Model: model,
Instruction: "You can leverage registered tools and sub-agents.",
Toolsets: []tool.Toolset{myMCPToolset},
SubAgents: []agent.Agent{myRemoteAgent},
})
if err != nil {
log.Fatalf("Failed to create the agent: %v", err)
}
config := &launcher.Config{AgentLoader: agent.NewSingleLoader(rootAgent)}
l := full.NewLauncher()
if err := l.Execute(ctx, config, os.Args[1:]); err != nil {
log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
}
}
Authentication for Google MCP Servers and Remote A2A Agents¶
Remote A2A Agents¶
Calls to a remote A2A agent are not authenticated for you. If you are connecting to a Google A2A agent, supply an authenticated HTTP client when you create the remote agent.
Pass an httpx.AsyncClient configured with Google authentication headers to
the get_remote_a2a_agent method.
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,
)
Pass an authenticated *http.Client with WithA2AHTTPClient, or static
headers with WithA2AHeaders.
import (
"golang.org/x/oauth2/google"
"google.golang.org/adk/v2/agentregistry"
)
httpClient, err := google.DefaultClient(ctx, "https://www.googleapis.com/auth/cloud-platform")
if err != nil {
log.Fatalf("Failed to load Application Default Credentials: %v", err)
}
remoteAgent, err := registry.RemoteAgent(ctx, agentName,
agentregistry.WithA2AHTTPClient(httpClient),
)
Set any timeout on the client's Transport rather than with
http.Client.Timeout, which applies to the whole request and would truncate
a streaming response.
Google MCP Servers¶
For Google MCP servers, authentication headers are automatically passed in.
If automatic authentication is not working as expected, you can manually
provide headers using the header_provider argument in the AgentRegistry
constructor.
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
)
Requests to a *.googleapis.com endpoint reuse the credentials of the
registry client itself. For any other endpoint, or to override that default,
pass WithMCPHTTPClient and WithMCPHeaders.
toolset, err := registry.MCPToolset(ctx, mcpServerName,
agentregistry.WithMCPHTTPClient(httpClient),
agentregistry.WithMCPHeaders(map[string]string{"X-Tenant-Id": "acme"}),
)
Headers set this way are applied to every request the toolset sends to the MCP server. They do not affect calls to the Agent Registry API itself.
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.
The agentregistry.Client type exposes three discovery methods per resource
kind: List* returns a single page, Get* returns one resource by its full
resource name, and All* returns an iter.Seq2 that fetches pages on demand.
ListAgents(ctx, opts ...ListOption),GetAgent(ctx, name),AllAgents(ctx, opts ...ListOption): registered A2A agents.ListMCPServers(ctx, opts ...ListOption),GetMCPServer(ctx, name),AllMCPServers(ctx, opts ...ListOption): registered MCP servers.ListEndpoints(ctx, opts ...ListOption),GetEndpoint(ctx, name),AllEndpoints(ctx, opts ...ListOption): registered model endpoints.RemoteAgent(ctx, name, opts ...RemoteAgentOption): resolves a registered A2A agent into anagent.Agentusable as a sub-agent.MCPToolset(ctx, name, opts ...MCPToolsetOption): resolves a registered MCP server into atool.Toolset.
The list options are WithFilter, WithPageSize, and WithPageToken. The
All* iterators manage the page token themselves. A non-2xx response from the
Agent Registry API is returned as an *agentregistry.APIError carrying the
StatusCode and the response Body.
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 thatget_mcp_toolsetreturns, to the target MCP server. These headers do not affect calls to the Agent Registry API itself, and they do not affect requests made by RemoteA2aAgent. For those requests, pass an authenticatedhttpx.AsyncClienttoget_remote_a2a_agent, as shown in Remote A2A Agents.
The agentregistry.New constructor takes a Config struct:
ProjectID(string, required): The Google Cloud project ID.Location(string, required): The Google Cloud location/region, such as "global", "us-central1".HTTPClient(*http.Client, optional): The client used for Agent Registry API calls. When it is nil, ADK builds one from Application Default Credentials and resolves the endpoint, including mTLS, fromGOOGLE_API_USE_MTLS_ENDPOINTandGOOGLE_API_USE_CLIENT_CERTIFICATE. This client is also reused for McpToolset traffic to*.googleapis.comendpoints, but never for A2A traffic.
Egress to the resolved endpoints is configured per call instead:
WithA2AHTTPClient and WithA2AHeaders on RemoteAgent,
WithMCPHTTPClient and WithMCPHeaders on MCPToolset.