Neste tutorial, descrevemos como configurar e usar o QueryData no Spanner Graph usando o console do Google Cloud e integrá-lo ao seu aplicativo. Você vai aprender a configurar o gráfico de propriedades FinGraph, criar um arquivo de conjunto de contextos da linguagem de consulta de gráfico (GQL) usando o agente de engenharia de contexto, criar um conjunto de contextos no Spanner Studio, testar o QueryData chamando o método QueryData na API Conversational Analytics com graph_ids configurado e usar uma ferramenta HTTP personalizada no MCP Toolbox para conectar um aplicativo de agente ao QueryData.
Para mais informações, consulte Visão geral do QueryData.
Objetivos
- Crie o esquema de gráfico de propriedades
FinGraphe preencha-o com dados de gráfico de amostra. - Crie um arquivo de conjunto de contexto para
FinGraphusando o agente de engenharia de contexto. - Crie um conjunto de contextos e faça upload do arquivo dele no Spanner Studio.
- Teste o QueryData e gere consultas GQL chamando a API REST
QueryDatacomgraph_idsespecificado emspanner_reference. - Integre o QueryData ao seu aplicativo usando uma ferramenta HTTP personalizada no MCP Toolbox que chama a API REST
QueryData. - Embase as respostas do LLM nos dados do gráfico usando modelos de consulta, facetas de consulta e consultas de pesquisa de valor
GRAPH_TABLE.
Custos
Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.
Para evitar o faturamento contínuo, exclua os recursos criados ao concluir as tarefas deste documento. Para mais informações, consulte Limpeza.
Antes de começar
Conclua os seguintes pré-requisitos antes de criar um conjunto de contexto:
Ativar serviços obrigatórios
Ative os seguintes serviços para seu projeto:Preparar uma instância do Spanner
- Verifique se uma instância do Spanner está disponível. Para mais informações, consulte Criar uma instância.
- Crie um banco de dados na instância em que você vai criar as tabelas. Para mais informações, consulte Criar um banco de dados na instância do Spanner.
Papéis e permissões necessárias
- Adicione um usuário do IAM ou uma conta de serviço à instância. Para mais informações, consulte Aplicar papéis do IAM.
- Conceda os papéis
roles/spanner.databaseReader,roles/serviceusage.serviceUsageConsumereroles/geminidataanalytics.queryDataUserao usuário do IAM no nível do projeto. Para mais informações, consulte Adicionar vinculação de política do IAM a um projeto. - Para criar, fazer upload e gerenciar conjuntos de contexto, conceda o papel de Editor do Dataplex Catalog (
roles/dataplex.catalogEditor) ou Administrador do Dataplex Catalog (roles/dataplex.catalogAdmin) ao usuário do IAM no nível do projeto. Para mais informações, consulte Permissões de conjuntos de contexto. - Conceda papéis e permissões ao usuário do IAM para envolvidos no projeto para os bancos de dados necessários.
Criar o esquema FinGraph e inserir dados de gráfico
Neste tutorial, usamos o conjunto de dados de gráfico de propriedades financeiras FinGraph, que modela nós Person e Account conectados por arestas Owns (PersonOwnAccount) e Transfers (AccountTransferAccount).
Para criar o esquema FinGraph e preencher os dados do gráfico no banco de dados do Spanner, siga estas etapas do guia de configuração do Spanner Graph:
- Siga as instruções em Criar um banco de dados de gráfico usando um esquema para criar as tabelas
Person,Account,PersonOwnAccounteAccountTransferAccounte a definição do gráfico de propriedadesFinGraph. - Siga as instruções em Inserir dados do gráfico para inserir as pessoas de exemplo (
Alex,DanaeLee), as contas (7,16e20), as arestas de propriedade da conta e as arestas de transferência de dinheiro emFinGraph.
Criar um conjunto de contextos
Crie um conjunto de contextos vazio chamado fingraph-assistant. Mais adiante neste tutorial, você vai fazer upload de um arquivo de conjunto de contexto para ele.
No console do Google Cloud , acesse a página do Spanner.
Selecione sua instância na lista e, em seguida, o banco de dados que contém
FinGraph.No menu de navegação, clique em Spanner Studio.
No painel Explorer, ao lado de Conjuntos de contexto, clique em Ver ações.
Clique em Criar conjunto de contexto.
No campo Nome do conjunto de contexto, digite
fingraph-assistant.Clique em Criar.
Testar o QueryData sem contexto
Nesta seção, você vai chamar a API REST QueryData para gerar consultas GQL para perguntas em linguagem natural sem um contexto definido. Sem contexto, o QueryData pode responder a perguntas que se correlacionam diretamente com o esquema FinGraph, mas não pode interpretar terminologias de negócios personalizadas, como high-risk transfers, ou resolver diferenças de formatação de valores, como Czech Republic em vez de Czech_Republic.
No terminal, defina as seguintes variáveis de ambiente:
export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID"
Substitua:
PROJECT_ID: o ID do projeto Google Cloud .INSTANCE_ID: o ID da instância do Spanner.DATABASE_ID: o ID do banco de dados que contémFinGraph.
Crie um script auxiliar chamado
query_data.shque envie uma pergunta à API RESTQueryDatacomgraph_idsdefinido comoFinGraph. Se a variável de ambienteCONTEXT_SET_IDestiver definida, o script também vai enviar o ID do conjunto de contexto: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.shO script insere sua pergunta no corpo da solicitação como está, então não use aspas duplas (
") na pergunta.Faça uma pergunta que se relacione diretamente com o esquema
FinGraph:./query_data.sh "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts."
Na resposta, revise os campos
generatedQueryequeryResult. Para essa pergunta inequívoca, o QueryData gera uma consulta GQL semelhante a esta: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;Isso retorna resultados semelhantes a estes:
+----------------+----------------------+-----------------+ | recipient_name | recipient_account_id | transfer_amount | +----------------+----------------------+-----------------+ | Alex | 7 | 500 | | Lee | 16 | 200 | +----------------+----------------------+-----------------+Faça uma pergunta que inclua o termo comercial
high-risk transfers:./query_data.sh "Find all high-risk transfers initiated by Alex"
Como o esquema
FinGraphnão define o que constitui umhigh-risk transfer(que, na sua lógica de negócios, significa uma transferência de200ou mais para uma conta bloqueada em queis_blocked = true), o QueryData não aplica os filtros de conta bloqueada e limite de valor ou aplica a própria interpretação do termo. Por exemplo, o QueryData pode inventar um limite de valor que não retorna linhas ou ignorar o termo e gerar uma consulta semelhante a esta:-- 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;Isso retorna as duas transferências de Alex, incluindo a de
100que não atende ao limite:+-------------------+------------------------+-----------------+-----------------+ | source_account_id | destination_account_id | transfer_amount | order_number | +-------------------+------------------------+-----------------+-----------------+ | 7 | 16 | 300 | 304330008004315 | | 7 | 16 | 100 | 304120005529714 | +-------------------+------------------------+-----------------+-----------------+Faça uma pergunta que se refira a um país:
./query_data.sh "Find accounts owned by people from Czech Republic"
Sem contexto ou vinculação de valor, o QueryData gera uma consulta GQL que filtra por
'Czech Republic'com um espaço. Como a propriedadePerson.countryemFinGrapharmazena o valor como'Czech_Republic'com um sublinhado, a consulta não retorna linhas: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;
Gerar contexto para o conjunto de contextos
Nesta seção, você vai preparar o ambiente local e usar o agente de engenharia de contexto para criar um arquivo de conjunto de contexto (context_set.json) para o gráfico de propriedades FinGraph no banco de dados do Spanner.
Configurar o ambiente
Para configurar o ambiente para o agente de engenharia de contexto, siga estas etapas:
- Instale a CLI do Antigravity. Para mais informações, consulte Primeiros passos com a CLI do Antigravity.
- Instale a CLI do Google Cloud.
Configure o Application Default Credentials (ADC). Execute o seguinte comando no terminal para fazer a autenticação:
gcloud auth application-default loginNo terminal, inicie a CLI do Antigravity:
agyConfigure a conexão do banco de dados do Spanner. Insira um comando que especifique explicitamente que você está gerando contexto para os gráficos de propriedades no banco de dados do Spanner e inclua o nome do gráfico de propriedades
FinGraphpara que o agente acione o fluxo de trabalho de engenharia de contexto específico do GQL:Help me set up the database connection for the FinGraph property graph in my Spanner database.Siga as instruções fornecidas pelo agente para criar
autoctx/tools.yamleautoctx/state.md. Em seguida, abraautoctx/state.mde verifique se a seção## Active Databasecontém a linha- **Graph Ids**: ["FinGraph"]. O agente de engenharia de contexto lê os nomes dos gráficos de propriedades dessa linha quando gera configurações de avaliação. Para mais informações sobre otools.yaml, consulte a documentação do MCP Toolbox.Para recarregar a configuração depois que
autoctx/tools.yamlfor criado, execute o seguinte comando na CLI do Antigravity:/mcpSelecione
toolboxe, em seguida,Restart.Verifique se o MCP Toolbox e o plug-in do agente de engenharia de contexto estão conectados e prontos para uso:
/mcp
Gerar contexto de modelo GQL
Para resolver o problema em que o QueryData não reconheceu o termo comercial high-risk transfers, defina high-risk transfers no arquivo de conjunto de contexto como transferências de 200 ou mais enviadas para uma conta bloqueada (dst.is_blocked = true).
Para gerar o contexto do modelo GQL, siga estas etapas:
Insira o comando a seguir na estrutura do agente, especificando que
FinGraphé um gráfico de propriedades no banco de dados do 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;O agente converte sua entrada em um modelo GQL parametrizado que generaliza os nomes de pessoas. Para mais informações, consulte Visão geral dos conjuntos de contexto.
Analise o modelo de consulta GQL gerado e envie o comando
Save it to context_set.jsonpara o agente. O agente criacontext_set.jsonno seu diretório com o seguinte conteúdo:{ "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 ?" } } ] }
Gerar contexto de pesquisa de atributo e valor
Nesta seção, você vai adicionar um atributo GQL e duas consultas de pesquisa de valor GRAPH_TABLE a context_set.json. O modelo adicionado na seção anterior responde a perguntas que têm a mesma estrutura de "Encontrar todas as transferências de alto risco iniciadas por Alex". O atributo captura o padrão de conta bloqueada para que o QueryData também possa aplicá-lo a perguntas que não correspondem ao modelo, como "Encontre todas as transferências de dinheiro que envolvem uma conta bloqueada". As pesquisas de valor permitem que o QueryData mapeie frases de valor, como Czech Republic, para o valor armazenado Czech_Republic em Person.country e correspondam a apelidos de conta em Account.nick_name, independentemente de maiúsculas e minúsculas.
Insira o comando a seguir na estrutura do agente, especificando que
FinGraphé um gráfico de propriedades no banco de dados do 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.Revise o arquivo
context_set.jsonatualizado, que agora contém o modelo GQL, o atributo GQL e as definições de pesquisa de valor:{ "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" } ] }Cada pesquisa de valor usa o operador
GRAPH_TABLEpara corresponder a um rótulo de nó emFinGraphe retorna o valor da propriedade armazenada, o local da propriedade (FinGraph.Person.country), o tipo de conceito, uma distância de0para uma correspondência e um contexto JSON vazio. Para mais informações, consulte Consultas de pesquisa de valor.
Fazer upload do arquivo de conjunto de contexto para o QueryData
Nesta seção, você vai fazer upload do arquivo context_set.json para o conjunto de contexto fingraph-assistant no Spanner Studio.
No console do Google Cloud , acesse a página do Spanner.
Selecione sua instância na lista e, em seguida, selecione seu banco de dados do Spanner.
No menu de navegação, clique em Spanner Studio.
No painel Explorer, ao lado do conjunto de contexto
fingraph-assistant, clique em Ver ações.Clique em Editar conjunto de contexto.
Opcional: edite a Descrição do conjunto de contexto.
Clique em Procurar na seção Fazer upload do arquivo do conjunto de contexto e selecione o arquivo
context_set.jsonque você gerou.Clique em Salvar.
Gerar consultas GQL usando o QueryData
Nesta seção, você vai chamar a API REST QueryData com o contexto fingraph-assistant definido para verificar se o QueryData traduz com precisão termos de negócios, como high-risk transfers, e resolve Czech Republic como Czech_Republic em consultas GQL.
- Encontre o ID do conjunto de contextos de
fingraph-assistant. Para instruções, consulte Encontrar o ID do conjunto de contexto. Defina a variável de ambiente
CONTEXT_SET_IDpara quequery_data.shenvie seu conjunto de contexto:export CONTEXT_SET_ID="CONTEXT_SET_ID"
Substitua
CONTEXT_SET_IDpelo ID completo do conjunto de contexto, comoprojects/my-project/locations/us-central1/contextSets/fingraph-assistant.Faça a pergunta sobre transferências de alto risco novamente:
./query_data.sh "Find all high-risk transfers initiated by Alex"
A consulta GQL gerada agora aplica o filtro de conta de destino bloqueada (
is_blocked: true) e o limite de valor (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;Isso exclui a transferência de
100feita por Alex para a conta bloqueada16e retorna resultados semelhantes a estes:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 300 | +------------------------+-----------------+Faça uma pergunta semelhante para
Dana:./query_data.sh "What are the high-risk transfers initiated by Dana?"
Como o modelo GQL em
context_set.jsoné parametrizado ({name: ?}), QueryData aplica a mesma definição dehigh-risk transfersaDana: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;Isso exclui a transferência de
500feita por Dana para a conta desbloqueada7e retorna resultados semelhantes a estes:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 200 | +------------------------+-----------------+Faça a pergunta sobre o país novamente:
./query_data.sh "Find accounts owned by people from Czech Republic"
O QueryData executa a pesquisa de valor
Person country, vinculaCzech Republicao valor armazenadoCzech_Republice gera uma consulta semelhante a esta: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;Isso retorna resultados semelhantes a estes:
+------------+------------+----------------+ | owner_name | account_id | nick_name | +------------+------------+----------------+ | Dana | 20 | Rainy Day Fund | +------------+------------+----------------+Faça uma pergunta que use o aspecto de conta bloqueada:
./query_data.sh "Find all money transfers involving a blocked account."
QueryData usa o atributo para corresponder às transferências em qualquer direção que envolvam a conta bloqueada
16e retorna quatro transferências.
Integrar o QueryData ao seu aplicativo
Nesta seção, você vai criar um aplicativo de agente de dados de conversação para o FinGraph usando o Kit de Desenvolvimento de Agente (ADK), o MCP Toolbox e o conjunto de contexto do fingraph-assistant. Para ativar a geração de consultas GQL para o Spanner Graph, defina uma ferramenta HTTP personalizada no arquivo tools.yaml que chama a API REST QueryData com graph_ids definido em spanner_reference.database_reference.
- Baixe a versão 1.4.0 ou mais recente do MCP Toolbox. O MCP Toolbox expõe a API REST
QueryDatacomo uma ferramenta do MCP para que os aplicativos se conectem. Configure o Application Default Credentials (ADC):
gcloud auth application-default loginCrie um arquivo de configuração
tools.yamlque defina uma fonte HTTP para a API Análise conversacional e uma ferramenta HTTP que chame o métodoQueryData. Especifiquegraph_ids(definido como["FinGraph"]) emspanner_reference.database_referenceno corpo da solicitação: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.A MCP Toolbox substitui as referências
${...}pelos valores das variáveis de ambiente correspondentes ao carregartools.yamle substitui{{json .query}}pela pergunta que o agente envia à ferramenta, codificada como uma string JSON.No terminal em que você executa o MCP Toolbox, defina as variáveis de ambiente que
tools.yamlreferencia: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)"
Substitua:
PROJECT_ID: o ID do projeto Google Cloud .INSTANCE_ID: o ID da instância do Spanner.DATABASE_ID: o ID do banco de dados do Spanner que contémFinGraph.CONTEXT_SET_ID: o ID do conjunto de contexto completo defingraph-assistant.
Execute o servidor do MCP Toolbox com o arquivo
tools.yaml:./toolbox --config "tools.yaml"Crie um aplicativo do ADK que invoque a ferramenta
fingraph_query_data_toolusando o SDK do Python do MCP Toolbox:Crie e mude para um diretório do aplicativo, como
fingraph-assistant-app:mkdir fingraph-assistant-appcd fingraph-assistant-appCrie um ambiente virtual e instale os pacotes necessários:
python3 -m venv .venvsource .venv/bin/activatepip install toolbox-corepip install google-genaipip install google-adkCrie um agente do ADK:
adk create my_agentSelecione o modelo
gemini-2.5-flash, escolha IA do Google e insira sua chave de API Gemini. Para mais informações, consulte Como usar chaves de API Gemini.Substitua o conteúdo de
my_agent/agent.pypelo seguinte código de aplicativo de exemplo do Assistente de Gráfico Financeiro: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]), )
Inicie o servidor da Web do ADK em
http://127.0.0.1:8000:adk web --port 8000Insira uma pergunta de gráfico de vários saltos na UI da Web do ADK:
Who did Dana transfer money to, and what were the amounts?O agente chama a ferramenta
fingraph_query_data_tool, que envia a pergunta para a API RESTQueryDatacomgraph_idsdefinido comoFinGraph. O QueryData executa a consulta GQL gerada, e o agente retorna uma resposta semelhante a esta:Dana transferred money from account 20 to the following recipients: * Alex (account 7): 500 * Lee (account 16): 200Insira uma pergunta que use o modelo GQL
high-risk transfersque você adicionou ao conjunto de contexto:What are the high-risk transfers initiated by Alex?Com base no modelo GQL em
fingraph-assistant, o QueryData identifica transferências de pelo menos200para uma conta bloqueada, e o agente retorna uma resposta semelhante a esta:Here is the high-risk transfer initiated by Alex (transfers of 200 or more to a blocked account): * Blocked destination account 16: amount 300
Iterar o desempenho do agente
A UI da Web do ADK permite inspecionar os payloads de solicitação e resposta da ferramenta fingraph_query_data_tool. Na guia Evento no painel de navegação, abra functionResponse para inspecionar a consulta GQL FinGraph gerada (generatedQuery), queryResult, intentExplanation, disambiguationQuestion e naturalLanguageAnswer. A API REST QueryData retorna esses nomes de campo em camelCase.
Refinar a precisão da resposta
É possível refinar continuamente a precisão das respostas do QueryData adicionando modelos GQL, atributos e pesquisas de valor. Use o agente de engenharia de contexto para gerar e avaliar o contexto atualizado do grafo de propriedades FinGraph no banco de dados do Spanner e, em seguida, faça upload do arquivo de conjunto de contexto atualizado no Spanner Studio. Para mais informações, consulte Gerenciar conjuntos de contexto no Spanner Studio.
Vários agentes
No ambiente de desenvolvimento, é possível realizar testes A/B em vários conjuntos de contexto do Spanner Graph definindo várias ferramentas HTTP no arquivo tools.yaml (como fingraph_query_data_tool_v1 e fingraph_query_data_tool_v2). O corpo da solicitação de cada ferramenta define graph_ids como ["FinGraph"] e um context_set_id diferente.
Limpar
Para evitar o faturamento contínuo, exclua os recursos criados ao concluir este tutorial.
Excluir o conjunto de contexto
Antes de excluir o banco de dados ou a instância do Spanner, exclua o conjunto de contexto fingraph-assistant:
No console do Google Cloud , acesse a página do Spanner.
Selecione sua instância na lista e, em seguida, selecione seu banco de dados do Spanner.
No menu de navegação, clique em Spanner Studio.
No painel Explorer, ao lado de
fingraph-assistant, clique em Ver ações.Clique em Excluir conjunto de contexto, insira
fingraph-assistantno campo de confirmação e clique em Confirmar.
Excluir o banco de dados e a instância
Para excluir o gráfico de propriedades FinGraph, o banco de dados e a instância do Spanner, siga as etapas em Configurar e consultar o Spanner Graph: limpar.
A seguir
- Saiba mais sobre os conjuntos de contexto do Spanner Graph.
- Saiba como criar conjuntos de contexto usando o agente de engenharia de contexto.
- Saiba como definir o contexto criado para fontes de dados de banco de dados.