Definisci il contesto dell'agente dati per le origini dati del database

Questa pagina descrive come fornire un contesto creato per gli agenti per i dati che utilizzano origini dati del database.

Il contesto creato è una guida che i Data Agent Owner possono fornire per modellare il comportamento di un agente per i dati e perfezionare le risposte dell'API. Un contesto creato in modo efficace fornisce agli agenti per i dati dell'API Analisi conversazionale un contesto utile per rispondere alle domande sulle origini dati.

Per le origini dati del database come AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL, fornisci il contesto creato definendolo e archiviandolo prima nel database, quindi facendovi riferimento nel riferimento all'origine dati. Gli esempi in questa pagina utilizzano il metodo QueryData.

Fornire un contesto di alta precisione consente all'API di generare query SQL e risposte più accurate e pertinenti.

Prima di iniziare

Fornire contesto con QueryData

Quando chiami il metodo QueryData, fornisci l'origine dati e le informazioni di contesto nel campo QueryDataRequest.context.datasourceReferences. Per le origini dati del database, devi utilizzare uno dei seguenti elementi:

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

All'interno di questi riferimenti, specifichi il database e le tabelle utilizzando il campo databaseReference. Per includere il contesto dell'autore, devi anche fornire un agentContextReference che rimandi a un context_set_id.

Esempio di richiesta QueryData con contesto creato

L'esempio seguente mostra una richiesta QueryData che utilizza alloydb. Il campo agent_context_reference.context_set_id viene utilizzato per collegare il contesto pre-creato archiviato nel database.

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 per 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 per 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 per 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
 }
}

Il corpo della richiesta contiene i seguenti campi:

  • prompt: la domanda in linguaggio naturale dell'utente finale.
  • context: contiene informazioni sulle origini dati.
    • datasource_references: specifica il tipo di origine dati.
      • alloydb: obbligatorio quando si esegue una query sul database. Questo campo cambia in base al database su cui stai eseguendo la query.
        • database_reference: : specifica le informazioni relative all'istanza del database.
          • engine: il motore del database o il dialetto SQL. Facoltativo per AlloyDB. Per i database Spanner, imposta su GOOGLE_SQL. Per le istanze Cloud SQL per MySQL, imposta su MYSQL. Per le istanze Cloud SQL per PostgreSQL, imposta su POSTGRESQL.
          • project_id: l'ID progetto dell'istanza di database.
          • region: la regione dell'istanza di database.
          • cluster_id: l'ID cluster dell'istanza di database.
          • instance_id: l'ID istanza del database.
          • database_id: l'ID del database.
          • graph_ids: obbligatorio per Spanner Graph. Un elenco di nomi di grafi di proprietà nel database Spanner su cui eseguire query (ad esempio ["FinGraph"]). Se ometti graph_ids, QueryData genera query GoogleSQL sulle tabelle sottostanti anziché query GQL.
        • agent_context_reference: link al contesto creato nel database.
  • generationOptions: configura il tipo di output da generare.
    • generate_query_result: impostato su true per generare e restituire i risultati della query.
    • generate_natural_language_answer: (Facoltativo) Se impostato su true, genera una risposta in linguaggio naturale.
    • generate_explanation: (Facoltativo) Se impostato su true, genera una spiegazione della query SQL.
    • generate_disambiguation_question: (Facoltativo) Se impostato su true, genera domande di disambiguazione se la query è ambigua.

Risposta di esempio QueryData

Ecco un esempio di risposta corretta da una chiamata 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."
}