このドキュメントでは、データ エージェント アプリケーションで QueryData クエリの精度を高めるのに役立つコンテキスト セットを作成して最適化する方法について説明します。コンテキスト エンジニアリング エージェントは、コンテキスト セットの作成と最適化を自動化することで、コンテキスト セットの構築、評価、改善を支援します。
コンテキスト セットと QueryData については、コンテキスト セットの概要と QueryData の概要をご覧ください。エンタープライズ グレードのデータ アプリケーションを構築するには、通常、Text-to-SQL モデルの精度で 100% に近い品質を実現する必要があります。クエリ結果が正しくないと、アプリケーションの全体的なユーザビリティとユーザー エクスペリエンスに影響します。説明可能でビジネスに関連する回答を高い精度で実現するには、コンテキスト エンジニアリングが必要です。これは、最適な精度を実現するためにコンテキストを作成して繰り返し最適化するプロセスです。
ビジネス アプリケーションを対象としたコンテキストで QueryData を提供することで、ユーザーの微妙な意図を解決するためにシステムが必要とする正確なビジネスルールを提供します。
コンテキスト エンジニアリング エージェント
コンテキスト エンジニアリング エージェントは、この最適化ワークフローを自動化します。エージェントと会話して、コンテキストを最適化するためのアドホック タスクを処理できます。次のリストは、エージェントに指示するために使用できる自然言語プロンプトの例と、エージェントの応答方法の説明を示しています。これらの例を参考にして、コンテキストを構築して最適化してください。
- 障害分析のプロンプトの例: 「'ディズニーワールド フライト' などのクエリで空港を正しく特定できるように、コンテキストを更新してください。」エージェントは障害を分析し、ギャップについて推論し、値検索クエリなどの適切なコンテキスト アイテムを追加することを推奨します。
- コンテキスト候補のプロンプトの例: 「アプリコードを読んで、追加するコンテキストを提案して。」エージェントはコードを解析し、アプリケーションのドメインについて推論して、関連するコンテキスト アイテムを提案します。
- 一括処理のプロンプトの例: 「質問と SQL クエリの例を 10 個示します。テンプレートに変換します。」エージェントは入力を一括処理し、コンテキスト セットを更新します。
ゴールデン データセットの重要性
コンテキストを最適化するには、まずアプリケーションの自然言語入力と一致するデータセットを作成する必要があります。エージェントは、ユーザーの質問と想定されるデータベース クエリで構成されるこのゴールデン データセットの構築を支援します。ゴールデン データセットを使用すると、次のことが可能になります。
- クエリ パフォーマンスのベースラインを確立します。
- グラウンド トゥルース データベース クエリに対して更新を検証します。
- イテレーション全体で精度の向上を測定します。
体系的なヒルクライミング プロセス
体系的なヒルクライミングでは、エージェントはゴールデン データセットの評価、ギャップ分析、更新を通じてコンテキスト セットを繰り返し改善し、精度を 100% に近づけます。
- ベースライン コンテキストを自動生成する: データベース スキーマとアプリケーション アーティファクトから派生した開始コンテキスト セットを作成します。
- 山登り最適化ワークフロー: エージェントが QueryData の精度を評価し、障害のギャップ分析を行い、精度を高めるための改善案を自動的に提案します。
次の図は、体系的なヒルクライミングのワークフローを示しています。
始める前に
コンテキスト エンジニアリング エージェントを使用する前に、次の前提条件を満たす必要があります。
必要なサービスを有効にする
プロジェクトで次のサービスを有効にします。Cloud SQL インスタンスを準備する
既存の Cloud SQL インスタンスにアクセスできることを確認するか、新しいインスタンスを作成します。詳細については、Cloud SQL のインスタンスを作成するをご覧ください。このチュートリアルでは、Cloud SQL インスタンスにデータベースが必要です。詳細については、Cloud SQL インスタンスでデータベースを作成するをご覧ください。
必要なロールと権限
- IAM ユーザーまたはサービス アカウントをインスタンスに追加します。詳細については、Cloud SQL の IAM データベース認証でユーザーを管理するをご覧ください。
- プロジェクト レベルで IAM ユーザーに
cloudsql.studioUser、cloudsql.instanceUser、geminidataanalytics.queryDataUserのロールを付与します。詳細については、プロジェクトの IAM ポリシー バインディングを追加するをご覧ください。 - また、
postgresユーザーなどのスーパーユーザー権限を持つユーザーとしてログインして、IAM ユーザーまたはサービス アカウントに読み取り専用のデータベース権限を付与する必要があります。GRANT SELECT ON ALL TABLES IN SCHEMA public TO USER_NAME;
USER_NAME は、ユーザーのメールアドレスに置き換えます。メールアドレスには特殊文字（@ と .）が含まれているため、引用符で囲む必要があります。
詳細については、個々の IAM ユーザーまたはサービス アカウントにデータベース権限を付与するをご覧ください。
Cloud SQL インスタンスに executesql 権限を付与する
Cloud SQL インスタンスに executesql 権限を付与し、Cloud SQL Data API を有効にするには、次のコマンドを実行します。
gcloud config set project PROJECT_ID gcloud components update gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
PROJECT_ID: 実際の Google Cloud プロジェクト ID。INSTANCE_ID: Cloud SQL インスタンスの ID。
環境を準備する
コンテキスト セット ファイルは、任意のローカル開発環境または IDE から作成できます。環境を準備するには、次の手順を行います。
- コンテキスト エンジニアリング エージェントをインストールする
- データベース接続を設定する
コンテキスト エンジニアリング エージェントをインストールする
コンテキスト エンジニアリング エージェントは、基盤となる Python パッケージの管理に uv を必要とする Model Context Protocol（MCP）サーバーを実行します。
uvをインストールするの手順に沿って、uvをインストールします。uvがインストールされ、コマンドラインからアクセスできることを確認します。uv --version
環境を準備するには、選択したエージェント ハーネス（Antigravity CLI、Claude Code、Gemini CLI など）にコンテキスト エンジニアリング エージェントをインストールします。
選択したエージェント ハーネスに応じて、対応するインストール手順を行います。
Antigravity CLI
Antigravity CLI にコンテキスト エンジニアリング エージェントをインストールする手順は次のとおりです。
- Antigravity CLI をインストールします。Antigravity CLI を使ってみるをご覧ください。
- コンテキスト生成のワークフローを含むコンテキスト エンジニアリング エージェント プラグインをインストールします。VERSION は、必要なリリース バージョンに置き換えます。
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
- Antigravity CLI を起動します。
agy
- 省略可。プラグインを更新します。
agy plugin uninstall google-cloud-db-context-engineering agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/NEW_VERSION
Claude Code
Claude Code にコンテキスト エンジニアリング エージェントをインストールする手順は次のとおりです。
- プラグイン マーケットプレイスを追加します。
/plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
- プラグインをインストールします。
/plugin install db-context-engineering@db-context-enrichment-marketplace
- プラグインを再読み込みして変更を有効にします。
/reload-plugins
- 省略可。プラグインを更新します。
/plugin update db-context-engineering@db-context-enrichment-marketplace
Gemini CLI（非推奨）
Gemini CLI にコンテキスト エンジニアリング エージェントをインストールする手順は次のとおりです。
- Gemini CLI をインストールします。Gemini CLI の使用を開始するをご覧ください。
- 拡張機能をインストールします。
gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
- 省略可。拡張機能を更新します。
gemini extensions update mcp-db-context-enrichment
データベース接続を設定する
エージェントは、スキーマを取得するためのデータベース接続と、生成された SQL コンテキストの構文を検証する機能を必要とします。エージェントがデータベースを操作できるようにするには、認証情報を構成し、データベース接続構成を定義します。
アプリケーションのデフォルト認証情報を構成する
コンテキスト エンジニアリング エージェントから Google Cloud リソースにアクセスするためのユーザー認証情報を提供するように、アプリケーションのデフォルト認証情報（ADC）を構成します。
- Toolbox MCP サーバー: 認証情報を使用してデータベースに接続し、スキーマを取得して、検証用の SQL を実行します。
- Evalbench: 認証情報を使用して QueryData を呼び出し、評価を行います。
ターミナルで次のコマンドを実行して認証します。
gcloud auth application-default loginデータベース接続ファイルを構成する
エージェントはコンテキスト生成にデータベース接続を必要とします。これは、MCP ツールボックスがサポートし、構成ファイル内で定義します。
構成ファイルには、スキーマの取得または SQL の実行に必要なデータベース ソースとツールが指定されています。コンテキスト エンジニアリング エージェントには、構成の生成に役立つエージェント スキルがプリインストールされています。
エージェント環境を開始します。
エージェントにデータベース接続の設定を依頼します（「データベース接続の設定を手伝って」など）。エージェントの手順に沿って、現在の作業ディレクトリに
autoctx/tools.yamlとして構成ファイルを作成します。新しい
tools.yaml構成を適用するには、接続を再読み込みします。- Antigravity CLI で
/mcpを実行し、toolboxを選択して再起動します。 - Gemini CLI で
/mcp reloadを実行します。 - Claude Code で
/reload-pluginsを実行します。
- Antigravity CLI で
データベース構成ファイルを手動で構成する方法については、MCP ツールボックスの構成をご覧ください。
コンテキストを生成して最適化する
コンテキスト エンジニアリング エージェントは、コーディング エージェントのコンテキスト エンジニアリング機能を強化するための一連のエージェント スキルと MCP ツールを提供します。これらのツールを組み合わせて使用すると、ベースラインを生成し、有効性を測定して、改善を繰り返し適用できます。ただし、ワークフローのどのステージからでも開始できます。
- コンテキスト セットがすでに存在する場合は、評価に直接進むことができます。
- 修正するクエリがある場合は、ギャップ分析に直接進むことができます。
各ケーパビリティは、エージェントのアクション、ユースケース、呼び出しコマンドを記述します。
プロンプトの例は、自然言語でエージェントにクエリする方法を示しています。エージェントがリクエストを完了するために追加の詳細情報を必要とする場合は、明確化を求めるメッセージが表示されます。
評価データセットを構築して拡張する
パフォーマンスを改善するには、まずパフォーマンスを測定する必要があります。ユーザーの質問と期待される SQL で構成されるゴールデン データセットがないコンテキスト エンジニアリングでは、体系的な検証ができません。ゴールデン データセットを使用すると、すべての変更が測定可能な改善となり、グラウンド トゥルースに対して検証できます。
代表的なゴールデン データセットを手動で作成するには時間がかかり、小さなデータセットではユーザーの言い回しのバリエーションが見落とされる可能性があります。エージェントは次のようにしてこの問題を解決します。
- データベース スキーマに基づいて候補の質問と SQL のペアを生成する。
- フィルタのバリエーション、同義語、言い換えを使用して、小さなシード データセットを拡張します。
必要に応じて、生成された SQL をデータベースに対して実行するようにエージェントに指示できます。この検証により、クエリをデータセットに追加する前に、クエリが正常に実行されることを確認できます。
データセットは、質問と SQL のペアを含む JSON ファイルです。
[
{
"id": "example_001",
"nlq": "What is the total revenue for the top 5 products?",
"golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
}
]
承認されたペアは、ワークスペースの autoctx/golden.json ファイルに入力され、評価の準備が整います。既存のファイルを提供することも、エージェントが展開する評価例をインラインで記述することもできます。
次のプロンプト例を使用して、エージェントに指示できます。
- 「スキーマから評価データセットを生成して。」
- 「シード質問と SQL を示します。これをより広範なデータセットに拡張し、クエリが実行されることを確認してください。」
ベースライン コンテキスト セットを生成する
コンテキストを最初から作成しないようにするには、エージェントがデータベース スキーマとアプリケーション アーティファクト（ビジネスルール、サンプルクエリ、README ファイルなど）から初期コンテキスト セットを導出するようにします。このベースライン コンテキストは最終的なものではありませんが、データベース モデルに基づいた検証済みの出発点となります。
次のプロンプト例を使用して、エージェントに指示できます。
- 「スキーマからコンテキスト セットを生成して。」
- 「これらのスキーマと
requirements.mdのビジネスルールを使用して、初期コンテキストを生成します。」
エージェントは、生成されたアーティファクトを整理するテストの名前を指定するよう求めます。データベース スキーマが大きい場合は、スコープを絞り込むよう求められることがあります。Cloud SQL Studio を使用してコンテキストをアップロードするには、エージェントが JSON ファイルを生成した後に、手順に沿って操作します。
コンテキストの有効性を評価する
コンテキスト セットとゴールデン データセットを確立したら、各ゴールデン質問でデータ エージェントの QueryData API をクエリして、エージェントがコンテキストのパフォーマンスを測定できるようにします。エージェントは、生成された SQL とその実行結果を Evalbench を使用して想定される回答と比較し、比較を処理します。
評価を実行すると、次の結果が得られます。
- 合格と不合格の結果や合計スコアなどの定量的指標を使用して、コンテキストの反復処理の進捗状況を追跡します。
- インラインの会話の概要と、テストフォルダの
eval_reports/ディレクトリに書き込まれた詳細な CSV レポート。
評価を開始するには、ゴールデン データセットのパスとコンテキスト セット ID を指定します。コンテキスト セット ID を確認する方法については、エージェント コンテキスト ID を確認するをご覧ください。
次のプロンプト例を使用して、エージェントに指示できます。
- 「
golden.jsonに対してコンテキストを評価して。」 - 「前回のテストの構成を使用して評価を再実行して。」
以前に生成した評価構成を再設定せずに再実行するには、エージェントに問い合わせるか、CLI を直接呼び出します。
uvx google-evalbench --run_config=autoctx/experiments/my-experiment/eval_configs/run_config.json
評価構成スキーマと評価実行のカスタマイズ方法の詳細については、Evalbench のドキュメントをご覧ください。
ギャップ分析を実施し、改善策を提案する
クエリの失敗を解決するには、根本原因（列の誤り、テーブル結合の欠落、あいまいな用語の未解決など）を特定する必要があります。これらの問題を手動で特定するには、評価レポートの詳細な分析が必要です。
エージェントは、この分析と修正のループを自動化します。
- ギャップ分析: エージェントは評価結果とコンテキスト セットを読み取り、同様の失敗をグループ化して、テンプレート、ファセット、値検索などのターゲット コンテキストの追加を推奨します。
- 提案された修正: エージェントは具体的な編集を提案し、必要に応じてデータベースに対して SQL をテストして解決策を検証します。
- ベースラインの保持: エージェントは、ベースライン コンテキストとともに新しい JSON ファイルに改善点を書き込み、元のファイルを保持します。
次のプロンプト例を使用して、エージェントに指示できます。
- 「前回の評価でギャップ分析を行い、修正案を提案して。」
- 「このコンテキスト セットを
golden.jsonに対して最適化します。」
次のイテレーションの準備として、Data Agents Studio を使用して改善されたコンテキストをターゲット コンテキスト セットにアップロードします。手順に沿って操作してください。
オンデマンドで特定のコンテキスト アイテムを作成する
特定の質問のテンプレート、繰り返しフィルタのファセット、特定の列の値検索など、必要なコンテキストがわかっている場合、コンテキスト JSON を手動で記述すると、パラメータ名、型メタデータ、フラグメント構文でシリアル化エラーが発生する可能性があります。エージェントは JSON 形式を処理するため、ビジネスの意図に集中できます。
この機能は、新しいクエリパターンのサポートやスキーマの詳細の欠落への対応など、アドホック更新にも使用できます。JSON を取得するには、評価を実行したり、テストを設定したりせずに、必要なコンテキストをエージェントに説明します。
これは、1 回限りのタスクを渡された場合にも適切な機能です。たとえば、サポートしてほしい新しい質問と SQL のペアを関係者から渡された場合や、コードレビュー中に欠落しているファセットを見つけた場合などです。修正するためにテストを設定したり、評価を実行したりする必要はありません。必要な内容を説明すると、エージェントが JSON を生成します。
次のプロンプト例を使用して、エージェントに指示できます。
- 「SQL を使用して、'カリフォルニア州にある空港はどこですか？' という質問のテンプレートを作成して:
SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'。」 - 「赤目」というラベルの付いたフィルタ
departure_time BETWEEN '00:00:00' AND '06:00:00'のファセットを作成して。」 - 「
airports.iataの値検索を作成します。」
コンテキスト タイプの選択に関する理由
テンプレート、ファセット、値の検索のいずれの場合でも、正しいコンテキスト タイプを選択することで、コンテキストの肥大化とデータベース クエリの回帰を防ぐことができます。たとえば、ファセットの代わりにテンプレートを使用すると、ルールが重複する可能性があります。また、テンプレートで十分な場合に値検索を導入すると、クエリ レイテンシが増加する可能性があります。正しいスキーマ形式を見つけるには、コンテキスト アイテムを作成する前に、クエリ構造またはデータベース列に基づいて型を推奨するようにエージェントに指示します。エージェントは、コンテキスト オプションを理解できるように、その理由を説明します。
次のプロンプト例を使用して、エージェントに指示できます。
- 「多くのクエリでフィルタ
departure_time BETWEEN '00:00:00' AND '06:00:00'を記述し続けています。これを把握する最善の方法は何ですか？」 - 「ユーザーが自由形式のテキストでフライトのステータスを説明しているため、
flights.statusと照合したい。どのような値検索を設定すればよいですか？」 - 「テンプレートとファセットの違いは何ですか？また、それぞれをいつ使用すればよいですか？」
コンテキスト セット全体に一括オペレーションを適用する
エージェントは、大規模なコンテキスト セットを一貫して管理するための一括更新をサポートしています。データベースの列の名前が変更された場合、コード値の形式が変更された場合、テンプレートが非推奨のテーブルを参照している場合など、複数のコンテキスト アイテムを同時に更新する必要がある場合、エージェントは関連のないエントリを変更せずに、影響を受けるすべてのアイテムに変更を適用できます。
次のプロンプト例を使用して、エージェントに指示できます。
- 「
golden.txtを読み取り、すべてのペアをテンプレートに変換します。」 - 「
context_set.jsonで、'United' を参照するアイテムのairline = 'UA'をairline = 'United Airlines'に置き換えます。関係のないアイテムはそのままにしておきます。」
次のステップ
- 詳しくは、コンテキスト セットをご覧ください。
- Cloud SQL Studio でコンテキスト セットを作成または削除する方法を確認する。
- 詳しくは、コンテキスト セットをテストする方法をご覧ください。