Gemini CLI を使用してコンテキストを作成する

このドキュメントでは、Gemini CLI と MCP ツールボックスを使用してエージェント コンテキスト ファイルを作成する方法を説明します。これらのファイルには、自然言語から SQL クエリを生成するためのコンテキストを提供するテンプレートとファセットが含まれています。また、DB コンテキスト拡充 MCP サーバーも使用します。

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

エージェント コンテキストを構築する大まかな手順は次のとおりです。

  • 環境を準備する
  • ターゲットを絞ったテンプレートを生成する
  • ターゲットを絞ったファセットを生成する
  • 省略可。テンプレートを一括生成する

始める前に

エージェントを作成する前に、次の前提条件を満たす必要があります。

Cloud SQL インスタンスを準備する

  • 既存の Cloud SQL インスタンスにアクセスできることを確認するか、新しいインスタンスを作成します。 詳細については、Cloud SQL のインスタンスを作成するをご覧ください。
  • エンドユーザーがアクセスするデータとスキーマをデータベースに入力します。

必要なロールと権限

Cloud SQL インスタンスに executesql 権限を付与する

Cloud SQL インスタンスに executesql 権限を付与し、Cloud SQL Data API を有効にするには、次のコマンドを実行します。 
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
INSTANCE_ID は、Cloud SQL インスタンス ID に置き換えます。

環境を準備する

エージェント コンテキスト ファイルは、任意のローカル開発環境または IDE から作成できます。環境を準備する手順は次のとおりです。

  • Gemini CLI をインストールする
  • MCP ツールボックスをインストールして設定する
  • DB コンテキスト拡充 MCP サーバーをインストールして設定する

Gemini CLI をインストールする

Gemini CLI をインストールするには、Gemini CLI の使用を開始するをご覧ください。Gemini CLI は、必ず別のディレクトリにインストールしてください。そのディレクトリを、MCP ツールボックスと DB コンテキスト拡充 MCP サーバーのインストールにも使用します。

MCP ツールボックスをインストールして設定する

  1. Gemini CLI をインストールしたディレクトリに、MCP ツールボックス Gemini CLI 拡張機能をインストールします。

    gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

  2. データベース接続を構成するために、MCP ツールボックスをインストールしたのと同じディレクトリ内に tools.yaml 構成ファイルを作成します。

      sources:
    my-cloud-sql-mysql-source:
      kind: cloud-sql-mysql
      project: PROJECT_ID
      region: REGION_ID
      instance: INSTANCE_ID
      database: DATABASE_ID
      user: USER_NAME
      password: PASSWORD

    次のように置き換えます。

    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
    • REGION_ID: Cloud SQL インスタンスのリージョン（us-central1 など）。
    • INSTANCE_ID: Cloud SQL インスタンスの ID。
    • DATABASE_ID: 接続先のデータベースの名前。
    • USER_NAME: データベース ユーザー。この値を設定する方法について詳しくは、MCP ツールボックス内のソースをご覧ください。
    • PASSWORD: データベース ユーザー用のパスワード。この値を設定する方法について詳しくは、MCP ツールボックス内のソースをご覧ください。

  3. tools.yaml ファイルが正しく構成されていることを確認します。

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

DB コンテキスト拡充 MCP サーバーをインストールする

DB コンテキスト拡充 MCP サーバーは、データベース スキーマから構造化された NL2SQL テンプレートを生成するためのインタラクティブなガイド付きワークフローを提供します。データベース接続には MCP Toolbox 拡張機能を使用します。DB コンテキスト拡充 MCP サーバーのインストールについて詳しくは、DB コンテキスト拡充 MCP サーバーをご覧ください。

DB コンテキスト拡充 MCP サーバーをインストールする手順は次のとおりです。

  1. Gemini CLI をインストールしたのと同じディレクトリに、uv Python パッケージ インストーラをインストールします。

      pip install --user pipx
  pipx ensurepath
  pipx install uv

  2. DB コンテキスト拡充 MCP サーバーをインストールします。

    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

このサーバーは生成に Gemini API を使用します。必ず、API キーを環境変数としてエクスポートしてください。API キーの確認方法については、Gemini API キーを使用するをご覧ください。

