이 튜토리얼에서는 Google Cloud 콘솔을 사용하여 Spanner Graph에서 QueryData를 설정하고 사용하며 이를 애플리케이션과 통합하는 방법을 설명합니다. FinGraph 속성 그래프를 설정하고, 컨텍스트 엔지니어링 에이전트를 사용하여 Graph Query Language(GQL) 컨텍스트 세트 파일을 빌드하고, Spanner Studio에서 컨텍스트 세트를 만들고, graph_ids가 구성된 대화형 분석 API의 QueryData 메서드를 호출하여 QueryData를 테스트하고, MCP 도구 상자에서 사용자설정 HTTP 도구를 사용하여 에이전트 애플리케이션을 QueryData에 연결하는 방법을 알아봅니다.
자세한 내용은 QueryData 개요를 참고하세요.
목표
FinGraph속성 그래프 스키마를 만들고 샘플 그래프 데이터로 채웁니다.- 컨텍스트 엔지니어링 에이전트를 사용하여
FinGraph의 컨텍스트 세트 파일을 빌드합니다. - Spanner Studio에서 컨텍스트 세트를 만들고 컨텍스트 세트 파일을 업로드합니다.
spanner_reference에 지정된graph_ids를 사용하여QueryDataREST API를 호출하여 QueryData를 테스트하고 GQL 쿼리를 생성합니다.QueryDataREST API를 호출하는 MCP 도구 상자의 커스텀 HTTP 도구를 사용하여 QueryData를 애플리케이션과 통합합니다.- 쿼리 템플릿, 쿼리 패싯,
GRAPH_TABLE값 검색 쿼리를 사용하여 그래프 데이터에서 LLM 응답을 그라운딩합니다.
비용
이 문서에서는 비용이 청구될 수 있는 Google Cloud구성요소를 사용합니다.
프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용합니다.
신규 Google Cloud 사용자는 무료 체험판을 이용할 수 있습니다.
요금이 계속 청구되지 않도록 하려면 이 문서의 작업을 완료한 후 만든 리소스를 삭제하세요. 자세한 내용은 삭제를 참조하세요.
시작하기 전에
컨텍스트 세트를 만들기 전에 다음 기본 요건을 완료하세요.
필수 서비스 사용 설정
프로젝트에 다음 서비스를 사용 설정합니다.Spanner 인스턴스 준비
- Spanner 인스턴스를 사용할 수 있는지 확인합니다. 자세한 내용은 인스턴스 만들기를 참조하세요.
- 테이블을 만들 인스턴스에 데이터베이스를 만들어야 합니다. 자세한 내용은 Spanner 인스턴스에서 데이터베이스 만들기를 참조하세요.
필수 역할 및 권한
- 인스턴스에 IAM 사용자 또는 서비스 계정을 추가합니다. 자세한 내용은 IAM 역할 적용을 참조하세요.
- 프로젝트 수준에서 IAM 사용자에게
roles/spanner.databaseReader,roles/serviceusage.serviceUsageConsumer,roles/geminidataanalytics.queryDataUser역할을 부여합니다. 자세한 내용은 프로젝트에 IAM 정책 바인딩 추가를 참조하세요. - 컨텍스트 세트를 만들고, 업로드하고, 관리하려면 프로젝트 수준에서 IAM 사용자에게 Dataplex 카탈로그 편집자(
roles/dataplex.catalogEditor) 또는 Dataplex 카탈로그 관리자(roles/dataplex.catalogAdmin) 역할을 부여합니다. 자세한 내용은 컨텍스트 세트 권한을 참고하세요. - 필요한 데이터베이스의 프로젝트 수준에서 IAM 사용자에게 역할 및 권한을 부여합니다.
FinGraph 스키마 만들기 및 그래프 데이터 삽입
이 튜토리얼에서는 Owns(PersonOwnAccount) 및 Transfers(AccountTransferAccount) 에지로 연결된 Person 및 Account 노드를 모델링하는 FinGraph 금융 속성 그래프 데이터 세트를 사용합니다.
FinGraph 스키마를 만들고 Spanner 데이터베이스에 그래프 데이터를 채우려면 Spanner Graph 설정 가이드의 다음 단계를 완료하세요.
- 스키마를 사용하여 그래프 데이터베이스 만들기에 따라
Person,Account,PersonOwnAccount,AccountTransferAccount테이블과FinGraph속성 그래프 정의를 만듭니다. - 그래프 데이터 삽입에 따라 샘플 사용자(
Alex,Dana,Lee), 계정(7,16,20), 계정 소유권 에지, 송금 에지를FinGraph에 삽입합니다.
컨텍스트 세트 만들기
fingraph-assistant라는 빈 컨텍스트 세트를 만듭니다. 이 튜토리얼의 뒷부분에서 컨텍스트 세트 파일을 업로드합니다.
Google Cloud 콘솔에서 Spanner 페이지로 이동합니다.
목록에서 인스턴스를 선택한 다음
FinGraph가 포함된 데이터베이스를 선택합니다.탐색 메뉴에서 Spanner 스튜디오를 클릭합니다.
탐색기 창의 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.
컨텍스트 세트 만들기를 클릭합니다.
컨텍스트 세트 이름 필드에
fingraph-assistant를 입력합니다.만들기를 클릭합니다.
컨텍스트 없이 QueryData 테스트
이 섹션에서는 QueryData REST API를 호출하여 컨텍스트 집합 없이 자연어 질문에 대한 GQL 쿼리를 생성합니다. 컨텍스트가 없으면 QueryData는 FinGraph 스키마에 직접 매핑되는 질문에 답할 수 있지만 high-risk transfers와 같은 커스텀 비즈니스 용어를 해석하거나 Czech Republic와 Czech_Republic와 같은 값 형식 차이를 해결할 수 없습니다.
터미널에서 다음 환경 변수를 설정합니다.
export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID"
다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.INSTANCE_ID: Spanner 인스턴스 ID입니다.DATABASE_ID:FinGraph가 포함된 데이터베이스의 ID입니다.
graph_ids가FinGraph로 설정된QueryDataREST API에 질문을 전송하는query_data.sh라는 도우미 스크립트를 만듭니다.CONTEXT_SET_ID환경 변수가 설정된 경우 스크립트는 컨텍스트 세트 ID도 전송합니다.cat > query_data.sh <<'EOF' #!/bin/bash # Usage: ./query_data.sh "NATURAL_LANGUAGE_QUESTION" if [[ -n "${CONTEXT_SET_ID}" ]]; then AGENT_CONTEXT=", \"agent_context_reference\": {\"context_set_id\": \"${CONTEXT_SET_ID}\"}" fi curl -sS -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: ${PROJECT_ID}" \ "https://geminidataanalytics.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global:queryData" \ -d @- <<JSON { "prompt": "$1", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "${PROJECT_ID}", "instance_id": "${INSTANCE_ID}", "database_id": "${DATABASE_ID}", "graph_ids": ["FinGraph"] }${AGENT_CONTEXT} } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true } } JSON EOF chmod +x query_data.sh스크립트는 질문을 요청 본문에 그대로 삽입하므로 질문에 큰따옴표(
")를 사용하지 마세요.FinGraph스키마에 직접 매핑되는 질문을 합니다../query_data.sh "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts."
응답에서
generatedQuery및queryResult필드를 검토합니다. 이 명확한 질문에 대해 QueryData는 다음과 유사한 GQL 쿼리를 생성합니다.GRAPH FinGraph MATCH (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account), (recipient:Person)-[:Owns]->(dst) RETURN recipient.name AS recipient_name, dst.id AS recipient_account_id, t.amount AS transfer_amount;그러면 다음과 비슷한 결과가 반환됩니다.
+----------------+----------------------+-----------------+ | recipient_name | recipient_account_id | transfer_amount | +----------------+----------------------+-----------------+ | Alex | 7 | 500 | | Lee | 16 | 200 | +----------------+----------------------+-----------------+비즈니스 용어
high-risk transfers를 포함하는 질문을 합니다../query_data.sh "Find all high-risk transfers initiated by Alex"
FinGraph스키마는high-risk transfer를 구성하는 요소를 정의하지 않으므로(비즈니스 로직에서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;이렇게 하면 기준점을 충족하지 않는
100전송을 포함하여 Alex의 두 전송이 모두 반환됩니다.+-------------------+------------------------+-----------------+-----------------+ | source_account_id | destination_account_id | transfer_amount | order_number | +-------------------+------------------------+-----------------+-----------------+ | 7 | 16 | 300 | 304330008004315 | | 7 | 16 | 100 | 304120005529714 | +-------------------+------------------------+-----------------+-----------------+국가를 참조하는 질문을 합니다.
./query_data.sh "Find accounts owned by people from Czech Republic"
컨텍스트 또는 값 연결이 없으면 QueryData는 공백이 있는
'Czech Republic'를 필터링하는 GQL 쿼리를 생성합니다.FinGraph의Person.country속성은 값을 밑줄이 있는'Czech_Republic'로 저장하므로 쿼리는 행을 반환하지 않습니다.GRAPH FinGraph MATCH (p:Person {country: 'Czech Republic'})-[:Owns]->(a:Account) RETURN p.name AS owner_name, a.id AS account_id, a.nick_name;
컨텍스트 세트의 컨텍스트 생성
이 섹션에서는 로컬 환경을 준비하고 컨텍스트 엔지니어링 에이전트를 사용하여 Spanner 데이터베이스의 FinGraph 속성 그래프에 대한 컨텍스트 세트 파일(context_set.json)을 만듭니다.
환경 설정
컨텍스트 엔지니어링 에이전트의 환경을 설정하려면 다음 단계를 수행합니다.
- Antigravity CLI를 설치합니다. 자세한 내용은 Antigravity CLI 시작하기를 참고하세요.
- Google Cloud CLI를 설치합니다.
애플리케이션 기본 사용자 인증 정보(ADC)를 설정합니다. 터미널에서 다음 명령어를 실행하여 인증합니다.
gcloud auth application-default login터미널에서 Antigravity CLI를 시작합니다.
agySpanner 데이터베이스의 데이터베이스 연결을 설정합니다. Spanner 데이터베이스의 속성 그래프에 대한 컨텍스트를 생성하고 있음을 명시적으로 지정하고 에이전트가 GQL 관련 컨텍스트 엔지니어링 워크플로를 트리거하도록
FinGraph속성 그래프 이름을 포함하는 프롬프트를 입력합니다.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 도구 상자 문서를 참조하세요.autoctx/tools.yaml가 생성된 후 구성을 새로고침하려면 Antigravity CLI에서 다음 명령어를 실행합니다./mcptoolbox을 선택한 다음Restart을 선택합니다.MCP 도구 상자와 컨텍스트 엔지니어링 에이전트 플러그인이 연결되어 있고 사용할 준비가 되었는지 확인합니다.
/mcp
GQL 템플릿 컨텍스트 생성
QueryData가 비즈니스 용어 high-risk transfers를 인식하지 못하는 문제를 해결하려면 컨텍스트 세트 파일에서 high-risk transfers를 차단된 계정(dst.is_blocked = true)으로 전송된 200 이상의 송금으로 정의합니다.
GQL 템플릿 컨텍스트를 생성하려면 다음 단계를 수행합니다.
에이전트 하네스에 다음 프롬프트를 입력하여
FinGraph가 Spanner 데이터베이스의 속성 그래프임을 지정합니다.For the FinGraph property graph in my Spanner database, generate a GQL template for the question: "Find all high-risk transfers initiated by Alex" with the following GQL query: GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;에이전트는 입력을 사람 이름 전반에 걸쳐 일반화하는 매개변수화된 GQL 템플릿으로 변환합니다. 자세한 내용은 컨텍스트 세트 개요를 참조하세요.
생성된 GQL 쿼리 템플릿을 검토한 후 에이전트에
Save it to context_set.json프롬프트를 입력합니다. 에이전트는 다음 콘텐츠를 사용하여 디렉터리에context_set.json를 만듭니다.{ "templates": [ { "nl_query": "Find all high-risk transfers initiated by Alex", "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "intent": "Find all high-risk transfers initiated by Alex", "manifest": "Find all high-risk transfers initiated by a given person", "parameterized": { "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "parameterized_intent": "Find all high-risk transfers initiated by ?" } } ] }
패싯 및 값 검색 컨텍스트 생성
이 섹션에서는 GQL 속성과 GRAPH_TABLE 값 검색어 2개를 context_set.json에 추가합니다. 이전 섹션에서 추가한 템플릿은 'Alex가 시작한 모든 고위험 전송 찾기'와 동일한 구조의 질문에 답변합니다. 패싯은 차단된 계정 패턴을 캡처하므로 QueryData는 '차단된 계정이 포함된 모든 송금 찾기'와 같이 템플릿과 일치하지 않는 질문에도 이 패턴을 적용할 수 있습니다. 값 검색을 통해 QueryData는 Czech Republic와 같은 값 구문을 Person.country의 저장된 값 Czech_Republic에 매핑하고 대소문자에 관계없이 Account.nick_name의 계정 닉네임을 일치시킬 수 있습니다.
에이전트 하네스에 다음 프롬프트를 입력하여
FinGraph가 Spanner 데이터베이스의 속성 그래프임을 지정합니다.For the FinGraph property graph in my Spanner database, generate a GQL facet with the GQL clause "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})" for intent "transfers involving a blocked account". Then generate two GRAPH_TABLE value searches on FinGraph: one on Person.country that ignores case and treats underscores as spaces, with concept type "Person country", and one on Account.nick_name that ignores case, with concept type "Account nickname". Validate the value search queries against the database, and then append the facet and value searches to context_set.json.이제 GQL 템플릿, GQL 속성, 값 검색 정의가 포함된 업데이트된
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 ?" } } ], "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에 컨텍스트 세트 파일 업로드
이 섹션에서는 Spanner Studio에서 설정한 fingraph-assistant 컨텍스트에 context_set.json 파일을 업로드합니다.
Google Cloud 콘솔에서 Spanner 페이지로 이동합니다.
목록에서 인스턴스를 선택한 다음 Spanner 데이터베이스를 선택합니다.
탐색 메뉴에서 Spanner 스튜디오를 클릭합니다.
탐색기 창에서
fingraph-assistant컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.컨텍스트 세트 수정을 클릭합니다.
선택사항: 컨텍스트 세트 설명을 수정합니다.
컨텍스트 세트 파일 업로드 섹션에서 찾아보기를 클릭하고 생성한
context_set.json파일을 선택합니다.저장을 클릭합니다.
QueryData를 사용하여 GQL 쿼리 생성
이 섹션에서는 fingraph-assistant 컨텍스트 세트로 QueryData REST API를 호출하여 QueryData가 high-risk transfers와 같은 비즈니스 용어를 정확하게 변환하고 GQL 쿼리에서 Czech Republic를 Czech_Republic로 변환하는지 확인합니다.
fingraph-assistant의 컨텍스트 세트 ID를 찾습니다. 자세한 내용은 컨텍스트 세트 ID 찾기를 참고하세요.query_data.sh에서 컨텍스트 세트를 전송하도록CONTEXT_SET_ID환경 변수를 설정합니다.export CONTEXT_SET_ID="CONTEXT_SET_ID"
CONTEXT_SET_ID를 전체 컨텍스트 세트 ID(예:projects/my-project/locations/us-central1/contextSets/fingraph-assistant)로 바꿉니다.고위험 트랜스퍼 질문을 다시 합니다.
./query_data.sh "Find all high-risk transfers initiated by Alex"
이제 생성된 GQL 쿼리에 차단된 대상 계정 필터(
is_blocked: true)와 금액 기준(t.amount >= 200)이 적용됩니다.GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;이렇게 하면 Alex가 차단된 계정
16으로100를 이체한 내역이 제외되고 다음과 비슷한 결과가 반환됩니다.+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 300 | +------------------------+-----------------+Dana에 대해 비슷한 질문을 합니다../query_data.sh "What are the high-risk transfers initiated by Dana?"
context_set.json의 GQL 템플릿은 파라미터화({name: ?})되어 있으므로 QueryData는Dana에 동일한high-risk transfers정의를 적용합니다.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;이렇게 하면 다나가 차단되지 않은 계정
7으로500를 전송한 내역이 제외되고 다음과 비슷한 결과가 반환됩니다.+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 200 | +------------------------+-----------------+국가에 관한 질문을 다시 합니다.
./query_data.sh "Find accounts owned by people from Czech Republic"
QueryData는
Person country값 검색을 실행하고Czech Republic를 저장된 값Czech_Republic에 연결하고 다음과 유사한 쿼리를 생성합니다.GRAPH FinGraph MATCH (p:Person {country: 'Czech_Republic'})-[:Owns]->(a:Account) RETURN p.name AS owner_name, a.id AS account_id, a.nick_name;그러면 다음과 비슷한 결과가 반환됩니다.
+------------+------------+----------------+ | owner_name | account_id | nick_name | +------------+------------+----------------+ | Dana | 20 | Rainy Day Fund | +------------+------------+----------------+차단된 계정 패싯을 사용하는 질문을 합니다.
./query_data.sh "Find all money transfers involving a blocked account."
QueryData는 패싯을 사용하여 차단된 계정
16과 관련된 양방향 전송을 일치시키고 전송 4개를 반환합니다.
애플리케이션과 QueryData 통합
이 섹션에서는 에이전트 개발 키트(ADK), MCP 도구 상자, fingraph-assistant 컨텍스트 세트를 사용하여 FinGraph의 대화형 데이터 에이전트 애플리케이션을 만듭니다. Spanner Graph에 GQL 쿼리 생성을 사용 설정하려면 tools.yaml 파일에서 spanner_reference.database_reference에 graph_ids를 설정하여 QueryData REST API를 호출하는 커스텀 HTTP 도구를 정의합니다.
- MCP 도구 상자 버전 1.4.0 이상을 다운로드합니다. MCP 도구 상자는 애플리케이션이 연결할 수 있는 MCP 도구로
QueryDataREST API를 노출합니다. 애플리케이션 기본 사용자 인증 정보(ADC)를 설정합니다.
gcloud auth application-default loginConversational Analytics API의 HTTP 소스와
QueryData메서드를 호출하는 HTTP 도구를 정의하는tools.yaml구성 파일을 만듭니다. 요청 본문의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 도구 상자는
tools.yaml를 로드할 때${...}참조를 해당 환경 변수의 값으로 바꾸고{{json .query}}를 에이전트가 도구에 전송하는 질문으로 바꾸며, 이는 JSON 문자열로 인코딩됩니다.MCP 도구 상자를 실행하는 터미널에서
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 인스턴스의 IDDATABASE_ID:FinGraph가 포함된 Spanner 데이터베이스의 ID입니다.CONTEXT_SET_ID:fingraph-assistant의 전체 컨텍스트 세트 ID입니다.
tools.yaml파일을 사용하여 MCP 도구 상자 서버를 실행합니다../toolbox --config "tools.yaml"MCP 도구 상자 Python SDK를 사용하여
fingraph_query_data_tool도구를 호출하는 ADK 애플리케이션을 만듭니다.애플리케이션의 디렉터리(예:
fingraph-assistant-app)를 만들고 해당 디렉터리로 변경합니다.mkdir fingraph-assistant-appcd fingraph-assistant-app가상 환경을 만들고 필요한 패키지를 설치합니다.
python3 -m venv .venvsource .venv/bin/activatepip install toolbox-corepip install google-genaipip install google-adkADK 에이전트를 만듭니다.
adk create my_agentgemini-2.5-flash모델을 선택하고 Google AI를 선택한 후 Gemini API 키를 입력합니다. 자세한 내용은 Gemini API 키 사용을 참고하세요.my_agent/agent.py의 콘텐츠를 다음 Financial Graph Assistant 샘플 애플리케이션 코드로 바꿉니다.from typing import cast from google.adk.agents.llm_agent import Agent from google.adk.agents.llm_agent import ToolUnion from toolbox_core import ToolboxSyncClient TOOLBOX_URL = "http://127.0.0.1:5000" INSTRUCTION = """ # ROLE You are a factual financial graph data assistant for FinGraph. Your goal is to help users analyze account ownership, money transfers, and risk patterns by providing accurate information with a helpful, professional tone. - Always call the Query Data Tool first to answer questions about the graph data, including questions with domain-specific terms (such as "high-risk"), because the tool resolves domain definitions against the database context. Ask the user to clarify only if the tool returns a disambiguation question or fails to generate a valid query. # OPERATIONAL CONSTRAINTS - TOOL LIMITATION: You only have access to the Query Data Tool. Do not claim to have capabilities beyond what this tool provides. - TRANSPARENCY POLICY: Maintain a seamless user experience. Never mention that you are using a tool, querying a database, or generating GQL. Frame all responses as your own direct assistance. - SCOPE MANAGEMENT: If a user asks for something beyond your capabilities, politely state that you cannot perform that specific task and guide the user toward what you can help with. # COMMUNICATION STYLE - Be concise and scannable when listing answers. - Maintain a helpful, professional persona. ===== # QUERY DATA TOOL Inputs: 1. query: A natural language formulation of a graph database query. Outputs: (all optional) 1. disambiguationQuestion: Clarification questions or comments where the tool needs the user's input. 2. generatedQuery: The generated GQL query for the user query. 3. intentExplanation: An explanation for why the tool produced `generatedQuery`. 4. queryResult: The result of executing `generatedQuery`. 5. naturalLanguageAnswer: The natural language answer that summarizes the `query` and `queryResult`. Usage guidance: 1. If `disambiguationQuestion` is produced, solicit the needed inputs from the user and try the tool with a new `query` that includes the clarification. 2. If `naturalLanguageAnswer` is produced, use `intentExplanation` and `generatedQuery` to see if you need to clarify any assumptions for the user. 3. If the tool output indicates failure or empty results, explain that clearly using the provided reasoning. """ client = ToolboxSyncClient(TOOLBOX_URL) mcp_tool = client.load_tool("fingraph_query_data_tool") root_agent = Agent( model="gemini-2.5-flash", name="root_agent", instruction=INSTRUCTION, tools=cast(list[ToolUnion], [mcp_tool]), )
http://127.0.0.1:8000에서 ADK 웹 서버를 시작합니다.adk web --port 8000ADK 웹 UI에 멀티홉 그래프 질문을 입력합니다.
Who did Dana transfer money to, and what were the amounts?에이전트는
fingraph_query_data_tool도구를 호출하여graph_ids가FinGraph로 설정된QueryDataREST API에 질문을 전송합니다. QueryData는 생성된 GQL 쿼리를 실행하고 에이전트는 다음과 비슷한 응답을 반환합니다.Dana transferred money from account 20 to the following recipients: * Alex (account 7): 500 * Lee (account 16): 200컨텍스트 세트에 추가한
high-risk transfersGQL 템플릿을 사용하는 질문을 입력합니다.What are the high-risk transfers initiated by Alex?fingraph-assistant의 GQL 템플릿을 기반으로 QueryData는 차단된 계정으로의200이상의 이체를 식별하고 에이전트는 다음과 유사한 응답을 반환합니다.Here is the high-risk transfer initiated by Alex (transfers of 200 or more to a blocked account): * Blocked destination account 16: amount 300
에이전트 성능 반복
ADK 웹 UI를 사용하면 fingraph_query_data_tool 도구의 요청 및 응답 페이로드를 검사할 수 있습니다. 탐색창의 이벤트 탭에서 functionResponse를 펼쳐 생성된 FinGraph GQL 쿼리(generatedQuery), queryResult, intentExplanation, disambiguationQuestion, naturalLanguageAnswer를 검사합니다. QueryData REST API는 이러한 필드 이름을 camelCase로 반환합니다.
대답 정확도 미세 조정
GQL 템플릿, 패싯, 값 검색을 추가하여 QueryData의 응답 정확성을 지속적으로 미세 조정할 수 있습니다. 컨텍스트 엔지니어링 에이전트를 사용하여 Spanner 데이터베이스의 FinGraph 속성 그래프에 대한 업데이트된 컨텍스트를 생성하고 평가한 다음 Spanner Studio에서 업데이트된 컨텍스트 세트 파일을 업로드합니다. 자세한 내용은 Spanner Studio에서 컨텍스트 세트 관리를 참조하세요.
여러 에이전트
개발 환경에서는 tools.yaml 파일에 여러 HTTP 도구(예: fingraph_query_data_tool_v1 및 fingraph_query_data_tool_v2)를 정의하여 여러 Spanner Graph 컨텍스트 집합에서 A/B 테스트를 수행할 수 있습니다. 각 도구의 요청 본문은 graph_ids를 ["FinGraph"] 및 다른 context_set_id로 설정합니다.
삭제
이 튜토리얼을 마친 후 비용이 계속 청구되지 않도록 자신이 만든 리소스를 삭제하세요.
컨텍스트 세트 삭제
Spanner 데이터베이스 또는 인스턴스를 삭제하기 전에 fingraph-assistant 컨텍스트 세트를 삭제합니다.
Google Cloud 콘솔에서 Spanner 페이지로 이동합니다.
목록에서 인스턴스를 선택한 다음 Spanner 데이터베이스를 선택합니다.
탐색 메뉴에서 Spanner 스튜디오를 클릭합니다.
탐색기 창에서
fingraph-assistant옆에 있는 작업 보기를 클릭합니다.컨텍스트 세트 삭제를 클릭하고 확인 필드에
fingraph-assistant를 입력한 후 확인을 클릭합니다.
데이터베이스 및 인스턴스 삭제
FinGraph 속성 그래프, Spanner 데이터베이스, Spanner 인스턴스를 삭제하려면 Spanner Graph 설정 및 쿼리: 삭제의 단계를 따르세요.
다음 단계
- Spanner Graph의 컨텍스트 세트 자세히 알아보기
- 컨텍스트 엔지니어링 에이전트를 사용하여 컨텍스트 세트를 빌드하는 방법을 알아보세요.
- 데이터베이스 데이터 소스의 작성된 컨텍스트를 정의하는 방법을 알아보세요.