This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms, and theAdditional Terms for Generative AI Preview Products. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

For information about access to this release, see the access request page.

This document describes how to use the Gemini CLI and the MCP toolbox to build agent context files. These files contain templates and facets that provide context for generating SQL queries from natural language. You will also use the DB Context Enrichment MCP Server.

To build agent context, perform the following high-level steps:

• Prepare your environment
• Generate targeted templates
• Generate targeted facets
• Optional. Generate bulk templates

Before you begin

Complete the following prerequisites before creating an agent.

Prepare a Spanner instance

• Make sure that a Spanner instance is available. For more information, seeCreate an instance.
• Populate the database with the data and schema that the end user wants to access.

Required roles and permissions

• Add an IAM user or service account to the cluster. For more information, seeApply IAM roles.
• Grant thespanner.databaseReader roles to the IAM user at the project level. For more information, seeAdd IAM policy binding for a project.
• Grant roles and permissions to the IAM user at the project-level for the required databases.

Prepare your environment

You can build agent context files from any any local development environment or IDE. To prepare the environment, perform the following steps:

• Install Gemini CLI
• Install and setup MCP toolbox
• Install and setup the DB Context Enrichment MCP Server

Install Gemini CLI

To install Gemini CLI, seeGet Started with Gemini CLI. Make sure that you install Gemini CLI in a separate directory, which is also used to install theMCP toolbox and theDB Context Enrichment MCP Server.

Install and setup MCP toolbox

1. In the same directory where you installed Gemini CLI, install the MCP Toolbox Gemini CLI extension:

   geminiextensionsinstallhttps://github.com/gemini-cli-extensions/mcp-toolbox

2. Create atools.yaml configuration file in the same directory where you installed the MCP toolbox for configuring the database connection:

   sources:my-spanner-source:kind:spannerproject:PROJECT_IDinstance:INSTANCE_IDdatabase:DATABASE_ID

   Replace the following:

   • PROJECT_ID: Your Google Cloud project ID.
   • INSTANCE_ID: The ID of your Spanner instance.
   • DATABASE_ID: The name of the database to connect to.

3. Verify that thetools.yaml file is configured correctly:

   ./toolbox--tools-file"tools.yaml"

Install DB Context Enrichment MCP Server

The DB Context Enrichment MCP Server provides a guided, interactive workflow to generate structured NL2SQL templates from your database schemas. It relies on the MCP Toolbox extension for database connectivity. For more information about installing the DB Context Enrichment MCP Server, seeDB Context Enrichment MCP Server.

To install the DB Context Enrichment MCP Server, do the following:

1. In the same directory where you installed Gemini CLI, installuv Python package installer.

   pipinstall--userpipxpipxensurepathpipxinstalluv

2. Install the DB Context Enrichment MCP Server.

   geminiextensionsinstallhttps://github.com/GoogleCloudPlatform/db-context-enrichment

The server uses Gemini API for generation. Make sure that you export your API key as an environment variable. For more information about how to find your API key, seeUsing Gemini API keys.

To export the Gemini API key, run the following command:

exportGEMINI_API_KEY="YOUR_API_KEY"

ReplaceYOUR_API_KEY with your Gemini API key.

Generate targeted templates

If you want to add a specific query pair as a query template to the agent context, then you can use the/generate_targeted_templates command. For more information about templates, seeData agents overview.

To add a query template to the agent context, perform the following steps:

1. In the same directory where you installed Gemini CLI, start Gemini:

   gemini

2. Complete the Gemini CLI Authentication Setup.

3. Verify that the MCP toolbox and the database enrichment extension are ready to use:

   /mcplist

4. Run the/generate_targeted_templates command:

   /generate_targeted_templates

5. Enter the natural language query that you want to add to the query template.

6. Enter the corresponding SQL query to the query template.

7. Review the generated query template. You can either save the query template as an agent context file or append it to an existing context file.

The agent context file similar tomy-cluster-psc-primary_postgres_templates_20251104111122.json is saved in the directory where you ran the commands.

For more information about the context file and the query template, seeAgent context.

Generate targeted facets

If you want to add a specific query pair as a facet to the agent context file, then you can use the/generate_targeted_fragments command. For more information about facets, seeData agents overview.

To add a facet to the agent context, perform the following steps:

1. Run the/generate_targeted_fragments command:

   /generate_targeted_fragments

2. Enter the natural language query that you want to add to the query template.

3. Enter the corresponding SQL query to the query template.

4. Review the generated facet. You can either save the facet to an agent context file or append it to an existing context file.

The agent context file similar tomy-cluster-psc-primary_postgres_templates_20251104111122.json is saved in the directory where you ran the commands.

For more information about the context file and facets, seeAgent context.

Optional: Generate bulk templates

If you want to auto-generate the agent context file based on your database schema and data, then you can use the/generate_bulk_templates command.

To auto-generate bulk templates, perform the following steps:

1. Run the/generate_bulk_templates command:

   /generate_bulk_templates

2. Based on your database schema, the template-based SQL generation takes you through a series of questions related to verifying the database information and granting permissions to access the database schema.

3. Review the generated query template. You can either approve the template or update a query pair that you want to revise.

4. Enter the natural language query that you want to add to the query template.

5. Enter the corresponding SQL query to the query template.

6. Review the generated query template. You can either save the query template as an agent context file or append it to an existing context file.

7. After you approve the query template, you can either create a new template file or append the query pairs to an existing template file. The query template is saved as a JSON file in your local directory.

The agent context file similar tomy-cluster-psc-primary_postgres_templates_20251104111122.json is saved in the directory where you ran the commands.

For more information about the agent context file, seeAgent context.

What's next

• Learn more aboutdata agents.
• Learn how tocreate or delete a data agent in Spanner Studio.
• Learn how toinspect and call a data agent.