Mengintegrasikan QueryData dengan aplikasi

Tutorial ini menjelaskan cara menyiapkan dan menggunakan QueryData di Spanner Graph menggunakan konsol Google Cloud dan mengintegrasikannya dengan aplikasi Anda. Anda akan mempelajari cara menyiapkan grafik properti FinGraph, membangun file set konteks Graph Query Language (GQL) menggunakan agen rekayasa konteks, membuat set konteks di Spanner Studio, menguji QueryData dengan memanggil metode QueryData di Analisis Percakapan API dengan graph_ids yang dikonfigurasi, dan menggunakan alat HTTP kustom di MCP Toolbox untuk menghubungkan aplikasi agen ke QueryData.

Untuk mengetahui informasi selengkapnya, lihat Ringkasan QueryData.

Tujuan

  • Buat skema grafik properti FinGraph dan isi dengan data grafik sampel.
  • Buat file set konteks untuk FinGraph menggunakan agen rekayasa konteks.
  • Buat set data konteks dan upload file set data konteks di Spanner Studio.
  • Uji QueryData dan buat kueri GQL dengan memanggil REST API QueryData dengan graph_ids yang ditentukan di spanner_reference.
  • Integrasikan QueryData dengan aplikasi Anda menggunakan alat HTTP kustom di MCP Toolbox yang memanggil REST API QueryData.
  • Lakukan grounding respons LLM dalam data grafik Anda menggunakan template kueri, faset kueri, dan kueri penelusuran nilai GRAPH_TABLE.

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Untuk menghindari penagihan berkelanjutan, hapus resource yang Anda buat setelah menyelesaikan tugas dalam dokumen ini. Untuk informasi selengkapnya, lihat Pembersihan.

Sebelum memulai

Selesaikan prasyarat berikut sebelum membuat set konteks:

Mengaktifkan layanan yang diperlukan

Aktifkan layanan berikut untuk project Anda:

Menyiapkan instance Spanner

Peran dan izin yang diperlukan

  • Tambahkan akun pengguna atau layanan IAM ke instance. Untuk mengetahui informasi selengkapnya, lihat Menerapkan peran IAM.
  • Berikan peran roles/spanner.databaseReader, roles/serviceusage.serviceUsageConsumer, dan roles/geminidataanalytics.queryDataUser kepada pengguna IAM di level project. Untuk mengetahui informasi selengkapnya, lihat Menambahkan binding kebijakan IAM untuk project.
  • Untuk membuat, mengupload, dan mengelola set konteks, berikan peran Dataplex Catalog Editor (roles/dataplex.catalogEditor) atau Dataplex Catalog Admin (roles/dataplex.catalogAdmin) kepada pengguna IAM di level project. Untuk mengetahui informasi selengkapnya, lihat Izin set konteks.
  • Berikan peran dan izin kepada pengguna IAM di level project untuk database yang diperlukan.

Membuat skema FinGraph dan menyisipkan data grafik

Tutorial ini menggunakan set data grafik properti keuangan FinGraph, yang memodelkan node Person dan Account yang terhubung oleh edge Owns (PersonOwnAccount) dan Transfers (AccountTransferAccount).

Untuk membuat skema FinGraph dan mengisi data grafik di database Spanner, selesaikan langkah-langkah berikut dari panduan penyiapan Spanner Graph:

  1. Ikuti Membuat database grafik menggunakan skema untuk membuat tabel Person, Account, PersonOwnAccount, dan AccountTransferAccount serta definisi grafik properti FinGraph.
  2. Ikuti Menyisipkan data grafik untuk menyisipkan contoh orang (Alex, Dana, dan Lee), akun (7, 16, dan 20), edge kepemilikan akun, dan edge transfer uang ke FinGraph.

Membuat set data konteks

Buat set data konteks kosong bernama fingraph-assistant. Nantinya dalam tutorial ini, Anda akan mengupload file set konteks ke bucket tersebut.

  1. Di konsol Google Cloud , buka halaman Spanner.

    Buka Spanner

  2. Pilih instance Anda dari daftar, lalu pilih database yang berisi FinGraph.

  3. Di menu navigasi, klik Spanner Studio.

  4. Di panel Explorer, di samping Context sets, klik View actions.

  5. Klik Create context set.

  6. Di kolom Context set name, masukkan fingraph-assistant.

  7. Klik Create.

Menguji QueryData tanpa konteks

