Gemini CLI を使用してコンテキストを構築する

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

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

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

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

始める前に

エージェントを作成する前に、次の前提条件を満たしてください。

Spanner インスタンスを準備する

  • Spanner インスタンスが使用可能であることを確認します。詳細については、インスタンスの作成をご覧ください。
  • エンドユーザーがアクセスするデータとスキーマをデータベースに入力します。

必要なロールと権限

環境を準備する

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

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

Gemini CLI をインストールする

Gemini CLI をインストールするには、Gemini CLI のスタートガイドをご覧ください。Gemini CLI は、MCP ツールボックスと DB コンテキスト エンリッチメント MCP サーバーのインストールにも使用される別のディレクトリにインストールしてください。

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

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

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

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

      sources:
    my-spanner-source:
      kind: spanner
      project: PROJECT_ID
      instance: INSTANCE_ID
      database: DATABASE_ID

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

    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
    • INSTANCE_ID: Spanner インスタンスの ID。
    • DATABASE_ID: 接続先のデータベースの名前。

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

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

DB コンテキスト エンリッチメント MCP サーバーをインストールする

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

DB Context Enrichment 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 と同様のエージェント コンテキスト ファイルが、コマンドを実行したディレクトリに保存されます。

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

次のステップ