將 QueryData 整合至應用程式

本教學課程說明如何使用 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 查詢,方法是呼叫 QueryData REST API,並在 spanner_reference 中指定 graph_ids。
  • 在 MCP Toolbox 中使用自訂 HTTP 工具呼叫 QueryData REST API,將 QueryData 整合至應用程式。
  • 使用查詢範本、查詢 facet 和 GRAPH_TABLE 值搜尋查詢,以圖表資料建立 LLM 回覆的基準。

費用

在本文件中,您會使用下列 Google Cloud計費元件:

您可以使用 Pricing Calculator,根據預測用量估算費用。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

完成本文所述工作後,請刪除建立的資源,避免繼續計費。詳情請參閱「清除所用資源」一節。

事前準備

建立情境集前,請先完成下列前置作業:

啟用必要服務

為專案啟用下列服務:

準備 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 設定指南完成下列步驟:

  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. 在「Explorer」窗格中,點選「Context sets」旁邊的「查看動作」。

  5. 按一下「建立情境組合」。

  6. 在「Context set name」(情境組合名稱) 欄位中,輸入 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 的構成要素 (在您的商業邏輯中,這代表將 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 |
    +-------------------+------------------------+-----------------+-----------------+
    
  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」定義為轉帳金額達 200 以上,且轉入遭封鎖帳戶 (dst.is_blocked = true)。

如要生成 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 ?"
          }
        }
      ]
    }
    

生成 facet 和值搜尋背景資訊

在本節中,您會將 GQL facet 和兩個 GRAPH_TABLE 值搜尋查詢新增至 context_set.json。您在上一節新增的範本,可回答與「找出 Alex 發起的所有高風險轉移作業」結構相同的問題。Facet 會擷取封鎖帳戶模式,讓 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. 在「Explorer」窗格中,點選 fingraph-assistant 情境集旁邊的「查看動作」。

  5. 按一下「編輯情境組合」。

  6. 選用:編輯「Context set description」(情境集說明)。

  7. 按一下「Upload context set file」(上傳情境集檔案) 專區中的「Browse」(瀏覽),然後選取您產生的 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 與應用程式整合

在本節中,您將使用 Agent Development Kit (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. 使用 MCP Toolbox Python SDK 建立 ADK 應用程式,叫用 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 網路伺服器:

    adk web --port 8000
  8. 在 ADK 網頁 UI 輸入多躍圖問題:

    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?
    

    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 脈絡資料集:

  1. 前往 Google Cloud 控制台的「Spanner」頁面。

    前往「Spanner」頁面

  2. 從清單中選取執行個體,然後選取 Spanner 資料庫。

  3. 在導覽選單中,點選「Spanner Studio」。

  4. 在「Explorer」窗格中,點選 fingraph-assistant 旁邊的「查看動作」。

  5. 按一下「刪除情境組合」,在確認欄位中輸入 fingraph-assistant,然後點選「確認」。

刪除資料庫和執行個體

如要刪除 FinGraph 屬性圖、Spanner 資料庫和 Spanner 執行個體,請按照「設定及查詢 Spanner Graph:清理」中的步驟操作。

後續步驟