Gemini API キーをエクスポートするには、次のコマンドを実行します。

export GEMINI_API_KEY="YOUR_API_KEY"

YOUR_API_KEY は、実際の Gemini API キーに置き換えます。

ターゲットを絞ったテンプレートを生成する

特定のクエリのペアをクエリ テンプレートとしてエージェント コンテキストに追加する場合は、/generate_targeted_templates コマンドを使用します。テンプレートについて詳しくは、データ エージェントの概要をご覧ください。

クエリ テンプレートをエージェント コンテキストに追加する手順は次のとおりです。

  1. Gemini CLI をインストールしたのと同じディレクトリで Gemini を起動します。

    gemini

  2. Gemini CLI の認証を設定します。

  3. MCP ツールボックスとデータベース拡充拡張機能が使用可能な状態であることを確認します。

    /mcp list

  4. /generate_targeted_templates コマンドを実行します。

    /generate_targeted_templates

  5. クエリ テンプレートに追加する自然言語によるクエリを入力します。

  6. 対応する SQL クエリをクエリ テンプレートに入力します。

  7. 生成されたクエリ テンプレートを確認します。クエリ テンプレートは、エージェント コンテキスト ファイルとして保存することも、既存のコンテキスト ファイルに追加することもできます。

my-cluster-psc-primary_postgres_templates_20251104111122.json と同様のエージェント コンテキスト ファイルが、コマンドを実行したディレクトリに保存されます。

コンテキスト ファイルとクエリ テンプレートについて詳しくは、エージェント コンテキストをご覧ください。

ターゲットを絞ったファセットを生成する

特定のクエリのペアをファセットとしてエージェント コンテキスト ファイルに追加する場合は、/generate_targeted_fragments コマンドを使用します。ファセットについて詳しくは、データ エージェントの概要をご覧ください。

ファセットをエージェント コンテキストに追加する手順は次のとおりです。

  1. /generate_targeted_fragments コマンドを実行します。

    /generate_targeted_fragments

  2. クエリ テンプレートに追加する自然言語によるクエリを入力します。

  3. 対応する SQL クエリをクエリ テンプレートに入力します。

  4. 生成されたファセットを確認します。ファセットは、エージェント コンテキスト ファイルとして保存することも、既存のコンテキスト ファイルに追加することもできます。

my-cluster-psc-primary_postgres_templates_20251104111122.json と同様のエージェント コンテキスト ファイルが、コマンドを実行したディレクトリに保存されます。

コンテキスト ファイルとファセットについて詳しくは、エージェント コンテキストをご覧ください。

省略可: テンプレートを一括生成する

データベース スキーマとデータに基づいてエージェント コンテキスト ファイルを自動生成するには、/generate_bulk_templates コマンドを使用します。

テンプレートを一括で自動生成する手順は次のとおりです。

  1. /generate_bulk_templates コマンドを実行します。

    /generate_bulk_templates

  2. データベース スキーマに基づくテンプレート ベースの SQL 生成が行われる際は、データベース情報の確認とデータベース スキーマへのアクセス権限の付与に関連する一連の質問が表示されます。

  3. 生成されたクエリ テンプレートを確認します。テンプレートを承認することも、修正の必要があるクエリのペアを更新することもできます。

  4. クエリ テンプレートに追加する自然言語によるクエリを入力します。

  5. 対応する SQL クエリをクエリ テンプレートに入力します。

  6. 生成されたクエリ テンプレートを確認します。クエリ テンプレートは、エージェント コンテキスト ファイルとして保存することも、既存のコンテキスト ファイルに追加することもできます。

  7. クエリ テンプレートを承認したら、新しいテンプレート ファイルを作成するか、クエリのペアを既存のテンプレート ファイルに追加します。クエリ テンプレートは、ローカル ディレクトリに JSON ファイルとして保存されます。

my-cluster-psc-primary_postgres_templates_20251104111122.json と同様のエージェント コンテキスト ファイルが、コマンドを実行したディレクトリに保存されます。

エージェント コンテキスト ファイルについて詳しくは、エージェント コンテキストをご覧ください。

次のステップ