Di bagian ini, Anda akan memanggil REST API QueryData untuk membuat kueri GQL untuk pertanyaan bahasa alami tanpa set konteks. Tanpa konteks, QueryData dapat menjawab pertanyaan yang dipetakan langsung ke skema FinGraph, tetapi tidak dapat menafsirkan terminologi bisnis kustom seperti high-risk transfers atau menyelesaikan perbedaan format nilai seperti Czech Republic versus Czech_Republic.

  1. Di terminal Anda, tetapkan variabel lingkungan berikut:

    export PROJECT_ID="PROJECT_ID"
    export INSTANCE_ID="INSTANCE_ID"
    export DATABASE_ID="DATABASE_ID"
    

    Ganti kode berikut:

    • PROJECT_ID: Project ID Google Cloud Anda.
    • INSTANCE_ID: ID instance Spanner Anda.
    • DATABASE_ID: ID database yang berisi FinGraph.
  2. Buat skrip bantuan bernama query_data.sh yang mengirimkan pertanyaan ke REST API QueryData dengan graph_ids ditetapkan ke FinGraph. Jika variabel lingkungan CONTEXT_SET_ID ditetapkan, skrip juga akan mengirimkan ID set konteks Anda:

    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
    

    Skrip akan menyisipkan pertanyaan Anda ke dalam isi permintaan apa adanya, jadi jangan gunakan tanda petik ganda (") dalam pertanyaan.

  3. Ajukan pertanyaan yang dipetakan langsung ke skema FinGraph:

    ./query_data.sh "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts."
    

    Dalam respons, tinjau kolom generatedQuery dan queryResult. Untuk pertanyaan yang tidak ambigu ini, QueryData menghasilkan kueri GQL yang mirip dengan berikut ini:

    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;
    

    Tindakan ini akan menampilkan hasil yang mirip dengan berikut ini:

    +----------------+----------------------+-----------------+
    | recipient_name | recipient_account_id | transfer_amount |
    +----------------+----------------------+-----------------+
    | Alex           | 7                    | 500             |
    | Lee            | 16                   | 200             |
    +----------------+----------------------+-----------------+
    
  4. Ajukan pertanyaan yang menyertakan istilah bisnis high-risk transfers:

    ./query_data.sh "Find all high-risk transfers initiated by Alex"
    

    Karena skema FinGraph tidak menentukan apa yang dimaksud dengan high-risk transfer (yang dalam logika bisnis Anda berarti transfer sebesar 200 atau lebih ke rekening yang diblokir dengan is_blocked = true), QueryData tidak menerapkan filter rekening yang diblokir dan nilai minimum jumlah atau menerapkan interpretasinya sendiri terhadap istilah tersebut. Misalnya, QueryData mungkin membuat nilai minimum jumlah yang tidak menampilkan baris, atau mungkin mengabaikan istilah tersebut dan menghasilkan kueri yang mirip dengan berikut ini:

    -- 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;
    

    Tindakan ini akan menampilkan kedua transfer Alex, termasuk transfer 100 yang tidak memenuhi nilai minimum:

    +-------------------+------------------------+-----------------+-----------------+
    | source_account_id | destination_account_id | transfer_amount | order_number    |
    +-------------------+------------------------+-----------------+-----------------+
    | 7                 | 16                     | 300             | 304330008004315 |
    | 7                 | 16                     | 100             | 304120005529714 |
    +-------------------+------------------------+-----------------+-----------------+
    
  5. Ajukan pertanyaan yang merujuk ke suatu negara:

    ./query_data.sh "Find accounts owned by people from Czech Republic"
    

    Tanpa penautan konteks atau nilai, QueryData akan menghasilkan kueri GQL yang memfilter 'Czech Republic' dengan spasi. Karena properti Person.country di FinGraph menyimpan nilai sebagai 'Czech_Republic' dengan garis bawah, kueri tidak menampilkan baris:

    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;
    

Membuat konteks untuk set data konteks

Di bagian ini, Anda akan menyiapkan lingkungan lokal dan menggunakan agen rekayasa konteks untuk membuat file set konteks (context_set.json) untuk grafik properti FinGraph di database Spanner Anda.

Menyiapkan lingkungan Anda

Untuk menyiapkan lingkungan Anda untuk agen rekayasa konteks, lakukan langkah-langkah berikut:

  1. Instal Antigravity CLI. Untuk mengetahui informasi selengkapnya, lihat Memulai Antigravity CLI.
  2. Menginstal Google Cloud CLI.
  3. Siapkan Kredensial Default Aplikasi (ADC). Jalankan perintah berikut di terminal Anda untuk melakukan autentikasi:

    gcloud auth application-default login
  4. Instal agen rekayasa konteks.

  5. Di terminal Anda, mulai Antigravity CLI:

    agy
  6. Siapkan koneksi database untuk database Spanner Anda. Masukkan perintah yang secara eksplisit menentukan bahwa Anda membuat konteks untuk grafik properti di database Spanner, dan menyertakan nama grafik properti FinGraph agar agen memicu alur kerja rekayasa konteks khusus GQL:

    Help me set up the database connection for the FinGraph property graph in my Spanner database.
    

    Ikuti petunjuk yang diberikan oleh agen untuk membuat autoctx/tools.yaml dan autoctx/state.md. Kemudian, buka autoctx/state.md dan pastikan bagian ## Active Database berisi baris - **Graph Ids**: ["FinGraph"]. Agen rekayasa konteks membaca nama grafik properti dari baris ini saat membuat konfigurasi evaluasi. Untuk mengetahui informasi selengkapnya tentang tools.yaml, lihat dokumentasi MCP Toolbox.

  7. Untuk memuat ulang konfigurasi setelah autoctx/tools.yaml dibuat, jalankan perintah berikut di Antigravity CLI:

    /mcp
  8. Pilih toolbox, lalu pilih Restart.

  9. Pastikan MCP Toolbox dan plugin agen rekayasa konteks terhubung dan siap digunakan:

    /mcp

Membuat konteks template GQL

Untuk mengatasi masalah QueryData yang tidak mengenali istilah bisnis high-risk transfers, tentukan high-risk transfers dalam file set konteks sebagai transfer sebesar 200 atau lebih yang dikirim ke akun yang diblokir (dst.is_blocked = true).

Untuk membuat konteks template GQL, lakukan langkah-langkah berikut:

  1. Masukkan perintah berikut ke dalam infrastruktur pengelola agen, yang menentukan bahwa FinGraph adalah grafik properti di database Spanner Anda:

    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. Agen mengonversi input Anda menjadi template GQL berparameter yang digeneralisasi di seluruh nama orang. Untuk mengetahui informasi selengkapnya, lihat Ringkasan set konteks.

  3. Tinjau template kueri GQL yang dihasilkan, lalu berikan perintah kepada agen dengan Save it to context_set.json. Agen akan membuat context_set.json di direktori Anda dengan konten berikut:

    {
      "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 ?"
          }
        }
      ]
    }
    

