コンテキスト エンジニアリング エージェントを使用してコンテキスト セットを構築して最適化する

データ エージェント アプリケーションで QueryData クエリの精度を高め、オンライン レイテンシを低減するには、コンテキスト エンジニアリング エージェントを使用してコンテキスト セットを構築、評価、最適化します。コンテキストの作成、アップロード、最適化を自動化することで、エージェントはアプリケーションが自然言語の質問に対して高速で確定的、説明可能な回答を返すようにします。

コンテキスト セットと QueryData の詳細については、コンテキスト セットの概要と QueryData の概要をご覧ください。

ビジネス アプリケーションに合わせてカスタマイズされたコンテキストを QueryData に提供することで、システムがニュアンスのあるユーザー インテントを解決し、100% に近いクエリ品質を実現するために必要な正確なビジネスルールを提供できます。CLI または IDE で作業すると、コンテキスト エンジニアリング エージェントは、バージョン管理のためにワークスペースにローカル ファイルを保存しながら、コンテキスト セットを Google Cloud に自動的にアップロードします。

コンテキスト エンジニアリング エージェント

コンテキスト エンジニアリング エージェントは、CLI または IDE で直接設計時のアシスタントとして機能します。手動でコンテキストを作成するには、詳細なクエリパターンを手動で記述し、すべての言い回しのバリエーションを予測して、イテレーション全体でクエリの失敗を手動で診断する必要があります。コンテキスト エンジニアリング エージェントは、ベースライン コンテキストのブートストラップ、グラウンド トゥルース評価データセットのキュレーション、精度のギャップを修正するための反復的なヒルクライム、コンテキストが新しい質問に一般化されることの証明により、このオーバーヘッドを排除します。

自然言語を使用してエージェントと会話することで、最適化ワークフローを推進します。「アプリケーションの要件に合わせてコンテキスト セットを最適化する」などのプロンプトから始めます。

始める前に

コンテキスト エンジニアリング エージェントを使用する前に、次のセクションの前提条件を完了してください。データベース インスタンスが別のリージョンにある場合でも、us-central1、us-east1、europe-west4、asia-southeast1 リージョンにコンテキスト セットを作成して保存できます。

必要なサービスを有効にする

プロジェクトで次のサービスを有効にします。

データベースを準備する

Spanner インスタンスとデータベースを準備します。

必要なロールと権限

コンテキスト エンジニアリング エージェントの使用とコンテキスト セットの管理に必要な権限を取得するには、次の Identity and Access Management（IAM）ロールとデータベース権限を構成します。

  • プロジェクト レベルで IAM ユーザーまたはサービス アカウントに roles/spanner.databaseReader、roles/serviceusage.serviceUsageConsumer、roles/geminidataanalytics.queryDataUser、roles/mcp.toolUser ロールを付与します（または、必要なデータベースのデータベース レベルで roles/spanner.databaseReader を付与します）。詳細については、IAM ロールを適用するとプロジェクトの IAM ポリシー バインディングを追加するをご覧ください。
  • コンテキスト セットを作成、アップロード、管理するには、プロジェクト レベルで IAM ユーザーに Dataplex Catalog 編集者（roles/dataplex.catalogEditor）または Dataplex Catalog 管理者（roles/dataplex.catalogAdmin）ロールを付与します。詳細については、コンテキスト セットの権限をご覧ください。

環境を準備する

コンテキスト セットは、ローカル開発環境または IDE から作成して最適化できます。

uv をインストールする

コンテキスト エンジニアリング エージェントは、基盤となる Python パッケージを管理するために uv を必要とします。

  1. uv をインストールするの手順に沿って、uv をインストールします。

  2. uv がインストールされ、コマンドラインからアクセスできることを確認します。

    uv --version

コンテキスト エンジニアリング エージェントをインストールする

使用する開発環境にコンテキスト エンジニアリング エージェント プラグインをインストールします。

Antigravity CLI

  1. Antigravity CLI をインストールします。Antigravity CLI を使ってみるをご覧ください。
  2. コンテキスト エンジニアリング エージェント プラグインをインストールします。
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. Antigravity CLI を起動します。
    agy

後でプラグインを更新するには、agy plugin uninstall db-context-engineering を実行してから agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin を実行します。

Claude Code

  1. プラグイン マーケットプレイスを追加します。
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. プラグインをインストールします。
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. プラグインを再読み込みして変更を有効にします。
    /reload-plugins

後でプラグインを更新するには、/plugin update db-context-engineering@db-context-enrichment-marketplace を実行します。

Gemini CLI（非推奨）

  1. Gemini CLI をインストールします。Gemini CLI の使用を開始するをご覧ください。
  2. 拡張機能をインストールします。 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

後で拡張機能を更新するには、gemini extensions update google-cloud-db-context-engineering を実行します。

Google Cloudで認証する

  1. 開発環境を認証するようにアプリケーションのデフォルト認証情報（ADC）を構成します。

    gcloud auth application-default login

  2. Model Context Protocol（MCP）ツールが Google Cloud プロジェクトを使用できるように、認証情報の割り当てプロジェクトを設定します。

    gcloud auth application-default set-quota-project PROJECT_ID

    PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。

