Generative AI Google Brain

agents-agent-engine-tutorial-get-started-with-cloud-api-registry

3 min read

Get started with Cloud API Registry on Vertex AI Agent Engine

Source notebook

Repo path: agents/agent_engine/tutorial_get_started_with_cloud_api_registry.ipynb · Open on GitHub · intermediate

Builds and deploys an ADK BigQuery data analyst agent using Cloud API Registry on Vertex AI Agent Engine.

Summary

This notebook teaches how to discover MCP servers in Cloud API Registry, enable the BigQuery MCP server, and retrieve its tools for an ADK agent. It builds a Gemini-powered data analyst agent that explores BigQuery datasets, schemas, and SELECT query results through natural language. The workflow tests the agent locally with Runner and InMemorySessionService, then packages and deploys it to Vertex AI Agent Engine.

Key code patterns

Initialize Vertex AI and ADK

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = PROJECT_ID
os.environ["GOOGLE_CLOUD_LOCATION"] = LOCATION
vertexai.init(project=PROJECT_ID, location=LOCATION, staging_bucket=BUCKET_URI)

Configures ADK to use Vertex AI and sets the staging bucket used for Agent Engine deployment.

Load BigQuery MCP tools

header_provider = lambda context: {
    "x-goog-user-project": PROJECT_ID,
}
tool_registry = ApiRegistry(PROJECT_ID, header_provider=header_provider)
registry_tools = tool_registry.get_toolset(
    mcp_server_name=f"projects/{PROJECT_ID}/locations/global/mcpServers/google-bigquery.googleapis.com-mcp",
)

Retrieves the enabled BigQuery MCP toolset from Cloud API Registry with the required billing project header.

Create ADK agent with tools

data_analyst_agent = LlmAgent(
    model="gemini-2.5-flash",
    name="bigquery_data_analyst",
    instruction="Always use the BigQuery tools to fetch real data rather than making assumptions.",
    tools=[registry_tools],
)

Combines the Gemini model, a focused analyst instruction, and BigQuery MCP tools into one agent.

Test locally with Runner

session_service = InMemorySessionService()
runner = Runner(
    agent=data_analyst_agent,
    app_name="BigQueryDataAnalyst",
    session_service=session_service,
)

Lets the notebook test the agent locally before deploying it to managed infrastructure.

Deploy module agent

remote_app = agent_engines.create(
    display_name="bigquery-data-analyst",
    agent_engine=agent_engines.ModuleAgent(
        module_name="root_agent",
        agent_name="agent_app",
    ),
    requirements=["google-cloud-aiplatform[agent_engines,adk]>=1.101.0"],
    extra_packages=["root_agent.py", "startup_scripts/check_api_registry.sh"],
)

Deploys an importable ADK app module to Vertex AI Agent Engine with dependencies and setup files.

Models & APIs used

  • Models: gemini-2.5-flash
  • APIs / services: Vertex AI, Vertex AI Agent Engine, Cloud API Registry, API Hub, BigQuery, Cloud Storage, Google Cloud IAM
  • SDKs / libraries: google-cloud-aiplatform, vertexai, google-adk, google-genai

When to use this

Use this pattern when building a deployable ADK agent that needs governed access to BigQuery tools through Cloud API Registry MCP servers.

Gotchas & caveats

  • Requires a Google Cloud project with billing enabled.
  • The notebook installs google-cloud-aiplatform[agent_engines,adk]>=1.101.0 and may require a runtime restart.
  • Colab users must authenticate with google.colab.auth.authenticate_user().
  • The notebook recommends us-central1 for best availability.
  • Required APIs include apihub.googleapis.com, cloudapiregistry.googleapis.com, and aiplatform.googleapis.com.
  • The BigQuery MCP server must be enabled before the agent can use its tools.
  • The user and Agent Engine service account need MCP, Cloud API Registry, and BigQuery IAM roles.
  • ApiRegistry contains non-serializable state, so the deployed agent is defined in root_agent.py instead of pickling the local object.
  • Agent Engine deployment is stated to take about 10-15 minutes.
  • execute_sql only allows SELECT statements; INSERT, UPDATE, DELETE, and stored procedures are blocked.

Best practices

  • Discover MCP servers and tools before enabling and using them.
  • Verify the BigQuery MCP server shows as ENABLED after enabling it.
  • Use x-goog-user-project in the ApiRegistry header provider for BigQuery MCP access.
  • Explore datasets and table schemas before writing SQL queries.
  • Use BigQuery tools to fetch real data rather than making assumptions.
  • Test the agent locally before deploying to Vertex AI Agent Engine.
  • Use environment variables for PROJECT_ID and LOCATION in the deployment module.
  • Clean up the Agent Engine instance and Cloud Storage bucket to avoid ongoing charges.

Graph View

Backlinks