将 QueryData 与应用集成

本教程介绍了如何使用 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 中创建上下文集并上传上下文集文件。
  • 通过调用 QueryData REST API(在 spanner_reference 中指定 graph_ids)来测试 QueryData 并生成 GQL 查询。
  • 在 MCP Toolbox 中使用调用 QueryData REST API 的自定义 HTTP 工具,将 QueryData 与您的应用集成。
  • 使用查询模板、查询分面和 GRAPH_TABLE 值搜索查询,将 LLM 回答与图数据进行接地。

费用

在本文档中,您将使用 Google Cloud的以下收费组件:

您可使用价格计算器根据您的预计使用量来估算费用。

新 Google Cloud 用户可能有资格申请免费试用。

为避免继续计费,请在完成本文档中的任务后删除您创建的资源。如需了解详情,请参阅清理。

准备工作

在创建上下文集之前,请先完成以下前提条件:

启用必需服务

为您的项目启用以下服务:

准备 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 设置指南中的以下步骤:

  1. 按照使用架构创建图数据库中的说明创建 Person、Account、PersonOwnAccount 和 AccountTransferAccount 表以及 FinGraph 属性图定义。
  2. 按照插入图表数据中的说明,将示例人员(Alex、Dana 和 Lee)、账号(7、16 和 20)、账号所有权边和转账边插入 FinGraph。

创建上下文集

创建一个名为 fingraph-assistant 的空上下文集。在本教程的后面部分,您需要将上下文集文件上传到该存储桶。

  1. 在 Google Cloud 控制台中,前往 Spanner 页面。

    转到 Spanner

  2. 从列表中选择您的实例,然后选择包含 FinGraph 的数据库。

  3. 在导航菜单中,点击 Spanner Studio。

  4. 在探索器窗格中,点击上下文集旁边的查看操作。

  5. 点击创建情境集。

  6. 在上下文集名称字段中,输入 fingraph-assistant。

  7. 点击创建。

测试 QueryData(不使用上下文)

在本部分中,您将调用 QueryData REST API,为没有上下文集的自然语言问题生成 GQL 查询。在没有上下文的情况下,QueryData 可以回答直接映射到 FinGraph 架构的问题,但无法解读自定义业务术语(例如 high-risk transfers),也无法解决值格式差异(例如 Czech Republic 与 Czech_Republic)。

  1. 在终端中,设置以下环境变量:

    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。
  2. 创建一个名为 query_data.sh 的辅助脚本,用于向 QueryData REST 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
    

    该脚本会将您的问题原样插入到请求正文中,因此请勿在问题中使用双引号 (")。

  3. 提出一个直接映射到 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             |
    +----------------+----------------------+-----------------+
    
  4. 提出包含业务术语“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 |
    +-------------------+------------------------+-----------------+-----------------+
    
  5. 提出一个涉及国家/地区的问题:

    ./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)。

设置环境

如需为上下文工程代理设置环境,请执行以下步骤:

  1. 安装 Antigravity CLI。如需了解详情,请参阅 Antigravity CLI 使用入门。
  2. 安装 Google Cloud CLI。
  3. 设置应用默认凭据 (ADC)。在终端中运行以下命令进行身份验证:

    gcloud auth application-default login
  4. 安装内容相关引擎代理。

  5. 在终端中,启动 Antigravity CLI:

    agy
  6. 为 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 文档。

  7. 如需在创建 autoctx/tools.yaml 后重新加载配置,请在 Antigravity CLI 中运行以下命令:

    /mcp
  8. 选择 toolbox,然后选择 Restart。

  9. 验证 MCP Toolbox 和上下文工程智能体插件是否已连接并可供使用:

    /mcp

生成 GQL 模板上下文

为了解决 QueryData 无法识别业务术语high-risk transfers的问题,请在上下文集文件中将high-risk transfers定义为向已屏蔽账号 (dst.is_blocked = true) 发送的200或更多转账。

