データエージェントを検査して呼び出す

MySQL | PostgreSQL | SQL Server

このドキュメントでは、エージェントを検査する方法と、エージェントのコンテキストファイルを更新する方法を説明します。エージェントを検査して、自然言語による質問から SQL クエリを生成する能力をテストできます。生成されたクエリが正確でない場合は、エージェントのコンテキストを更新できます。

データエージェントについては、データエージェントの概要をご覧ください。

始める前に

データエージェントがすでに作成されていて、エージェントコンテキストがデータエージェントにアップロード済みであることを確認します。詳細については、Cloud SQL Studio でデータエージェントを管理するをご覧ください。

データエージェントを検査する

データエージェントを検査する手順は次のとおりです。

Google Cloud コンソールで、[Cloud SQL] ページに移動します。

Cloud SQL に移動
リストからインスタンスを選択します。
ナビゲーションメニューで [Cloud SQL Studio] をクリックします。
Identity and Access Management（IAM）認証を使用して Studio にログインします。
[エクスプローラ] ペインで、[データエージェント] の横にある [アクションを表示] をクリックします。
[エージェントを検査] をクリックします。
クエリエディタで、[SQL を生成] をクリックして [コーディングサポート] パネルを開きます。
SQL クエリを作成するための自然言語による質問を入力し、[生成] をクリックします。
SQL クエリの精度を確認します。

データエージェントのコンテキストをダウンロードして更新する

自然言語による質問に対して生成された SQL クエリに満足できない場合は、既存のエージェントコンテキストファイルをダウンロードします。クエリテンプレートを確認して更新し、更新後のコンテキストファイルをエージェントに再びアップロードできます。

データエージェントのコンテキストをダウンロードして更新する手順は次のとおりです。

[エクスプローラ] ペインで、[データエージェント] の横にある [アクションを表示] をクリックします。
[エージェントコンテキストファイルをダウンロード] をクリックします。
Gemini CLI を使用してコンテキストを作成するの手順に沿ってクエリのペアを追加し、コンテキストを更新します。
[エクスプローラ] ペインで、データエージェントの横にある [アクションを表示] をクリックします。
[エージェントを編集] をクリックします。
[エージェントコンテキストファイルのアップロード] セクションで [参照] をクリックし、更新したエージェントコンテキストファイルを選択します。
[保存] をクリックして、エージェントのコンテキストを更新します。

回答の精度が満足できるものになったら、QueryData エンドポイントを使用してアプリケーションをデータエージェントに接続できます。

エージェントコンテキスト ID を確認する

データアプリケーションをデータエージェントに接続するには、エージェントコンテキスト ID が必要です。

Google Cloud コンソールで、[Cloud SQL] ページに移動します。

Cloud SQL に移動
リストからインスタンスを選択します。
ナビゲーションメニューで [Cloud SQL Studio] をクリックします。
Identity and Access Management（IAM）認証を使用して Studio にログインします。
[エクスプローラ] ペインで、[データエージェント] の横にある [アクションを表示] をクリックします。
[エージェントを編集] をクリックします。
[エージェントのコンテキスト ID] に示されているコンテキスト ID をメモします。エージェントコンテキスト ID の形式は projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates のようになっています。

データエージェントをアプリケーションに接続する

QueryData メソッド呼び出しでエージェントコンテキスト ID を設定して、AlloyDB、Spanner、Cloud SQL、Cloud SQL for PostgreSQL などのデータベースをデータソースとして作成されたコンテキストを提供します。詳細については、データベースをデータソースとしたエージェントコンテキストを定義するをご覧ください。

データエージェントを検査したら、QueryData 呼び出しでデータベースのデータソースを参照できます。

作成されたコンテキストを含む `QueryData` リクエストの例

以下の例は、cloud_sql_reference データベースをデータソースとして使用した QueryData リクエストを示しています。データベースに保存されている事前作成済みのコンテキストにリンクするために、agent_context_reference.context_set_id フィールドを使用しています。

{
  "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": "POSTGRESQL"
            "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
  }
}

リクエスト本文には次のフィールドが含まれます。

prompt: エンドユーザーからの自然言語による質問。
context: データソースに関する情報を入力します。
- datasource_references: データソースのタイプを指定します。
  - cloud_sql_reference: データベースのクエリを実行する際に必須となります。このフィールドは、クエリの実行対象とするデータベースによって異なります。
    - database_reference: データベースインスタンスに関する情報を指定します。
      - engine: データベースエンジン。Cloud SQL インスタンスの場合は POSTGRESQL に設定します。
      - project_id: データベースインスタンスのプロジェクト ID。
      - region: Cloud SQL インスタンスのリージョン。
      - instance_id: Cloud SQL インスタンスのインスタンス ID。
      - database_id: データベースの ID。
    - agent_context_reference: データベースに保存されている作成済みコンテキストへのリンク。
      - context_set_id: データベースに保存されているコンテキストの完全なエージェントコンテキスト ID。例: projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates
generationOptions: 生成する出力のタイプを構成します。
- generate_query_result: クエリ結果を生成して取得する場合は true に設定します。
- generate_natural_language_answer: 省略可。true に設定すると、自然言語による回答が生成されます。
- generate_explanation: 省略可。true に設定すると、SQL クエリの説明が生成されます。
- generate_disambiguation_question: 省略可。true に設定すると、クエリがあいまいな場合はクエリを明確にするための質問が生成されます。

`QueryData` の回答の例

以下は、QueryData 呼び出しによる回答の成功例です。

{
  "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."
}

次のステップ

データエージェントの詳細を確認する。
Gemini CLI を使用してコンテキストを作成する方法を確認する。
Cloud SQL Studio でデータエージェントを管理する方法を確認する。

データ エージェントを検査して呼び出す コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

データ エージェントを検査する

データ エージェントのコンテキストをダウンロードして更新する

エージェント コンテキスト ID を確認する

データ エージェントをアプリケーションに接続する

作成されたコンテキストを含む QueryData リクエストの例

QueryData の回答の例