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

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

次のステップ