如需生成 GQL 模板上下文,请执行以下步骤:

  1. 在智能体框架中输入以下提示,指定 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;
  2. 智能体会将您的输入转换为参数化 GQL 模板,该模板可泛化到各种人名。如需了解详情,请参阅上下文集概览。

  3. 查看生成的 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 上的账号昵称(不区分大小写)。

  1. 在智能体框架中输入以下提示,指定 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.
    
  2. 查看更新后的 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 上下文。

  1. 在 Google Cloud 控制台中,前往 Spanner 页面。

    转到 Spanner

  2. 从列表中选择您的实例,然后选择您的 Spanner 数据库。

  3. 在导航菜单中,点击 Spanner Studio。

  4. 在探索器窗格中,点击 fingraph-assistant 上下文集旁边的查看操作。

  5. 点击修改上下文集。

  6. 可选:修改上下文集说明。

  7. 点击上传上下文集文件部分中的浏览,然后选择您生成的 context_set.json 文件。

  8. 点击保存。

使用 QueryData 生成 GQL 查询

在本部分中,您将使用 fingraph-assistant 上下文集调用 QueryData REST API,以验证 QueryData 是否能准确转换业务术语(例如 high-risk transfers),并在 GQL 查询中将 Czech Republic 解析为 Czech_Republic。

  1. 查找 fingraph-assistant 的上下文集 ID。如需查看相关说明,请参阅查找上下文集 ID。
  2. 设置 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。

  3. 再次询问高风险转移问题:

    ./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             |
    +------------------------+-----------------+
    
  4. 针对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             |
    +------------------------+-----------------+
    
  5. 再次询问国家/地区问题:

    ./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 |
    +------------+------------+----------------+
    
  6. 提出一个使用“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。

  1. 下载 MCP Toolbox 1.4.0 或更高版本。MCP Toolbox 将 QueryData REST API 公开为 MCP 工具,供应用连接。
  2. 设置应用默认凭证 (ADC):

    gcloud auth application-default login
  3. 创建一个 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 字符串)。

  4. 在运行 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。
  5. 使用 tools.yaml 文件运行 MCP Toolbox 服务器:

    ./toolbox --config "tools.yaml"
  6. 创建一个 ADK 应用,该应用使用 MCP Toolbox Python SDK 调用 fingraph_query_data_tool 工具:

    1. 为应用创建目录并切换到该目录,例如 fingraph-assistant-app:

      mkdir fingraph-assistant-app
      cd fingraph-assistant-app
    2. 创建虚拟环境并安装所需的软件包:

      python3 -m venv .venv
      source .venv/bin/activate
      pip install toolbox-core
      pip install google-genai
      pip install google-adk
    3. 创建 ADK 智能体:

      adk create my_agent
    4. 选择 gemini-2.5-flash 模型,选择 Google AI,然后输入您的 Gemini API 密钥。如需了解详情,请参阅使用 Gemini API 密钥。

    5. 将 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]),
      )
      
  7. 在 http://127.0.0.1:8000 启动 ADK Web 服务器:

    adk web --port 8000
  8. 在 ADK 网页界面中输入一个多跳图问题:

    Who did Dana transfer money to, and what were the amounts?
    

    智能体调用 fingraph_query_data_tool 工具,该工具会将问题发送到 QueryData REST API,并将 graph_ids 设置为 FinGraph。QueryData 会运行生成的 GQL 查询,然后代理会返回类似于以下内容的回答:

    Dana transferred money from account 20 to the following recipients:
    
    * Alex (account 7): 500
    * Lee (account 16): 200
    
  9. 输入一个问题,该问题使用您添加到上下文集的 high-risk transfers GQL 模板:

    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 上下文集:

  1. 在 Google Cloud 控制台中,前往 Spanner 页面。

    转到 Spanner

  2. 从列表中选择您的实例,然后选择您的 Spanner 数据库。

  3. 在导航菜单中,点击 Spanner Studio。

  4. 在探索器窗格中,点击 fingraph-assistant 旁边的查看操作。

  5. 点击删除上下文集,在确认字段中输入 fingraph-assistant,然后点击确认。

删除数据库和实例

如需删除 FinGraph 属性图、Spanner 数据库和 Spanner 实例,请按照设置和查询 Spanner Graph:清理中的步骤操作。

后续步骤