データベースに接続します

  1. エージェント環境を起動し、エージェントにデータベース接続を確立するよう依頼します（例: 「データベース接続の設定を手伝って」）。エージェントは、スキーマを読み取って SQL を検証できるように、.context-engineering/tools.yaml 構成ファイルの作成をガイドします。（.context-engineering/tools.yaml が作成される前に、起動時に最初の toolbox MCP サーバー接続警告が表示されることが想定されます）。

  2. MCP サーバー接続を再読み込みして、.context-engineering/tools.yaml 構成を適用します。

    • Antigravity CLI: /mcp を実行し、toolbox（または db-context-engineering_toolbox）を選択して再起動します。
    • Claude Code: /mcp を実行し、toolbox を選択して、Reconnect を選択します。
    • Gemini CLI: /mcp refresh（または /mcp reload）を実行します。

コンテキストを構築して最適化する

コンテキスト エンジニアリング エージェントは、初期ブートストラップから検証済みの一般化可能性まで、エンドツーエンドのライフサイクルを通じてコンテキスト セットをガイドします。

ベースライン コンテキスト セットをブートストラップする

エージェントは、空白のページからコンテキストを作成するのではなく、データベース スキーマと、ビジネス要件、ドキュメント、サンプル SQL クエリなどの利用可能なアプリケーション アーティファクトを検査します。エージェントは、データベース モデルに基づく基本的なクエリ テンプレートとクエリ ファセットを含む初期ベースライン コンテキスト セットを導出します。

ベースライン コンテキストを生成して検証した後、エージェントはそれを Google Cloud に直接アップロードし、コンテキスト セットのリソース名を返します。

アプリケーション アーティファクトから評価データセットとホールドアウト データセットを作成する

精度を体系的に向上させるには、検証済みの SQL クエリとペアになったグラウンド トゥルースの質問が必要です。評価ベンチマークがまだない場合は、エージェントがアプリケーション コード、過去のクエリ、データベース スキーマからビジネス シナリオを抽出してベンチマークを生成できます。

データセットの生成中に、エージェントは 2 つの異なるセットを作成します。

  • トレーニング ベンチマーク: 反復的な最適化で使用される、代表的な質問と SQL のペアのコレクション。
  • ホールドアウト データセット: トレーニング ベンチマークとドメインが類似した、一般化可能性のテスト用に予約された個別の質問セット。

山登り法で精度を最適化する

ヒルクライミング最適化では、エージェントはコンテキスト セットを繰り返し改良して、QueryData の精度を 100% に近づけます。

  • 評価: エージェントは、QueryData API を使用して、現在のコンテキスト セットをトレーニング ベンチマークに対してテストし、精度をスコア付けします。
  • ギャップを診断する: エージェントはクエリの失敗を分析し、根本原因（テーブル結合の欠落、リンクされていない非公開エンティティ、複雑なフィルタ条件など）を特定して、ターゲットを絞った修正を策定します。
  • 改良とアップロード: エージェントは、クエリ テンプレート、クエリ ファセット、値検索を追加または改善してギャップを解消し、更新されたコンテキスト セットを CLI から Google Cloud に自動的にアップロードします。
  • 反復処理: エージェントは、精度が最適なスコアに収束するまで、ラウンド全体でこのサイクルを繰り返します。

次の図は、体系的な山登りワークフローを示しています。

コンテキストを反復的に構築するためのワークフロー。

ホールドアウト データセットで一般化可能性を証明する

トレーニング ベンチマークで高精度を達成することは必要ですが、本番環境のトラフィックには、開発中に見られなかった表現のバリエーションや複雑な複合質問が含まれます。

山登り最適化が収束すると、エージェントは、結果のコンテキスト セットをホールドアウト データセットに対してテストします。このステップでは、設定されたコンテキストが、初期ベンチマークに過剰適合することなく、新しいユーザー入力に適切に一般化されることを確認します。エージェントは、未知の質問バリエーションと複合フィルタ（「デルマーの良い学校の近くにある、オーシャンビューの新婚家庭向けの家を探して」など）にわたる精度を示す一般化可能性レポートを生成します。

オンデマンドの作成と推論

完全な最適化の実行に加えて、ビジネス要件の変化に応じて、エージェントと会話してターゲットを絞った更新を行うことができます。

  • ターゲットを絞ったオーサリング: 特定のビジネス要件を自然言語で記述すると、エージェントがコンテキスト アイテムをフォーマットし、手動編集なしで CLI から直接アップロードします。

    • 「『デルマーの良い学校の近くにある家を探して』という質問のテンプレートを、SQL: SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7 を使用して作成して。」
    • 「『初めての家族向け』というラベルが付いたフィルタ properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 のファセットを作成して。」
    • 「properties.city の値検索を作成して。」

  • コンテキスト セット全体の一括更新: データベース列の名前が変更されたり、テーブル構造が変更されたりした場合、エージェントは、関連のないエントリを変更することなく、影響を受けるすべてのコンテキスト アイテムを同時に更新できます。

    • 「私のコンテキスト セットで、一戸建て住宅を参照するアイテムの properties.property_type = 'SFR' を properties.property_type = 'Single Family Residential' に置き換えてください。関係のないアイテムはそのままにしておきます。

次のステップ