Generative AI Google Brain

gemini-agent-engine-tutorial-mcp-toolbox-for-databases

4 min read

Deploying an Agent with Agent Engine and MCP Toolbox for Databases

Source notebook

Repo path: gemini/agent-engine/tutorial_mcp_toolbox_for_databases.ipynb · Open on GitHub · advanced

Deploys a Gemini hotel-booking agent on Agent Engine using Cloud SQL, Cloud Run Toolbox, and LangGraph.

Summary

This notebook teaches how to create a Cloud SQL PostgreSQL hotel table, expose database operations through MCP Toolbox for Databases on Cloud Run, and bind those tools to a Gemini ReAct agent built with LangGraph and LangChain. It tests the agent locally, then deploys a custom HotelBookingAgent class to Vertex AI Agent Engine with pinned runtime requirements and a Cloud Storage staging bucket. The workflow includes IAM setup, API enabling, secret-backed Toolbox configuration, remote querying, and resource cleanup.

Key code patterns

Cloud SQL connection

engine = await PostgresEngine.afrom_instance(
    PROJECT_ID,
    REGION,
    INSTANCE,
    database=DATABASE,
    user=USER,
    password=PASSWORD,
)

Creates the async PostgreSQL connection used to create tables, insert hotel data, and grant database access.

Toolbox SQL tools

tools:
  search-hotels-by-location:
    kind: postgres-sql
    source: my-cloud-sql-source
    parameters:
      - name: location
        type: string
    statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';

Turns parameterized PostgreSQL statements into callable tools for the hotel-booking agent.

Cloud Run Toolbox deploy

!gcloud run deploy toolbox \
  --image {IMAGE} \
  --service-account toolbox-identity \
  --region us-central1 \
  --set-secrets /app/tools.yaml=tools:latest \
  --args=--tools_file=/app/tools.yaml,--address=0.0.0.0,--port=8080 \
  --allow-unauthenticated

Deploys the Toolbox server remotely and mounts its tool configuration from Secret Manager.

LangGraph ReAct agent

model = ChatVertexAI(model_name=self.model, project=self.project_id)
client = ToolboxClient(self.toolbox_endpoint)
tools = client.load_toolset()
self.runnable = create_react_agent(
    model, tools, checkpointer=MemorySaver()
)

Binds Gemini to the remote Toolbox tools and creates the LangGraph ReAct reasoning loop.

Agent Engine deployment

vertexai.init(project=PROJECT_ID, location=REGION, staging_bucket=STAGING_BUCKET)
remote_agent = agent_engines.create(
    HotelBookingAgent(...),
    requirements=[
        "toolbox-langchain==0.1.0",
        "google-cloud-aiplatform[agent_engines,langchain]==1.87.0",
    ],
    display_name="HotelBookingAgent",
)

Packages the custom agent class and runtime dependencies for deployment to Vertex AI Agent Engine.

Models & APIs used

  • Models: gemini-2.0-flash
  • APIs / services: Vertex AI, Agent Engine, Cloud SQL for PostgreSQL, Cloud SQL Admin API, Cloud Run, Cloud Storage, Secret Manager, Cloud Build, Artifact Registry, IAM, Service Networking
  • SDKs / libraries: google-cloud-aiplatform, vertexai, toolbox-langchain, langchain-google-cloud-sql-pg, langchain-google-vertexai, langgraph, sqlalchemy

When to use this

Use this pattern when a Gemini agent needs to safely query or mutate a Cloud SQL PostgreSQL database through remote, deployable tools.

Gotchas & caveats

  • The tutorial states that only us-central1 is supported and hardcodes several resources to us-central1.
  • It requires billing, enabled Google Cloud APIs, and broad setup permissions such as Owner or the listed service account, Secret Manager, and Cloud Run roles.
  • The Cloud SQL instance is created with public IP enabled and cloudsql.iam_authentication=On, while the setup also uses the postgres password for onboarding.
  • Local and remote agent tests mutate the remote hotels table, so repeat runs require repopulating the data.
  • The prose says to call repopulate_date(), but the defined function is named repopulate_data().
  • The shown repopulate_data function uses async with inside a non-async def, so it would need to be made async or wrapped to run as written.
  • The Toolbox Cloud Run service is deployed with allUsers invoker access and —allow-unauthenticated.
  • The Agent Engine deployment pins toolbox-langchain0.1.0 and google-cloud-aiplatform[agent_engines,langchain]1.87.0.

Best practices

  • Test the HotelBookingAgent locally before deploying it to Agent Engine.
  • Use Secret Manager to provide the Toolbox tools file to Cloud Run.
  • Grant service accounts explicit roles for Cloud SQL, Vertex AI, Secret Manager, and service usage.
  • Use parameterized SQL statements in Toolbox tool definitions.
  • Initialize Vertex AI with a Cloud Storage staging bucket before Agent Engine deployment.
  • Clean up Agent Engine, Cloud Run, and Cloud SQL resources after the tutorial to avoid charges.

Graph View

Backlinks