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 inspect an agent and update the agent's context file. You can inspect an agent to test its ability to generate SQL queries from natural language questions. If a generated query is not accurate, you can update the agent's context.

Before you begin

Make sure that a data agent is already created and agent context is uploaded to the data agent. For more information, seeManage data agents in Cloud SQL Studio.

Inspect a data agent

To inspect a data agent, perform the following steps:

1. In the Google Cloud console, go to the Cloud SQL page.

   Go to Cloud SQL

2. Select an instance from the list.

3. In the navigation menu, clickCloud SQL Studio.

4. Sign in toStudio using Identity and Access Management (IAM) authentication.

5. In theExplorer pane, next toData Agents, clickView actions.

6. ClickInspect agent.

7. In the query editor, clickGenerate SQL to open theHelp me code panel.

8. Enter a natural language question to generate a SQL query, and clickGenerate.

9. Review the SQL query for accuracy.

Download and update context for a data agent

If you are not satisfied with the generated SQL query for a natural language question, download the existing agent context file. You can then review and update the query template, and reupload the updated context file to the agent.

To download and update context for a data agent, perform the following steps:

1. In theExplorer pane, next toData Agents, clickView actions.
2. ClickDownload agent context file.
3. Follow steps inBuild contexts using Gemini CLI to update context with additional query pairs.
4. In theExplorer pane, next to your data agent, clickView actions.
5. ClickEdit agent.
6. ClickBrowse in theUpload agent context file section, and select the updated agent context file.
7. ClickSave to update the agent context.

After you are satisfied with the accuracy of your responses, you can use theQueryData endpoint to connect your application to the data agent.

1. In the Google Cloud console, go to the Cloud SQL page.

   Go to Cloud SQL

2. Select an instance from the list.

3. In the navigation menu, clickCloud SQL Studio.

4. Sign in toStudio using Identity and Access Management (IAM) authentication.

5. In theExplorer pane, next toData Agents, clickView actions.

6. ClickEdit agent.

7. Note the context ID inAgent context ID. The agent context ID format is similar toprojects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates.

Connect the data agent to application

Set the agent context ID in theQueryData method call to provide authored context for database data sources such as AlloyDB, Spanner, Cloud SQL, and Cloud SQL for PostgreSQL. For more information, seeDefine data agent context for database data sources

After inspecting the data agent, you can reference the database data source in yourQueryData call.

ExampleQueryData request with authored context

The following example shows aQueryData request usingcloud_sql_reference database data source. Theagent_context_reference.context_set_id field is used to link to pre-authored context stored in the database.

{"parent":"projects/cloud-db-nl2sql/locations/us-central1","prompt":"How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.","context":{"datasource_references":[{"cloud_sql_reference":{"database_reference":{"engine":"MYSQL""project_id":"cloud-db-nl2sql","region":"us-central1","instance_id":"sqlgen-magic-primary","database_id":"financial"},"agent_context_reference":{"context_set_id":"projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates"}}}]},"generation_options":{"generate_query_result":true,"generate_natural_language_answer":true,"generate_disambiguation_question":true,"generate_explanation":true}}

The request body contains the following fields:

• prompt: The natural language question from the end user.
• context: Contains information about the data sources.
  • datasource_references: Specifies the data source type.
    • cloud_sql_reference: Required when querying the database. This field changes based on the database you are querying.
      • database_reference: Specifies information related to your database instance.
        • engine: The database engine. Set toMYSQL for Cloud SQL instances.
        • project_id: The project ID of the database instance.
        • region: The region of the Cloud SQL instance.
        • instance_id: The instance ID of the Cloud SQL instance.
        • database_id: The ID of the database.
      • agent_context_reference: Links to authored context in the database.
        • context_set_id: The complete agent context ID of the context stored in the database. For example,projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates.
• generationOptions: Configures the type of output to generate.
  • generate_query_result: Set to true to generate and return the query results.
  • generate_natural_language_answer: Optional. If set to true, generates a natural language answer.
  • generate_explanation: Optional. If set to true, generates an explanation of the SQL query.
  • generate_disambiguation_question: Optional. If set to true, generates disambiguation questions if the query is ambiguous.

ExampleQueryData Response

Here is an example of a successful response from aQueryData call:

{"generated_query":"-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region","intent_explanation":"The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.","query_result":{"columns":[{"name":"count"}],"rows":[{"values":[{"value":"2"}]}],"total_row_count":1},"natural_language_answer":"There are 2 accounts in Prague that are eligible for loans."}

What's next

• Learn more aboutdata agents.
• Learn how tobuild contexts using Gemini CLI
• Learn how toManage data agents in Cloud SQL Studio.