Membuat konteks penelusuran faset dan nilai

Di bagian ini, Anda akan menambahkan faset GQL dan dua kueri penelusuran nilai GRAPH_TABLE ke context_set.json. Template yang Anda tambahkan di bagian sebelumnya menjawab pertanyaan yang memiliki struktur yang sama dengan "Temukan semua transfer berisiko tinggi yang dimulai oleh Alex". Aspek ini menangkap pola akun yang diblokir sehingga QueryData juga dapat menerapkannya ke pertanyaan yang tidak cocok dengan template, seperti "Temukan semua transfer uang yang melibatkan akun yang diblokir". Penelusuran nilai memungkinkan QueryData memetakan frasa nilai seperti Czech Republic ke nilai tersimpan Czech_Republic di Person.country, dan mencocokkan nama panggilan akun di Account.nick_name tanpa memandang huruf besar/kecil.

  1. Masukkan perintah berikut ke dalam infrastruktur pengelola agen, yang menentukan bahwa FinGraph adalah grafik properti di database Spanner Anda:

    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. Tinjau file context_set.json yang telah diperbarui, yang kini berisi template GQL, faset GQL, dan definisi penelusuran nilai:

    {
      "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"
        }
      ]
    }
    

    Setiap penelusuran nilai menggunakan operator GRAPH_TABLE untuk mencocokkan label node di FinGraph dan menampilkan nilai properti yang disimpan, lokasi properti (FinGraph.Person.country), jenis konsep, jarak 0 untuk kecocokan, dan konteks JSON kosong. Untuk mengetahui informasi selengkapnya, lihat Kueri penelusuran nilai.

Mengupload file set konteks ke QueryData

Di bagian ini, Anda akan mengupload file context_set.json ke set konteks fingraph-assistant di Spanner Studio.

  1. Di konsol Google Cloud , buka halaman Spanner.

    Buka Spanner

  2. Pilih instance Anda dari daftar, lalu pilih database Spanner Anda.

  3. Di menu navigasi, klik Spanner Studio.

  4. Di panel Explorer, di samping set konteks fingraph-assistant, klik View actions.

  5. Klik Edit context set.

  6. Opsional: Edit Deskripsi set konteks.

  7. Klik Browse di bagian Upload context set file, lalu pilih file context_set.json yang Anda buat.

  8. Klik Simpan.

