本教程介绍了如何使用 Google Cloud 控制台在 Spanner Graph 中设置和使用 QueryData,并将其与您的应用集成。您将学习如何设置 FinGraph 属性图、使用上下文工程智能体构建 Graph Query Language (GQL) 上下文集文件、在 Spanner Studio 中创建上下文集、通过调用 Conversational Analytics API 中的 QueryData 方法(配置了 graph_ids)来测试 QueryData,以及在 MCP Toolbox 中使用自定义 HTTP 工具将智能体应用连接到 QueryData。
如需了解详情,请参阅 QueryData 概览。
目标
- 创建
FinGraph属性图表架构,并使用示例图表数据填充该架构。 - 使用上下文工程智能体为
FinGraph构建上下文集文件。 - 在 Spanner Studio 中创建上下文集并上传上下文集文件。
- 通过调用
QueryDataREST API(在spanner_reference中指定graph_ids)来测试 QueryData 并生成 GQL 查询。 - 在 MCP Toolbox 中使用调用
QueryDataREST API 的自定义 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 Editor (
roles/dataplex.catalogEditor) 或 Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 角色。如需了解详情,请参阅上下文集权限。 - 在项目级层向 IAM 用户授予所需数据库的角色和权限。
创建 FinGraph 架构并插入图表数据
本教程使用 FinGraph 财务属性图数据集,该数据集对通过 Owns (PersonOwnAccount) 和 Transfers (AccountTransferAccount) 边连接的 Person 和 Account 节点进行建模。
如需在 Spanner 数据库中创建 FinGraph 架构并填充图谱数据,请完成 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。
创建一个名为
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的构成要素(在您的业务逻辑中,这意味着向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;这将返回 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定义为向已屏蔽账号 (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 ?" } } ] }
生成分面和值搜索上下文
在本部分中,您将向 context_set.json 添加一个 GQL 分面和两个 GRAPH_TABLE 值搜索查询。您在上一部分中添加的模板可回答与“查找由 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
在本部分中,您需要将 context_set.json 文件上传到 Spanner Studio 中设置的 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 向被屏蔽账号
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 与您的应用集成
在本部分中,您将使用智能体开发套件 (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 工具,供应用连接。 设置应用默认凭证 (ADC):
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"创建一个 ADK 应用,该应用使用 MCP Toolbox Python SDK 调用
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 Web 服务器:adk web --port 8000在 ADK 网页界面中输入一个多跳图问题:
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?根据
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 Web 界面,您可以检查 fingraph_query_data_tool 工具的请求和响应载荷。在导航窗格的事件标签页中,展开 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 的上下文集。
- 了解如何使用上下文工程智能体构建上下文集。
- 了解如何为数据库数据源定义编写的上下文。