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
FinGraphdan isi dengan data grafik sampel. - Buat file set konteks untuk
FinGraphmenggunakan 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
QueryDatadengangraph_idsyang ditentukan dispanner_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
- Pastikan instance Spanner tersedia. Untuk mengetahui informasi selengkapnya, lihat Membuat instance.
- Pastikan Anda membuat database di instance tempat Anda akan membuat tabel. Untuk informasi selengkapnya, lihat Membuat database pada 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, danroles/geminidataanalytics.queryDataUserkepada 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:
- Ikuti Membuat database grafik menggunakan skema untuk membuat tabel
Person,Account,PersonOwnAccount, danAccountTransferAccountserta definisi grafik propertiFinGraph. - Ikuti Menyisipkan data grafik untuk menyisipkan contoh orang (
Alex,Dana, danLee), akun (7,16, dan20), edge kepemilikan akun, dan edge transfer uang keFinGraph.
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.
Di konsol Google Cloud , buka halaman Spanner.
Pilih instance Anda dari daftar, lalu pilih database yang berisi
FinGraph.Di menu navigasi, klik Spanner Studio.
Di panel Explorer, di samping Context sets, klik View actions.
Klik Create context set.
Di kolom Context set name, masukkan
fingraph-assistant.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.
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 berisiFinGraph.
Buat skrip bantuan bernama
query_data.shyang mengirimkan pertanyaan ke REST APIQueryDatadengangraph_idsditetapkan keFinGraph. Jika variabel lingkunganCONTEXT_SET_IDditetapkan, 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.shSkrip akan menyisipkan pertanyaan Anda ke dalam isi permintaan apa adanya, jadi jangan gunakan tanda petik ganda (
") dalam pertanyaan.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
generatedQuerydanqueryResult. 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 | +----------------+----------------------+-----------------+Ajukan pertanyaan yang menyertakan istilah bisnis
high-risk transfers:./query_data.sh "Find all high-risk transfers initiated by Alex"
Karena skema
FinGraphtidak menentukan apa yang dimaksud denganhigh-risk transfer(yang dalam logika bisnis Anda berarti transfer sebesar200atau lebih ke rekening yang diblokir denganis_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
100yang tidak memenuhi nilai minimum:+-------------------+------------------------+-----------------+-----------------+ | source_account_id | destination_account_id | transfer_amount | order_number | +-------------------+------------------------+-----------------+-----------------+ | 7 | 16 | 300 | 304330008004315 | | 7 | 16 | 100 | 304120005529714 | +-------------------+------------------------+-----------------+-----------------+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 propertiPerson.countrydiFinGraphmenyimpan 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:
- Instal Antigravity CLI. Untuk mengetahui informasi selengkapnya, lihat Memulai Antigravity CLI.
- Menginstal Google Cloud CLI.
Siapkan Kredensial Default Aplikasi (ADC). Jalankan perintah berikut di terminal Anda untuk melakukan autentikasi:
gcloud auth application-default loginDi terminal Anda, mulai Antigravity CLI:
agySiapkan 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
FinGraphagar 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.yamldanautoctx/state.md. Kemudian, bukaautoctx/state.mddan pastikan bagian## Active Databaseberisi baris- **Graph Ids**: ["FinGraph"]. Agen rekayasa konteks membaca nama grafik properti dari baris ini saat membuat konfigurasi evaluasi. Untuk mengetahui informasi selengkapnya tentangtools.yaml, lihat dokumentasi MCP Toolbox.Untuk memuat ulang konfigurasi setelah
autoctx/tools.yamldibuat, jalankan perintah berikut di Antigravity CLI:/mcpPilih
toolbox, lalu pilihRestart.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:
Masukkan perintah berikut ke dalam infrastruktur pengelola agen, yang menentukan bahwa
FinGraphadalah 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;Agen mengonversi input Anda menjadi template GQL berparameter yang digeneralisasi di seluruh nama orang. Untuk mengetahui informasi selengkapnya, lihat Ringkasan set konteks.
Tinjau template kueri GQL yang dihasilkan, lalu berikan perintah kepada agen dengan
Save it to context_set.json. Agen akan membuatcontext_set.jsondi 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.
Masukkan perintah berikut ke dalam infrastruktur pengelola agen, yang menentukan bahwa
FinGraphadalah 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.Tinjau file
context_set.jsonyang 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_TABLEuntuk mencocokkan label node diFinGraphdan menampilkan nilai properti yang disimpan, lokasi properti (FinGraph.Person.country), jenis konsep, jarak0untuk 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.
Di konsol Google Cloud , buka halaman Spanner.
Pilih instance Anda dari daftar, lalu pilih database Spanner Anda.
Di menu navigasi, klik Spanner Studio.
Di panel Explorer, di samping set konteks
fingraph-assistant, klik View actions.Klik Edit context set.
Opsional: Edit Deskripsi set konteks.
Klik Browse di bagian Upload context set file, lalu pilih file
context_set.jsonyang Anda buat.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.
- Temukan ID set konteks untuk
fingraph-assistant. Untuk mengetahui petunjuknya, lihat Menemukan ID set konteks. Tetapkan variabel lingkungan
CONTEXT_SET_IDagarquery_data.shmengirimkan set konteks Anda:export CONTEXT_SET_ID="CONTEXT_SET_ID"
Ganti
CONTEXT_SET_IDdengan ID set konteks lengkap, sepertiprojects/my-project/locations/us-central1/contextSets/fingraph-assistant.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
100oleh Alex ke akun yang diblokir16dan menampilkan hasil yang mirip dengan berikut ini:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 300 | +------------------------+-----------------+Ajukan pertanyaan serupa untuk
Dana:./query_data.sh "What are the high-risk transfers initiated by Dana?"
Karena template GQL di
context_set.jsondiparameterisasi ({name: ?}), QueryData menerapkan definisihigh-risk transfersyang sama keDana: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
500Dana ke akun7yang tidak diblokir dan menampilkan hasil yang mirip dengan berikut ini:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 200 | +------------------------+-----------------+Ajukan pertanyaan negara lagi:
./query_data.sh "Find accounts owned by people from Czech Republic"
QueryData menjalankan penelusuran nilai
Person country, menautkanCzech Republicke nilai tersimpanCzech_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 | +------------+------------+----------------+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.
- Download MCP Toolbox versi 1.4.0 atau yang lebih baru. MCP Toolbox mengekspos REST API
QueryDatasebagai alat MCP yang dapat dihubungkan oleh aplikasi. Siapkan Kredensial Default Aplikasi (ADC):
gcloud auth application-default loginBuat file konfigurasi
tools.yamlyang menentukan sumber HTTP untuk Analisis Percakapan API dan alat HTTP yang memanggil metodeQueryData. Pastikan untuk menentukangraph_ids(disetel ke["FinGraph"]) di bagianspanner_reference.database_referencedalam 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 memuattools.yaml, dan mengganti{{json .query}}dengan pertanyaan yang dikirim agen ke alat, yang dienkode sebagai string JSON.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 berisiFinGraph.CONTEXT_SET_ID: ID set konteks lengkapfingraph-assistant.
Jalankan server MCP Toolbox dengan file
tools.yaml:./toolbox --config "tools.yaml"Buat aplikasi ADK yang memanggil alat
fingraph_query_data_toolmenggunakan Python SDK MCP Toolbox:Buat dan ubah ke direktori untuk aplikasi, seperti
fingraph-assistant-app:mkdir fingraph-assistant-appcd fingraph-assistant-appBuat lingkungan virtual dan instal paket yang diperlukan:
python3 -m venv .venvsource .venv/bin/activatepip install toolbox-corepip install google-genaipip install google-adkBuat agen ADK:
adk create my_agentPilih model
gemini-2.5-flash, pilih Google AI, lalu masukkan kunci Gemini API Anda. Untuk informasi selengkapnya, lihat Menggunakan kunci Gemini API.Ganti konten
my_agent/agent.pydengan 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]), )
Mulai server web ADK di
http://127.0.0.1:8000:adk web --port 8000Masukkan 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 APIQueryDatadengangraph_idsditetapkan keFinGraph. 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): 200Masukkan pertanyaan yang menggunakan template GQL
high-risk transfersyang Anda tambahkan ke set konteks:What are the high-risk transfers initiated by Alex?Berdasarkan template GQL di
fingraph-assistant, QueryData mengidentifikasi transfer minimal200ke 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:
Di konsol Google Cloud , buka halaman Spanner.
Pilih instance Anda dari daftar, lalu pilih database Spanner Anda.
Di menu navigasi, klik Spanner Studio.
Di panel Explorer, di samping
fingraph-assistant, klik View actions.Klik Delete context set, masukkan
fingraph-assistantdi 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
- Pelajari lebih lanjut set konteks untuk Spanner Graph.
- Pelajari cara membangun set konteks menggunakan agen rekayasa konteks.
- Pelajari cara menentukan konteks yang ditulis untuk sumber data database.