Membuat kueri GQL menggunakan QueryData

Di bagian ini, Anda akan memanggil REST API QueryData dengan konteks fingraph-assistant yang ditetapkan untuk memverifikasi bahwa QueryData menerjemahkan istilah bisnis seperti high-risk transfers secara akurat dan me-resolve Czech Republic ke Czech_Republic dalam kueri GQL.

  1. Temukan ID set konteks untuk fingraph-assistant. Untuk mengetahui petunjuknya, lihat Menemukan ID set konteks.
  2. Tetapkan variabel lingkungan CONTEXT_SET_ID agar query_data.sh mengirimkan set konteks Anda:

    export CONTEXT_SET_ID="CONTEXT_SET_ID"
    

    Ganti CONTEXT_SET_ID dengan ID set konteks lengkap, seperti projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

  3. Ajukan pertanyaan tentang transfer berisiko tinggi lagi:

    ./query_data.sh "Find all high-risk transfers initiated by Alex"
    

    Kueri GQL yang dihasilkan kini menerapkan filter rekening tujuan yang diblokir (is_blocked: true) dan nilai minimum jumlah (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;
    

    Tindakan ini mengecualikan transfer 100 oleh Alex ke akun yang diblokir 16 dan menampilkan hasil yang mirip dengan berikut ini:

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 300             |
    +------------------------+-----------------+
    
  4. Ajukan pertanyaan serupa untuk Dana:

    ./query_data.sh "What are the high-risk transfers initiated by Dana?"
    

    Karena template GQL di context_set.json diparameterisasi ({name: ?}), QueryData menerapkan definisi high-risk transfers yang sama ke 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;
    

    Tindakan ini mengecualikan transfer 500 Dana ke akun 7 yang tidak diblokir dan menampilkan hasil yang mirip dengan berikut ini:

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 200             |
    +------------------------+-----------------+
    
  5. Ajukan pertanyaan negara lagi:

    ./query_data.sh "Find accounts owned by people from Czech Republic"
    

    QueryData menjalankan penelusuran nilai Person country, menautkan Czech Republic ke nilai tersimpan Czech_Republic, dan membuat kueri yang mirip dengan berikut ini:

    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;
    

    Tindakan ini akan menampilkan hasil yang mirip dengan berikut ini:

    +------------+------------+----------------+
    | owner_name | account_id | nick_name      |
    +------------+------------+----------------+
    | Dana       | 20         | Rainy Day Fund |
    +------------+------------+----------------+
    
  6. Ajukan pertanyaan yang menggunakan faset akun yang diblokir:

    ./query_data.sh "Find all money transfers involving a blocked account."
    

    QueryData menggunakan faset untuk mencocokkan transfer di kedua arah yang melibatkan akun yang diblokir 16, dan menampilkan empat transfer.

Mengintegrasikan QueryData dengan aplikasi Anda

Di bagian ini, Anda akan membuat aplikasi agen data percakapan untuk FinGraph menggunakan Agent Development Kit (ADK), MCP Toolbox, dan set konteks fingraph-assistant Anda. Untuk mengaktifkan pembuatan kueri GQL untuk Spanner Graph, Anda harus menentukan alat HTTP kustom dalam file tools.yaml yang memanggil REST API QueryData dengan graph_ids yang ditetapkan di spanner_reference.database_reference.

  1. Download MCP Toolbox versi 1.4.0 atau yang lebih baru. MCP Toolbox mengekspos REST API QueryData sebagai alat MCP yang dapat dihubungkan oleh aplikasi.
  2. Siapkan Kredensial Default Aplikasi (ADC):

    gcloud auth application-default login
  3. Buat file konfigurasi tools.yaml yang menentukan sumber HTTP untuk Analisis Percakapan API dan alat HTTP yang memanggil metode QueryData. Pastikan untuk menentukan graph_ids (disetel ke ["FinGraph"]) di bagian spanner_reference.database_reference dalam isi permintaan:

    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 mengganti referensi ${...} dengan nilai variabel lingkungan yang sesuai saat memuat tools.yaml, dan mengganti {{json .query}} dengan pertanyaan yang dikirim agen ke alat, yang dienkode sebagai string JSON.

  4. Di terminal tempat Anda menjalankan MCP Toolbox, tetapkan variabel lingkungan yang dirujuk oleh 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)"
    

    Ganti kode berikut:

    • PROJECT_ID: Project ID Google Cloud Anda.
    • INSTANCE_ID: ID instance Spanner Anda.
    • DATABASE_ID: ID database Spanner yang berisi FinGraph.
    • CONTEXT_SET_ID: ID set konteks lengkap fingraph-assistant.
  5. Jalankan server MCP Toolbox dengan file tools.yaml:

    ./toolbox --config "tools.yaml"
  6. Buat aplikasi ADK yang memanggil alat fingraph_query_data_tool menggunakan Python SDK MCP Toolbox:

    1. Buat dan ubah ke direktori untuk aplikasi, seperti fingraph-assistant-app:

      mkdir fingraph-assistant-app
      cd fingraph-assistant-app
    2. Buat lingkungan virtual dan instal paket yang diperlukan:

      python3 -m venv .venv
      source .venv/bin/activate
      pip install toolbox-core
      pip install google-genai
      pip install google-adk
    3. Buat agen ADK:

      adk create my_agent
    4. Pilih model gemini-2.5-flash, pilih Google AI, lalu masukkan kunci Gemini API Anda. Untuk informasi selengkapnya, lihat Menggunakan kunci Gemini API.

    5. Ganti konten my_agent/agent.py dengan kode aplikasi contoh Financial Graph Assistant berikut:

      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. Mulai server web ADK di http://127.0.0.1:8000:

    adk web --port 8000
  8. Masukkan pertanyaan grafik multi-hop di UI web ADK:

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

    Agen memanggil alat fingraph_query_data_tool, yang mengirimkan pertanyaan ke REST API QueryData dengan graph_ids ditetapkan ke FinGraph. QueryData menjalankan kueri GQL yang dihasilkan, dan agen menampilkan respons yang mirip dengan berikut ini:

    Dana transferred money from account 20 to the following recipients:
    
    * Alex (account 7): 500
    * Lee (account 16): 200
    
  9. Masukkan pertanyaan yang menggunakan template GQL high-risk transfers yang Anda tambahkan ke set konteks:

    What are the high-risk transfers initiated by Alex?
    

    Berdasarkan template GQL di fingraph-assistant, QueryData mengidentifikasi transfer minimal 200 ke rekening yang diblokir, dan agen menampilkan respons yang mirip dengan berikut ini:

    Here is the high-risk transfer initiated by Alex (transfers of 200 or more to a blocked account):
    
    * Blocked destination account 16: amount 300
    

