このチュートリアルでは、 Google Cloud コンソールを使用して Spanner Graph で QueryData を設定して使用し、アプリケーションと統合する方法について説明します。FinGraph プロパティ グラフを設定する方法、コンテキスト エンジニアリング エージェントを使用して Graph Query Language(GQL)コンテキスト セット ファイルを構築する方法、Spanner Studio でコンテキスト セットを作成する方法、graph_ids を構成して 会話型分析 API の QueryData メソッドを呼び出して QueryData をテストする方法、MCP ツールボックスのカスタム HTTP ツールを使用してエージェント アプリケーションを QueryData に接続する方法について説明します。
詳細については、QueryData の概要をご覧ください。
目標
FinGraphプロパティ グラフ スキーマを作成し、サンプル グラフデータを入力します。- コンテキスト エンジニアリング エージェントを使用して、
FinGraphのコンテキスト セット ファイルをビルドします。 - コンテキスト セットを作成し、Spanner Studio でコンテキスト セット ファイルをアップロードします。
spanner_referenceで指定されたgraph_idsを使用してQueryDataREST API を呼び出し、QueryData をテストして GQL クエリを生成します。QueryDataREST API を呼び出す MCP ツールボックスのカスタム HTTP ツールを使用して、QueryData をアプリケーションに統合します。- クエリ テンプレート、クエリ ファセット、
GRAPH_TABLE値検索クエリを使用して、グラフデータで LLM レスポンスをグラウンディングします。
費用
このドキュメントでは、課金対象である次の Google Cloudコンポーネントを使用します。
料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを算出できます。
新規の Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。
このドキュメントのタスクを完了したら、作成したリソースを削除して、それ以上の請求が発生しないようにします。詳細については、クリーンアップをご覧ください。
始める前に
コンテキスト セットを作成する前に、次の前提条件を満たす必要があります。
必要なサービスを有効にする
プロジェクトで次のサービスを有効にします。Spanner インスタンスを準備する
- Spanner インスタンスが使用可能であることを確認します。詳細については、インスタンスの作成をご覧ください。
- テーブルを作成するインスタンスにデータベースを作成してください。詳細については、Spanner インスタンスでデータベースを作成するをご覧ください。
必要なロールと権限
- IAM ユーザーまたはサービス アカウントをインスタンスに追加します。詳細については、IAM ロールを適用するをご覧ください。
- プロジェクト レベルで IAM ユーザーに
roles/spanner.databaseReader、roles/serviceusage.serviceUsageConsumer、roles/geminidataanalytics.queryDataUserのロールを付与します。詳細については、プロジェクトの IAM ポリシー バインディングを追加するをご覧ください。 - コンテキスト セットを作成、アップロード、管理するには、プロジェクト レベルで IAM ユーザーに Dataplex Catalog 編集者(
roles/dataplex.catalogEditor)または Dataplex Catalog 管理者(roles/dataplex.catalogAdmin)ロールを付与します。詳細については、コンテキスト セットの権限をご覧ください。 - 必要なデータベースに対して、プロジェクト レベルで IAM ユーザーにロールと権限を付与します。
FinGraph スキーマを作成してグラフデータを挿入する
このチュートリアルでは、FinGraph 金融プロパティ グラフ データセットを使用します。このデータセットは、Owns(PersonOwnAccount)エッジと Transfers(AccountTransferAccount)エッジで接続された Person ノードと Account ノードをモデル化します。
FinGraph スキーマを作成し、Spanner データベースにグラフデータを入力するには、Spanner Graph 設定ガイドの手順を完了します。
- スキーマを使用してグラフ データベースを作成するの手順に沿って、
Person、Account、PersonOwnAccount、AccountTransferAccountテーブルとFinGraphプロパティ グラフ定義を作成します。 - グラフデータを挿入するの手順に沿って、サンプルの人物(
Alex、Dana、Lee)、アカウント(7、16、20)、アカウント所有権エッジ、送金エッジをFinGraphに挿入します。
コンテキスト セットを作成する
fingraph-assistant という名前の空のコンテキスト セットを作成します。このチュートリアルの後半で、コンテキスト セット ファイルをアップロードします。
Google Cloud コンソールで、[Spanner] ページに移動します。
リストからインスタンスを選択し、
FinGraphを含むデータベースを選択します。ナビゲーション メニューで [Spanner Studio] をクリックします。
[エクスプローラ] ペインで、[コンテキスト セット] の横にある [アクションを表示] をクリックします。
[コンテキスト セットを作成] をクリックします。
[コンテキスト セット名] フィールドに「
fingraph-assistant」と入力します。[作成] をクリックします。
コンテキストなしで QueryData をテストする
このセクションでは、QueryData REST API を呼び出して、コンテキスト セットのない自然言語の質問に対する GQL クエリを生成します。コンテキストがない場合、QueryData は FinGraph スキーマに直接マッピングされる質問に回答できますが、high-risk transfers などのカスタム ビジネス用語を解釈したり、Czech Republic と Czech_Republic などの値の形式の違いを解決したりすることはできません。
ターミナルで、次の環境変数を設定します。
export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID"
次のように置き換えます。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。INSTANCE_ID: Spanner インスタンス ID。DATABASE_ID:FinGraphを含むデータベースの ID。
graph_idsをFinGraphに設定してQueryDataREST API に質問を送信するquery_data.shという名前のヘルパー スクリプトを作成します。CONTEXT_SET_ID環境変数が設定されている場合、スクリプトはコンテキスト セット ID も送信します。cat > query_data.sh <<'EOF' #!/bin/bash # Usage: ./query_data.sh "NATURAL_LANGUAGE_QUESTION" if [[ -n "${CONTEXT_SET_ID}" ]]; then AGENT_CONTEXT=", \"agent_context_reference\": {\"context_set_id\": \"${CONTEXT_SET_ID}\"}" fi curl -sS -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: ${PROJECT_ID}" \ "https://geminidataanalytics.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global:queryData" \ -d @- <<JSON { "prompt": "$1", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "${PROJECT_ID}", "instance_id": "${INSTANCE_ID}", "database_id": "${DATABASE_ID}", "graph_ids": ["FinGraph"] }${AGENT_CONTEXT} } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true } } JSON EOF chmod +x query_data.shスクリプトは質問をリクエスト本文にそのまま挿入するため、質問に二重引用符(
")を使用しないでください。FinGraphスキーマに直接マッピングされる質問をします。./query_data.sh "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts."
レスポンスで、
generatedQueryフィールドとqueryResultフィールドを確認します。この明確な質問に対して、QueryData は次のような GQL クエリを生成します。GRAPH FinGraph MATCH (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account), (recipient:Person)-[:Owns]->(dst) RETURN recipient.name AS recipient_name, dst.id AS recipient_account_id, t.amount AS transfer_amount;これにより、次のような結果が返されます。
+----------------+----------------------+-----------------+ | recipient_name | recipient_account_id | transfer_amount | +----------------+----------------------+-----------------+ | Alex | 7 | 500 | | Lee | 16 | 200 | +----------------+----------------------+-----------------+ビジネス用語
high-risk transfersを含む質問をします。./query_data.sh "Find all high-risk transfers initiated by Alex"
FinGraphスキーマでは、high-risk transferを構成する要素(ビジネス ロジックでは、is_blocked = trueのブロックされたアカウントへの200以上の送金を意味する)が定義されていないため、QueryData は、ブロックされたアカウントと金額のしきい値フィルタを適用しないか、この用語を独自に解釈して適用します。たとえば、QueryData は、行を返さない金額しきい値を考案したり、この用語を無視して次のようなクエリを生成したりすることがあります。-- Returning transfers initiated by Alex because 'high-risk' is not defined in the schema. GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account) RETURN src.id AS source_account_id, dst.id AS destination_account_id, t.amount AS transfer_amount, t.order_number;これにより、しきい値を満たしていない
100の転送を含む、Alex の両方の転送が返されます。+-------------------+------------------------+-----------------+-----------------+ | source_account_id | destination_account_id | transfer_amount | order_number | +-------------------+------------------------+-----------------+-----------------+ | 7 | 16 | 300 | 304330008004315 | | 7 | 16 | 100 | 304120005529714 | +-------------------+------------------------+-----------------+-----------------+国を参照する質問をします。
./query_data.sh "Find accounts owned by people from Czech Republic"
コンテキストまたは値のリンクがない場合、QueryData はスペースを含む
'Czech Republic'をフィルタする GQL クエリを生成します。FinGraphのPerson.countryプロパティは値をアンダースコア付きの'Czech_Republic'として保存するため、クエリは行を返しません。GRAPH FinGraph MATCH (p:Person {country: 'Czech Republic'})-[:Owns]->(a:Account) RETURN p.name AS owner_name, a.id AS account_id, a.nick_name;
コンテキスト セットのコンテキストを生成する
このセクションでは、ローカル環境を準備し、コンテキスト エンジニアリング エージェントを使用して、Spanner データベースの FinGraph プロパティ グラフのコンテキスト セット ファイル(context_set.json)を作成します。
環境の設定
コンテキスト エンジニアリング エージェントの環境を設定する手順は次のとおりです。
- Antigravity CLI をインストールします。詳細については、Antigravity CLI を使ってみるをご覧ください。
- Google Cloud CLI をインストールします。
アプリケーションのデフォルト認証情報(ADC)を設定します。ターミナルで次のコマンドを実行して認証します。
gcloud auth application-default loginターミナルで、Antigravity CLI を起動します。
agySpanner データベースのデータベース接続を設定します。Spanner データベースのプロパティ グラフのコンテキストを生成することを明示的に指定し、
FinGraphプロパティ グラフ名を含むプロンプトを入力して、エージェントが GQL 固有のコンテキスト エンジニアリング ワークフローをトリガーするようにします。Help me set up the database connection for the FinGraph property graph in my Spanner database.エージェントの指示に沿って
autoctx/tools.yamlとautoctx/state.mdを作成します。次に、autoctx/state.mdを開き、## Active Databaseセクションに- **Graph Ids**: ["FinGraph"]行が含まれていることを確認します。コンテキスト エンジニアリング エージェントは、評価構成を生成するときに、この行からプロパティ グラフ名を読み取ります。tools.yamlの詳細については、MCP ツールボックスのドキュメントをご覧ください。autoctx/tools.yamlの作成後に構成を再読み込みするには、Antigravity CLI で次のコマンドを実行します。/mcp[
toolbox]、[Restart] の順に選択します。MCP ツールボックスとコンテキスト エンジニアリング エージェント プラグインが接続され、使用可能な状態であることを確認します。
/mcp
GQL テンプレート コンテキストを生成する
QueryData がビジネス用語 high-risk transfers を認識しなかった問題に対処するには、コンテキスト セット ファイルで high-risk transfers を、ブロックされたアカウント(dst.is_blocked = true)に送信された 200 以上の送金として定義します。
GQL テンプレート コンテキストを生成する手順は次のとおりです。
エージェント ハーネスに次のプロンプトを入力し、
FinGraphが Spanner データベースのプロパティ グラフであることを指定します。For the FinGraph property graph in my Spanner database, generate a GQL template for the question: "Find all high-risk transfers initiated by Alex" with the following GQL query: GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;エージェントは、入力を、人名全体で一般化するパラメータ化された GQL テンプレートに変換します。詳細については、コンテキスト セットの概要をご覧ください。
生成された GQL クエリ テンプレートを確認し、エージェントに
Save it to context_set.jsonをプロンプトします。エージェントは、次の内容のcontext_set.jsonをディレクトリに作成します。{ "templates": [ { "nl_query": "Find all high-risk transfers initiated by Alex", "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "intent": "Find all high-risk transfers initiated by Alex", "manifest": "Find all high-risk transfers initiated by a given person", "parameterized": { "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "parameterized_intent": "Find all high-risk transfers initiated by ?" } } ] }
ファセットと値の検索コンテキストを生成する
このセクションでは、GQL ファセットと 2 つの GRAPH_TABLE 値検索クエリを context_set.json に追加します。前のセクションで追加したテンプレートは、「Alex が開始した高リスクの送金をすべて検索する」と同じ構造の質問に回答します。ファセットは、ブロックされた口座のパターンをキャプチャします。これにより、QueryData は、「ブロックされた口座が関与するすべての送金を検索する」など、テンプレートに一致しない質問にもこのパターンを適用できます。値検索により、QueryData は Czech Republic などの値フレーズを Person.country の保存された値 Czech_Republic にマッピングし、大文字と小文字を区別せずに Account.nick_name のアカウントのニックネームを照合できます。
エージェント ハーネスに次のプロンプトを入力し、
FinGraphが Spanner データベースのプロパティ グラフであることを指定します。For the FinGraph property graph in my Spanner database, generate a GQL facet with the GQL clause "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})" for intent "transfers involving a blocked account". Then generate two GRAPH_TABLE value searches on FinGraph: one on Person.country that ignores case and treats underscores as spaces, with concept type "Person country", and one on Account.nick_name that ignores case, with concept type "Account nickname". Validate the value search queries against the database, and then append the facet and value searches to context_set.json.更新された
context_set.jsonファイルを確認します。このファイルには、GQL テンプレート、GQL ファセット、値検索の定義が含まれています。{ "templates": [ { "nl_query": "Find all high-risk transfers initiated by Alex", "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "intent": "Find all high-risk transfers initiated by Alex", "manifest": "Find all high-risk transfers initiated by a given person", "parameterized": { "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "parameterized_intent": "Find all high-risk transfers initiated by ?" } } ], "facets": [ { "sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})", "intent": "transfers involving a blocked account", "manifest": "transfers involving a blocked account", "parameterized": { "parameterized_sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})", "parameterized_intent": "transfers involving a blocked account" } } ], "value_searches": [ { "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (p:Person) WHERE LOWER(REPLACE(p.country, '_', ' ')) = LOWER(REPLACE($value, '_', ' ')) RETURN DISTINCT p.country AS value, 'FinGraph.Person.country' AS columns, 'Person country' AS concept_type, 0 AS distance, JSON '{}' AS context)", "concept_type": "Person country", "description": "Match for country names on Person nodes in FinGraph that ignores case and treats underscores as spaces" }, { "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (a:Account) WHERE LOWER(a.nick_name) = LOWER($value) RETURN DISTINCT a.nick_name AS value, 'FinGraph.Account.nick_name' AS columns, 'Account nickname' AS concept_type, 0 AS distance, JSON '{}' AS context)", "concept_type": "Account nickname", "description": "Case-insensitive match for account nicknames on Account nodes in FinGraph" } ] }各値検索では、
GRAPH_TABLE演算子を使用してFinGraphのノードラベルを照合し、保存されたプロパティ値、プロパティの場所(FinGraph.Person.country)、コンセプト タイプ、一致の距離0、空の JSON コンテキストを返します。詳細については、値の検索クエリをご覧ください。
コンテキスト セット ファイルを QueryData にアップロードする
このセクションでは、Spanner Studio で context_set.json ファイルを fingraph-assistant コンテキスト セットにアップロードします。
Google Cloud コンソールで、[Spanner] ページに移動します。
リストからインスタンスを選択し、Spanner データベースを選択します。
ナビゲーション メニューで [Spanner Studio] をクリックします。
[エクスプローラ] ペインで、
fingraph-assistantコンテキスト セットの横にある [アクションを表示] をクリックします。[コンテキスト セットを編集] をクリックします。
省略可: [コンテキスト セットの説明] を編集します。
[コンテキスト セット ファイルのアップロード] セクションで [参照] をクリックし、生成した
context_set.jsonファイルを選択します。[保存] をクリックします。
QueryData を使用して GQL クエリを生成する
このセクションでは、fingraph-assistant コンテキストを設定して QueryData REST API を呼び出し、QueryData が high-risk transfers などのビジネス用語を正確に変換し、GQL クエリで Czech Republic を Czech_Republic に解決することを確認します。
fingraph-assistantのコンテキスト セット ID を確認します。手順については、コンテキスト セット ID を確認するをご覧ください。CONTEXT_SET_ID環境変数を設定して、query_data.shがコンテキスト セットを送信するようにします。export CONTEXT_SET_ID="CONTEXT_SET_ID"
CONTEXT_SET_IDは、完全なコンテキスト セット ID(projects/my-project/locations/us-central1/contextSets/fingraph-assistantなど)に置き換えます。高リスクの転送に関する質問をもう一度行います。
./query_data.sh "Find all high-risk transfers initiated by Alex"
生成された GQL クエリに、ブロックされた移行先のアカウント フィルタ(
is_blocked: true)と金額のしきい値(t.amount >= 200)が適用されます。GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;これにより、Alex の
100からブロックされたアカウント16への転送が除外され、次のような結果が返されます。+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 300 | +------------------------+-----------------+Danaについて同様の質問をします。./query_data.sh "What are the high-risk transfers initiated by Dana?"
context_set.jsonの GQL テンプレートはパラメータ化されている({name: ?})ため、QueryData はDanaに同じhigh-risk transfers定義を適用します。GRAPH FinGraph MATCH (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;これにより、Dana の
500からブロックされていないアカウント7への転送が除外され、次のような結果が返されます。+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 200 | +------------------------+-----------------+国に関する質問をもう一度行います。
./query_data.sh "Find accounts owned by people from Czech Republic"
QueryData は
Person country値検索を実行し、Czech Republicを保存された値Czech_Republicにリンクして、次のようなクエリを生成します。GRAPH FinGraph MATCH (p:Person {country: 'Czech_Republic'})-[:Owns]->(a:Account) RETURN p.name AS owner_name, a.id AS account_id, a.nick_name;これにより、次のような結果が返されます。
+------------+------------+----------------+ | owner_name | account_id | nick_name | +------------+------------+----------------+ | Dana | 20 | Rainy Day Fund | +------------+------------+----------------+blocked-account ファセットを使用する質問をします。
./query_data.sh "Find all money transfers involving a blocked account."
QueryData は、ファセットを使用して、ブロックされた口座
16が関与する双方向の送金を照合し、4 つの送金を返します。
QueryData をアプリケーションと統合する
このセクションでは、Agent Development Kit(ADK)、MCP ツールボックス、fingraph-assistant コンテキスト セットを使用して、FinGraph の会話型データ エージェント アプリケーションを作成します。Spanner Graph で GQL クエリの生成を有効にするには、tools.yaml ファイルでカスタム HTTP ツールを定義します。このツールは、spanner_reference.database_reference で graph_ids を設定して QueryData REST API を呼び出します。
- MCP ツールボックス バージョン 1.4.0 以降をダウンロードします。MCP ツールボックスは、アプリケーションが接続できるように、
QueryDataREST API を MCP ツールとして公開します。 アプリケーションのデフォルト認証情報(ADC)を設定します。
gcloud auth application-default loginConversational Analytics API の HTTP ソースと、
QueryDataメソッドを呼び出す HTTP ツールを定義するtools.yaml構成ファイルを作成します。リクエスト本文のspanner_reference.database_referenceでgraph_ids(["FinGraph"]に設定)を指定します。kind: source name: gda-rest-source type: http baseUrl: https://geminidataanalytics.googleapis.com timeout: 120s headers: Authorization: Bearer ${GDA_ACCESS_TOKEN} Content-Type: application/json x-goog-user-project: ${PROJECT_ID} --- kind: tool name: fingraph_query_data_tool type: http source: gda-rest-source method: POST path: /v1beta/projects/${PROJECT_ID}/locations/global:queryData description: Use this tool to send natural language questions about the FinGraph property graph to the QueryData API and receive GQL queries, query results, natural language answers, and explanations. requestBody: | { "parent": "projects/${PROJECT_ID}/locations/global", "prompt": {{json .query}}, "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "${PROJECT_ID}", "instance_id": "${INSTANCE_ID}", "database_id": "${DATABASE_ID}", "graph_ids": ["FinGraph"] }, "agent_context_reference": { "context_set_id": "${CONTEXT_SET_ID}" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true, "generate_disambiguation_question": true } } bodyParams: - name: query type: string description: A natural language question about the FinGraph property graph.MCP ツールボックスは、
tools.yamlを読み込むときに${...}参照を対応する環境変数の値に置き換え、{{json .query}}をエージェントがツールに送信する質問(JSON 文字列としてエンコード)に置き換えます。MCP ツールボックスを実行するターミナルで、
tools.yamlが参照する環境変数を設定します。export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID" export CONTEXT_SET_ID="CONTEXT_SET_ID" export GDA_ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
次のように置き換えます。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。INSTANCE_ID: Spanner インスタンスの ID。DATABASE_ID:FinGraphを含む Spanner データベースの ID。CONTEXT_SET_ID:fingraph-assistantの完全なコンテキスト セット ID。
tools.yamlファイルを使用して MCP ツールボックス サーバーを実行します。./toolbox --config "tools.yaml"MCP ツールボックス Python SDK を使用して
fingraph_query_data_toolツールを呼び出す ADK アプリケーションを作成します。アプリケーションのディレクトリ(
fingraph-assistant-appなど)を作成し、そのディレクトリに移動します。mkdir fingraph-assistant-appcd fingraph-assistant-app仮想環境を作成し、必要なパッケージをインストールします。
python3 -m venv .venvsource .venv/bin/activatepip install toolbox-corepip install google-genaipip install google-adkADK エージェントを作成します。
adk create my_agentgemini-2.5-flashモデルを選択し、[Google AI] を選択して、Gemini API キーを入力します。詳細については、Gemini API キーを使用するをご覧ください。my_agent/agent.pyの内容を、次の Financial Graph Assistant サンプル アプリケーション コードに置き換えます。from typing import cast from google.adk.agents.llm_agent import Agent from google.adk.agents.llm_agent import ToolUnion from toolbox_core import ToolboxSyncClient TOOLBOX_URL = "http://127.0.0.1:5000" INSTRUCTION = """ # ROLE You are a factual financial graph data assistant for FinGraph. Your goal is to help users analyze account ownership, money transfers, and risk patterns by providing accurate information with a helpful, professional tone. - Always call the Query Data Tool first to answer questions about the graph data, including questions with domain-specific terms (such as "high-risk"), because the tool resolves domain definitions against the database context. Ask the user to clarify only if the tool returns a disambiguation question or fails to generate a valid query. # OPERATIONAL CONSTRAINTS - TOOL LIMITATION: You only have access to the Query Data Tool. Do not claim to have capabilities beyond what this tool provides. - TRANSPARENCY POLICY: Maintain a seamless user experience. Never mention that you are using a tool, querying a database, or generating GQL. Frame all responses as your own direct assistance. - SCOPE MANAGEMENT: If a user asks for something beyond your capabilities, politely state that you cannot perform that specific task and guide the user toward what you can help with. # COMMUNICATION STYLE - Be concise and scannable when listing answers. - Maintain a helpful, professional persona. ===== # QUERY DATA TOOL Inputs: 1. query: A natural language formulation of a graph database query. Outputs: (all optional) 1. disambiguationQuestion: Clarification questions or comments where the tool needs the user's input. 2. generatedQuery: The generated GQL query for the user query. 3. intentExplanation: An explanation for why the tool produced `generatedQuery`. 4. queryResult: The result of executing `generatedQuery`. 5. naturalLanguageAnswer: The natural language answer that summarizes the `query` and `queryResult`. Usage guidance: 1. If `disambiguationQuestion` is produced, solicit the needed inputs from the user and try the tool with a new `query` that includes the clarification. 2. If `naturalLanguageAnswer` is produced, use `intentExplanation` and `generatedQuery` to see if you need to clarify any assumptions for the user. 3. If the tool output indicates failure or empty results, explain that clearly using the provided reasoning. """ client = ToolboxSyncClient(TOOLBOX_URL) mcp_tool = client.load_tool("fingraph_query_data_tool") root_agent = Agent( model="gemini-2.5-flash", name="root_agent", instruction=INSTRUCTION, tools=cast(list[ToolUnion], [mcp_tool]), )
http://127.0.0.1:8000で ADK ウェブサーバーを起動します。adk web --port 8000ADK ウェブ UI にマルチホップ グラフの質問を入力します。
Who did Dana transfer money to, and what were the amounts?エージェントは
fingraph_query_data_toolツールを呼び出し、graph_idsをFinGraphに設定してQueryDataREST API に質問を送信します。QueryData が生成された GQL クエリを実行し、エージェントが次のようなレスポンスを返します。Dana transferred money from account 20 to the following recipients: * Alex (account 7): 500 * Lee (account 16): 200コンテキスト セットに追加した
high-risk transfersGQL テンプレートを使用する質問を入力します。What are the high-risk transfers initiated by Alex?fingraph-assistantの GQL テンプレートに基づいて、QueryData はブロックされたアカウントへの200以上の送金を特定し、エージェントは次のようなレスポンスを返します。Here is the high-risk transfer initiated by Alex (transfers of 200 or more to a blocked account): * Blocked destination account 16: amount 300
エージェントのパフォーマンスを反復処理する
ADK ウェブ UI を使用すると、fingraph_query_data_tool ツールからのリクエストとレスポンスのペイロードを検査できます。ナビゲーション パネルの [Event] タブで、functionResponse を展開して、生成された FinGraph GQL クエリ(generatedQuery)、queryResult、intentExplanation、disambiguationQuestion、naturalLanguageAnswer を確認します。QueryData REST API は、これらのフィールド名をキャメルケースで返します。
回答の精度を向上させる
GQL テンプレート、ファセット、値検索を追加することで、QueryData からの回答の精度を継続的に向上させることができます。コンテキスト エンジニアリング エージェントを使用して、Spanner データベースの FinGraph プロパティ グラフの更新されたコンテキストを生成して評価し、更新されたコンテキスト セット ファイルを Spanner Studio にアップロードします。詳細については、Spanner Studio でコンテキスト セットを管理するをご覧ください。
複数のエージェント
開発環境では、tools.yaml ファイルに複数の HTTP ツール(fingraph_query_data_tool_v1 や fingraph_query_data_tool_v2 など)を定義することで、複数の Spanner Graph コンテキスト セットで A/B テストを実行できます。各ツールのリクエスト本文で、graph_ids を ["FinGraph"] に設定し、異なる context_set_id を設定します。
クリーンアップ
このチュートリアルを終了した後、作成したリソースを削除すると、それ以上の請求は発生しません。
コンテキスト セットを削除する
Spanner データベースまたはインスタンスを削除する前に、fingraph-assistant コンテキスト セットを削除します。
Google Cloud コンソールで、[Spanner] ページに移動します。
リストからインスタンスを選択し、Spanner データベースを選択します。
ナビゲーション メニューで [Spanner Studio] をクリックします。
[エクスプローラ] ペインで、
fingraph-assistantの横にある [アクションを表示] をクリックします。[コンテキスト セットを削除] をクリックし、確認フィールドに「
fingraph-assistant」と入力して、[確認] をクリックします。
データベースとインスタンスを削除する
FinGraph プロパティ グラフ、Spanner データベース、Spanner インスタンスを削除するには、Spanner Graph を設定してクエリを実行する: クリーンアップの手順に沿って操作します。
次のステップ
- Spanner Graph のコンテキスト セットの詳細を確認する。
- コンテキスト エンジニアリング エージェントを使用してコンテキスト セットを構築する方法を確認する。
- データベース データソースの作成済みコンテキストを定義する方法を確認する。