本教學課程說明如何使用 Google Cloud 控制台,在 Spanner Graph 中設定及使用 QueryData,並與應用程式整合。您將瞭解如何設定 FinGraph 屬性圖、使用脈絡工程代理建構圖形查詢語言 (GQL) 脈絡資料集檔案、在 Spanner Studio 建立脈絡資料集、設定 graph_ids 並呼叫對話式數據分析 API 的 QueryData 方法來測試 QueryData,以及在 MCP Toolbox 使用自訂 HTTP 工具,將代理應用程式連結至 QueryData。
詳情請參閱「QueryData 總覽」。
目標
- 建立
FinGraph屬性圖表結構定義,並填入範例圖表資料。 - 使用脈絡工程代理,為
FinGraph建構脈絡資料集檔案。 - 在 Spanner Studio 建立脈絡資料集,並上傳脈絡資料集檔案。
- 測試 QueryData 並生成 GQL 查詢,方法是呼叫
QueryDataREST API,並在spanner_reference中指定graph_ids。 - 在 MCP Toolbox 中使用自訂 HTTP 工具呼叫
QueryDataREST API,將 QueryData 整合至應用程式。 - 使用查詢範本、查詢 facet 和
GRAPH_TABLE值搜尋查詢,以圖表資料建立 LLM 回覆的基準。
費用
在本文件中,您會使用下列 Google Cloud計費元件:
您可以使用 Pricing Calculator,根據預測用量估算費用。
初次使用 Google Cloud 的使用者可能符合免費試用期資格。
完成本文所述工作後,請刪除建立的資源,避免繼續計費。詳情請參閱「清除所用資源」一節。
事前準備
建立情境集前,請先完成下列前置作業:
啟用必要服務
為專案啟用下列服務:準備 Spanner 執行個體
- 確認 Spanner 執行個體可用。詳情請參閱「建立執行個體」。
- 請務必在執行個體中建立資料庫,以便在其中建立資料表。詳情請參閱「在 Spanner 執行個體上建立資料庫」。
必要角色和權限
- 將 IAM 使用者或服務帳戶新增至執行個體。詳情請參閱「套用 IAM 角色」。
- 在專案層級,將
roles/spanner.databaseReader、roles/serviceusage.serviceUsageConsumer和roles/geminidataanalytics.queryDataUser角色授予 IAM 使用者。詳情請參閱「新增專案的 IAM 政策繫結」。 - 如要建立、上傳及管理情境集,請在專案層級,將 Dataplex Catalog 編輯者 (
roles/dataplex.catalogEditor) 或 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin) 角色授予 IAM 使用者。詳情請參閱「情境組合權限」。 - 在專案層級,為 IAM 使用者授予所需資料庫的角色和權限。
建立 FinGraph 結構定義並插入圖表資料
本教學課程使用 FinGraph 金融屬性圖資料集,其中 Person 和 Account 節點透過 Owns (PersonOwnAccount) 和 Transfers (AccountTransferAccount) 邊緣連結。
如要建立 FinGraph 結構定義,並在 Spanner 資料庫中填入圖形資料,請按照 Spanner Graph 設定指南完成下列步驟:
- 按照「使用結構定義建立圖形資料庫」一文的說明,建立
Person、Account、PersonOwnAccount和AccountTransferAccount資料表,以及FinGraph屬性圖定義。 - 按照「插入圖表資料」一節的說明,將範例人物 (
Alex、Dana和Lee)、帳戶 (7、16和20)、帳戶擁有權邊緣和匯款邊緣插入FinGraph。
建立脈絡資料集
建立名為 fingraph-assistant 的空白脈絡資料集。在本教學課程的後續步驟中,您會將情境集檔案上傳到這個值區。
前往 Google Cloud 控制台的「Spanner」頁面。
從清單中選取執行個體,然後選取含有
FinGraph的資料庫。在導覽選單中,點選「Spanner Studio」。
在「Explorer」窗格中,點選「Context sets」旁邊的「查看動作」。
按一下「建立情境組合」。
在「Context set name」(情境組合名稱) 欄位中,輸入
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。
建立名為
query_data.sh的輔助指令碼,將問題傳送至QueryDataREST API,並將graph_ids設為FinGraph。如果已設定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的構成要素 (在您的商業邏輯中,這代表將200以上金額轉移至is_blocked = true的封鎖帳戶),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;這會傳回 Alex 的兩筆轉帳,包括未達門檻的
100轉帳:+-------------------+------------------------+-----------------+-----------------+ | 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 會產生 GQL 查詢,篩選出含有空格的
'Czech Republic'。由於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:
agy設定 Spanner 資料庫的資料庫連線。輸入提示,明確指定要為 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 Toolbox 說明文件。如要在建立
autoctx/tools.yaml後重新載入設定,請在 Antigravity CLI 中執行下列指令:/mcp依序選取「
toolbox」和「Restart」。確認 MCP Toolbox 和情境工程代理外掛程式已連線,可供使用:
/mcp
生成 GQL 範本背景資訊
為解決 QueryData 無法辨識業務術語「high-risk transfers」的問題,請在情境集檔案中將「high-risk transfers」定義為轉帳金額達 200 以上,且轉入遭封鎖帳戶 (dst.is_blocked = true)。
如要生成 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 ?" } } ] }
生成 facet 和值搜尋背景資訊
在本節中,您會將 GQL facet 和兩個 GRAPH_TABLE 值搜尋查詢新增至 context_set.json。您在上一節新增的範本,可回答與「找出 Alex 發起的所有高風險轉移作業」結構相同的問題。Facet 會擷取封鎖帳戶模式,讓 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
在本節中,您會將 context_set.json 檔案上傳至 Spanner Studio 中的 fingraph-assistant 內容集。
前往 Google Cloud 控制台的「Spanner」頁面。
從清單中選取執行個體,然後選取 Spanner 資料庫。
在導覽選單中,點選「Spanner Studio」。
在「Explorer」窗格中,點選
fingraph-assistant情境集旁邊的「查看動作」。按一下「編輯情境組合」。
選用:編輯「Context set description」(情境集說明)。
按一下「Upload context set file」(上傳情境集檔案) 專區中的「Browse」(瀏覽),然後選取您產生的
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 轉移至封鎖帳戶
16的100,並傳回類似下列的結果:+------------------------+-----------------+ | 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 會將相同的high-risk transfers定義套用至Dana: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 會使用 facet 比對涉及封鎖帳戶
16的雙向轉帳,並傳回四筆轉帳。
將 QueryData 與應用程式整合
在本節中,您將使用 Agent Development Kit (ADK)、MCP Toolbox 和 fingraph-assistant 情境集,為 FinGraph 建立對話式資料代理應用程式。如要為 Spanner Graph 啟用 GQL 查詢生成功能,請在 tools.yaml 檔案中定義自訂 HTTP 工具,呼叫 QueryData REST API,並在 spanner_reference.database_reference 中設定 graph_ids。
- 下載 MCP Toolbox 1.4.0 以上版本。MCP Toolbox 會將
QueryDataREST API 公開為 MCP 工具,供應用程式連線。 -
gcloud auth application-default login 建立
tools.yaml設定檔,定義 對話式數據分析 API 的 HTTP 來源,以及呼叫QueryData方法的 HTTP 工具。請務必在要求主體的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 Toolbox 載入
tools.yaml時,會將${...}參照替換為對應環境變數的值,並將{{json .query}}替換為代理傳送至工具的問題 (編碼為 JSON 字串)。在執行 MCP Toolbox 的終端機中,設定
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 伺服器:./toolbox --config "tools.yaml"使用 MCP Toolbox Python SDK 建立 ADK 應用程式,叫用
fingraph_query_data_tool工具:建立並切換至應用程式的目錄,例如
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-adk建立 ADK 代理:
adk create my_agent選取
gemini-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 8000在 ADK 網頁 UI 輸入多躍圖問題:
Who did Dana transfer money to, and what were the amounts?代理會呼叫
fingraph_query_data_tool工具,將問題傳送至QueryDataREST API,並將graph_ids設為FinGraph。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?QueryData 根據
fingraph-assistant中的 GQL 範本,找出轉帳至封鎖帳戶且金額至少為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 工具的要求和回應酬載。在導覽窗格的「事件」分頁中,展開 functionResponse 即可檢查產生的 FinGraph GQL 查詢 (generatedQuery)、queryResult、intentExplanation、disambiguationQuestion 和 naturalLanguageAnswer。QueryData REST API 會以駝峰式大小寫傳回這些欄位名稱。
提高回覆準確度
您可以新增 GQL 範本、facet 和值搜尋,持續提升 QueryData 回覆的準確度。使用脈絡工程代理,為 Spanner 資料庫中的 FinGraph 屬性圖生成及評估更新後的脈絡,然後在 Spanner Studio 中上傳更新後的脈絡集檔案。詳情請參閱「在 Spanner Studio 中管理情境集」。
多個代理
在開發環境中,您可以在 tools.yaml 檔案 (例如 fingraph_query_data_tool_v1 和 fingraph_query_data_tool_v2) 中定義多個 HTTP 工具,對多個 Spanner Graph 情境集執行 A/B 測試。每個工具的要求主體都會將 graph_ids 設為 ["FinGraph"],並設定不同的 context_set_id。
清除所用資源
完成本教學課程後,請刪除建立的資源,以免繼續計費。
刪除脈絡資料集
刪除 Spanner 資料庫或執行個體前,請先刪除 fingraph-assistant 脈絡資料集:
前往 Google Cloud 控制台的「Spanner」頁面。
從清單中選取執行個體,然後選取 Spanner 資料庫。
在導覽選單中,點選「Spanner Studio」。
在「Explorer」窗格中,點選
fingraph-assistant旁邊的「查看動作」。按一下「刪除情境組合」,在確認欄位中輸入
fingraph-assistant,然後點選「確認」。
刪除資料庫和執行個體
如要刪除 FinGraph 屬性圖、Spanner 資料庫和 Spanner 執行個體,請按照「設定及查詢 Spanner Graph:清理」中的步驟操作。
後續步驟
- 進一步瞭解 Spanner Graph 的情境集。
- 瞭解如何使用脈絡工程代理建立脈絡資料集。
- 瞭解如何定義資料庫資料來源的編寫情境。