Melakukan iterasi performa agen

UI web ADK memungkinkan Anda memeriksa payload permintaan dan respons dari alat fingraph_query_data_tool. Di tab Event di panel navigasi, luaskan functionResponse untuk memeriksa kueri GQL FinGraph yang dihasilkan (generatedQuery), queryResult, intentExplanation, disambiguationQuestion, dan naturalLanguageAnswer. REST API QueryData menampilkan nama kolom ini dalam camelCase.

Mempertajam akurasi respons

Anda dapat terus meningkatkan akurasi respons dari QueryData dengan menambahkan template GQL, faset, dan penelusuran nilai. Gunakan agen rekayasa konteks untuk membuat dan mengevaluasi konteks yang diperbarui untuk grafik properti FinGraph di database Spanner Anda, lalu upload file set konteks yang diperbarui di Spanner Studio. Untuk mengetahui informasi selengkapnya, lihat Mengelola set konteks di Spanner Studio.

Beberapa agen

Di lingkungan pengembangan, Anda dapat melakukan pengujian A/B pada beberapa set konteks Spanner Graph dengan menentukan beberapa alat HTTP dalam file tools.yaml (seperti fingraph_query_data_tool_v1 dan fingraph_query_data_tool_v2). Isi permintaan setiap alat menetapkan graph_ids ke ["FinGraph"] dan context_set_id yang berbeda.

Pembersihan

Untuk menghindari penagihan berkelanjutan, hapus resource yang Anda buat setelah menyelesaikan tutorial ini.

Menghapus set konteks

Sebelum Anda menghapus database atau instance Spanner, hapus set konteks fingraph-assistant:

  1. Di konsol Google Cloud , buka halaman Spanner.

    Buka Spanner

  2. Pilih instance Anda dari daftar, lalu pilih database Spanner Anda.

  3. Di menu navigasi, klik Spanner Studio.

  4. Di panel Explorer, di samping fingraph-assistant, klik View actions.

  5. Klik Delete context set, masukkan fingraph-assistant di kolom konfirmasi, lalu klik Confirm.

Menghapus database dan instance

Untuk menghapus grafik properti FinGraph, database Spanner, dan instance Spanner, ikuti langkah-langkah di Menyiapkan dan mengkueri Spanner Graph: Pembersihan.

Langkah berikutnya