Definir o contexto do agente de dados para fontes de dados de banco de dados

Nesta página, descrevemos como fornecer contexto criado para agentes de dados que usam fontes de dados de banco de dados.

O contexto criado é uma orientação que os proprietários de agentes de dados podem fornecer para moldar o comportamento de um agente de dados e refinar as respostas da API. Um contexto criado de forma eficaz fornece aos agentes de dados da API Análise conversacional um contexto útil para responder a perguntas sobre suas fontes de dados.

Para fontes de dados de banco de dados, como AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL e Cloud SQL para PostgreSQL, você fornece contexto criado primeiro definindo e armazenando o contexto no banco de dados e, em seguida, referenciando-o na referência da fonte de dados. Os exemplos nesta página usam o método QueryData.

Fornecer um contexto de alta precisão permite que a API gere consultas e respostas SQL mais precisas e relevantes.

Antes de começar

Como fornecer contexto com QueryData

Ao chamar o método QueryData, você fornece a fonte de dados e as informações de contexto no campo QueryDataRequest.context.datasourceReferences. Para fontes de dados de banco de dados, use uma das seguintes opções:

  • alloydb para AlloyDB para PostgreSQL
  • spanner_reference para GoogleSQL para Spanner
  • cloud_sql_reference para Cloud SQL para MySQL e Cloud SQL para PostgreSQL

Nessas referências, você especifica o banco de dados e as tabelas usando o campo databaseReference. Para incluir o contexto criado, você também precisa fornecer um agentContextReference que aponte para um context_set_id.

Exemplo de solicitação QueryData com contexto criado

O exemplo a seguir mostra uma solicitação QueryData que usa alloydb. O campo agent_context_reference.context_set_id é usado para vincular ao contexto pré-criado armazenado no banco de dados.

AlloyDB

{
 "parent": "projects/data-agents-project/locations/us-central1",
 "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
 "context": {
   "datasource_references": [
     {
       "alloydb": {
         "database_reference": {
           "project_id": "data-agents-project",
           "region": "us-central1",
           "cluster_id": "sqlgen-magic",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates"
         }
       }
     }
   ]
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

GoogleSQL para Spanner

{
 "parent": "projects/data-agents-project/locations/us-central1",
 "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
 "context": {
   "datasource_references": [
     {
       "spanner_reference" {
         "database_reference" {
           "engine": "GOOGLE_SQL"
           "project_id": "data-agents-project"
           "instance_id": "evalbench"
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates"
         }
       }
     }
   ]
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

Spanner Graph

{
 "parent": "projects/data-agents-project/locations/global",
 "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
 "context": {
   "datasource_references": {
     "spanner_reference": {
       "database_reference": {
         "engine": "GOOGLE_SQL",
         "project_id": "data-agents-project",
         "instance_id": "data-agents-instance",
         "database_id": "fin-graph-db",
         "graph_ids": [
           "FinGraph"
         ]
       },
       "agent_context_reference": {
         "context_set_id": "projects/data-agents-project/locations/us-central1/contextSets/fingraph-assistant"
       }
     }
   }
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

Cloud SQL para MySQL

{
 "parent": "projects/data-agents-project/locations/us-central1",
 "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
 "context": {
   "datasource_references": [
     {
       "cloud_sql_reference": {
         "database_reference": {
           "engine": "MYSQL"
           "project_id": "data-agents-project",
           "region": "us-central1",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates"
         }
       }
     }
   ]
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

Cloud SQL para PostgreSQL

{
 "parent": "projects/data-agents-project/locations/us-central1",
 "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
 "context": {
   "datasource_references": [
     {
       "cloud_sql_reference": {
         "database_reference": {
           "engine": "POSTGRES"
           "project_id": "data-agents-project",
           "region": "us-central1",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates"
         }
       }
     }
   ]
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

O corpo da solicitação contém os seguintes campos:

  • prompt: a pergunta em linguagem natural do usuário final.
  • context: contém informações sobre as fontes de dados.
    • datasource_references: especifica o tipo de fonte de dados.
      • alloydb: obrigatório ao consultar o banco de dados. Esse campo muda de acordo com o banco de dados que você está consultando.
        • database_reference: especifica informações relacionadas à instância do banco de dados.
          • engine: o mecanismo de banco de dados ou dialeto SQL. Opcional para o AlloyDB. Para bancos de dados do Spanner, defina como GOOGLE_SQL. Para instâncias do Cloud SQL para MySQL, defina como MYSQL. Para instâncias do Cloud SQL para PostgreSQL, defina como POSTGRESQL.
          • project_id: o ID do projeto da instância do banco de dados.
          • region: a região da instância do banco de dados.
          • cluster_id: o ID do cluster da instância de banco de dados.
          • instance_id: o ID da instância do banco de dados.
          • database_id: o ID do banco de dados.
          • graph_ids: obrigatório para o Spanner Graph. Uma lista de nomes de gráficos de propriedades no banco de dados do Spanner para consulta (por exemplo, ["FinGraph"]). Se você omitir graph_ids, o QueryData vai gerar consultas do GoogleSQL nas tabelas subjacentes em vez de consultas GQL.
        • agent_context_reference: links para o contexto criado no banco de dados.
  • generationOptions: configura o tipo de saída a ser gerada.
    • generate_query_result: defina como verdadeiro para gerar e retornar os resultados da consulta.
    • generate_natural_language_answer: opcional. Se definido como verdadeiro, gera uma resposta em linguagem natural.
    • generate_explanation: opcional. Se definido como verdadeiro, gera uma explicação da consulta SQL.
    • generate_disambiguation_question: opcional. Se definido como verdadeiro, gera perguntas de desambiguação se a consulta for ambígua.

Exemplo de resposta QueryData

Veja um exemplo de resposta bem-sucedida de uma chamada QueryData:

{
 "generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
 "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
 "query_result": {
   "columns": [
     {
       "name": "count"
     }
   ],
   "rows": [
     {
       "values": [
         {
           "value": "2"
         }
       ]
     }
   ],
   "total_row_count": 1
 },
 "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}