mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
George Weale
d9e930e823
* docs(integrations): fix unresolvable imports and stale API claims * docs: apply style pass and drop out-of-scope import cleanup * docs(integrations): address review feedback on gcs, cloud-trace, reflect-and-retry Restore the gcs_ tool name prefixes in the GCS tool tables, since both toolsets set tool_name_prefix="gcs" and the tables list names as the model sees them. Use the current Agent Platform SDK name in cloud-trace prose, make the reflect-and-retry failure description language-neutral for Python and Go, and drop the redundant re-export clause. * docs(gcs): note that tool_filter matches unprefixed tool names Tool filtering runs inside get_tools() against the unprefixed name, and get_tools_with_prefix() applies the gcs_ prefix afterwards, so the names in the tables are not the names tool_filter expects. * docs(computer-use): drop unused Gemini and override imports --------- Co-authored-by: Kristopher Overholt <koverholt@google.com>
185 lines
8.1 KiB
Markdown
185 lines
8.1 KiB
Markdown
---
|
|
catalog_title: Google Cloud API Registry
|
|
catalog_description: Connect with Google Cloud services as MCP tools
|
|
catalog_icon: /integrations/assets/developer-tools-color.svg
|
|
catalog_tags: ["google", "mcp", "connectors"]
|
|
---
|
|
|
|
# Google Cloud API Registry tool for ADK
|
|
|
|
<div class="language-support-tag">
|
|
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.20.0</span><span class="lst-preview">Preview</span>
|
|
</div>
|
|
|
|
The Google Cloud API Registry connector tool for Agent Development Kit (ADK)
|
|
lets you access a wide range of Google Cloud services for your agents as Model
|
|
Context Protocol (MCP) servers through the
|
|
[Google Cloud API Registry](https://docs.cloud.google.com/api-registry/docs/overview).
|
|
You can configure this tool to connect your agent to your Google Cloud projects
|
|
and dynamically access Cloud services enabled for that project.
|
|
|
|
!!! example "Preview release"
|
|
The Google Cloud API Registry feature is a Preview release. For
|
|
more information, see the
|
|
[launch stage descriptions](https://cloud.google.com/products#product-launch-stages).
|
|
|
|
## Prerequisites
|
|
|
|
Before using the API Registry with your agent, you need to ensure the following:
|
|
|
|
- **Google Cloud project:** Configure your agent to access AI models using an
|
|
existing Google Cloud project.
|
|
|
|
- **API Registry access:** The environment where your agent runs needs Google
|
|
Cloud [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/provide-credentials-adc)
|
|
with the `apiregistry.viewer` role to list available MCP servers.
|
|
|
|
- **Cloud APIs:** In your Google Cloud project, enable the
|
|
*cloudapiregistry.googleapis.com* and *apihub.googleapis.com* Google Cloud
|
|
APIs.
|
|
|
|
- **MCP Server and Tool access:** Make sure you enable the MCP Servers in the
|
|
API Registry for the Google Cloud services in your Cloud Project that you
|
|
want access with your agent. You can enable this in the Cloud Console or
|
|
use a gcloud command such as:
|
|
`gcloud beta api-registry mcp enable bigquery.googleapis.com --project={PROJECT_ID}`.
|
|
The credentials used by the agent must have permissions to access the MCP
|
|
server and the underlying services used by the tools. For example, to use
|
|
BigQuery tools, the service account needs BigQuery IAM roles like
|
|
`bigquery.dataViewer` and `bigquery.jobUser`. For more information about
|
|
required permissions, see [Authentication and access](#auth).
|
|
|
|
You can check what MCP servers are enabled with API Registry using the following
|
|
gcloud command:
|
|
|
|
```console
|
|
gcloud beta api-registry mcp servers list --project={PROJECT_ID}.
|
|
```
|
|
|
|
## Use with agent
|
|
|
|
When configuring the API Registry connector tool with an agent, you first
|
|
initialize the ***ApiRegistry*** class to establish a connection with Cloud
|
|
services, and then use the `get_toolset()` function to retrieve a toolset for a
|
|
specific MCP server registered in the API Registry. The following code example
|
|
demonstrates how to create an agent that uses tools from an MCP server listed in
|
|
API Registry. This agent is designed to interact with BigQuery:
|
|
|
|
```python
|
|
import os
|
|
from google.adk.agents.llm_agent import LlmAgent
|
|
from google.adk.integrations.api_registry import ApiRegistry
|
|
|
|
# Configure with your Google Cloud Project ID and registered MCP server name
|
|
PROJECT_ID = "your-google-cloud-project-id"
|
|
MCP_SERVER_NAME = "projects/your-google-cloud-project-id/locations/global/mcpServers/your-mcp-server-name"
|
|
|
|
# Example header provider for BigQuery, a project header is required.
|
|
def header_provider(context):
|
|
return {"x-goog-user-project": PROJECT_ID}
|
|
|
|
# Initialize ApiRegistry
|
|
api_registry = ApiRegistry(
|
|
api_registry_project_id=PROJECT_ID,
|
|
header_provider=header_provider
|
|
)
|
|
|
|
# Get the toolset for the specific MCP server
|
|
registry_tools = api_registry.get_toolset(
|
|
mcp_server_name=MCP_SERVER_NAME,
|
|
# Optionally filter tools:
|
|
#tool_filter=["list_datasets", "run_query"]
|
|
)
|
|
|
|
# Create an agent with the tools
|
|
root_agent = LlmAgent(
|
|
model="gemini-flash-latest", # Or your preferred model
|
|
name="bigquery_assistant",
|
|
instruction="""
|
|
Help user access their BigQuery data using the available tools.
|
|
""",
|
|
tools=[registry_tools],
|
|
)
|
|
```
|
|
|
|
For the complete code for this example, see the
|
|
[api_registry_agent](https://github.com/google/adk-python/tree/main/contributing/samples/integrations/api_registry_agent/)
|
|
sample. For information on the configuration options, see
|
|
[Configuration](#configuration).
|
|
For information on the authentication for this tool, see
|
|
[Authentication and access](#auth).
|
|
|
|
## Authentication and access {#auth}
|
|
|
|
Using the API Registry with your agent requires authentication for the services
|
|
the agent accesses. By default the tool uses Google Cloud
|
|
[Application Default Credentials](https://docs.cloud.google.com/docs/authentication/provide-credentials-adc)
|
|
for authentication. When using this tool make sure your agent has the following
|
|
permissions and access:
|
|
|
|
- **API Registry access:** The `ApiRegistry` class uses Application Default
|
|
Credentials (`google.auth.default()`) to authenticate requests to the Google
|
|
Cloud API Registry to list the available MCP servers. Ensure the environment
|
|
where the agent runs has credentials with the necessary permissions to view
|
|
the API Registry resources, such as `apiregistry.viewer`.
|
|
|
|
- **MCP Server and Tool access:** The `McpToolset` returned by `get_toolset`
|
|
also uses the Google Cloud Application Default Credentials by default to
|
|
authenticate calls to the actual MCP server endpoint. The credentials used
|
|
must have the necessary permissions for both:
|
|
1. Accessing the MCP server itself.
|
|
1. Utilizing the underlying services and resources that the tools interact
|
|
with.
|
|
|
|
- **MCP Tool user role:** Allow the account used by your agent to call MCP
|
|
tools through the API registry by granting the MCP tool user role:
|
|
`gcloud projects add-iam-policy-binding {PROJECT_ID} --member={member}
|
|
--role="roles/mcp.toolUser"`
|
|
|
|
For example, when using MCP server tools that interact with BigQuery, the
|
|
account associated with the credentials, such as a service account, must be
|
|
granted appropriate BigQuery IAM roles, such as `bigquery.dataViewer` or
|
|
`bigquery.jobUser`, within your Google Cloud project to access datasets and run
|
|
queries. In the case of the bigquery MCP server, a `"x-goog-user-project":
|
|
PROJECT_ID` header is required to use its tools Additional headers for
|
|
authentication or project context can be injected via the `header_provider`
|
|
argument in the `ApiRegistry` constructor.
|
|
|
|
## Configuration {#configuration}
|
|
|
|
The ***APIRegistry*** object has the following configuration options:
|
|
|
|
- **`api_registry_project_id`** (str): The Google Cloud Project ID where the
|
|
API Registry is located.
|
|
|
|
- **`location`** (str, optional): The location of the API Registry resources.
|
|
Defaults to `"global"`.
|
|
|
|
- **`header_provider`** (Callable, optional): A function that takes the call
|
|
context and returns a dictionary of additional HTTP headers to be sent with
|
|
requests to the MCP server. This is often used for dynamic authentication or
|
|
project-specific headers.
|
|
|
|
The `get_toolset()` function has the following configuration options:
|
|
|
|
- **`mcp_server_name`** (str): The full name of the registered MCP server from
|
|
which to load tools, for example:
|
|
`projects/my-project/locations/global/mcpServers/my-server`.
|
|
|
|
- **`tool_filter`** (Union[ToolPredicate, List[str]], optional): Specifies
|
|
which tools to include in the toolset.
|
|
- If a list of strings, only tools with names in the list are included.
|
|
- If a `ToolPredicate` function, the function is called for each tool, and
|
|
only tools for which it returns `True` are included.
|
|
- If `None`, all tools from the MCP server are included.
|
|
|
|
- **`tool_name_prefix`** (str, optional): A prefix to add to the name of each
|
|
tool in the resulting toolset.
|
|
|
|
## Additional resources
|
|
|
|
- [api_registry_agent](https://github.com/google/adk-python/tree/main/contributing/samples/integrations/api_registry_agent/)
|
|
ADK code sample
|
|
- [Google Cloud API Registry](https://docs.cloud.google.com/api-registry/docs/overview)
|
|
documentation
|