Ispezionare e chiamare un agente di dati

Questo documento descrive come ispezionare un agente e aggiornare il file di contesto dell'agente. Puoi ispezionare un agente per testare la sua capacità di generare query SQL da domande in linguaggio naturale. Se una query generata non è accurata, puoi aggiornare il contesto dell'agente.

Per scoprire di più sugli agenti di dati, consulta la panoramica degli agenti di dati.

Prima di iniziare

Assicurati che sia già stato creato un agente di dati e che il contesto dell'agente sia stato caricato nell'agente di dati. Per ulteriori informazioni, consulta Gestire gli agenti di dati in Spanner Studio.

Ispezionare un agente di dati

Per ispezionare un agente di dati:

  1. Nella Google Cloud console, vai alla pagina Spanner.

    Vai a Spanner

  2. Seleziona un'istanza dall'elenco, quindi seleziona un database.

  3. Nel menu di navigazione, fai clic su Spanner Studio.

  4. Nel riquadro Explorer, fai clic su Visualizza azioni accanto all'agente di dati che stai utilizzando.

  5. Fai clic su Ispeziona agente.

  6. Nell'editor di query, fai clic su Genera SQL per aprire il riquadro Aiutami a programmare.

  7. Inserisci una domanda in linguaggio naturale nell'editor per generare una query SQL e fai clic su Genera.

  8. Esamina la query SQL per verificarne l'accuratezza.

Scaricare e aggiornare il contesto per un agente di dati

Se non sei soddisfatto della query SQL generata per una domanda in linguaggio naturale, scarica il file di contesto dell'agente esistente. Puoi quindi esaminare e aggiornare il modello di query e ricaricare il file di contesto aggiornato nell'agente.

Per scaricare e aggiornare il contesto per un agente di dati:

  1. Nel riquadro Explorer, fai clic su Visualizza azioni.
  2. Fai clic su Scarica il file di contesto dell'agente.
  3. Segui i passaggi descritti in Creare contesti utilizzando Gemini CLI per aggiornare il contesto con altre coppie di query.
  4. Nel riquadro Explorer, fai clic su Visualizza azioni accanto all'agente di dati che stai utilizzando.
  5. Fai clic su Modifica agente.
  6. Fai clic su Sfoglia nella sezione Carica il file di contesto dell'agente e seleziona il file di contesto dell'agente aggiornato.
  7. Fai clic su Salva per aggiornare il contesto dell'agente.

Una volta soddisfatto dell'accuratezza delle risposte, puoi utilizzare l'endpoint QueryData per connettere l'applicazione all'agente di dati.

Trovare l'ID contesto agente

Per connettere un'applicazione di dati all'agente di dati, devi disporre dell'ID contesto dell'agente.

  1. Nella Google Cloud console, vai alla pagina Spanner.

    Vai a Spanner

  2. Seleziona un'istanza dall'elenco, quindi seleziona un database.

  3. Nel menu di navigazione, fai clic su Spanner Studio.

  4. Nel riquadro Explorer, fai clic su Visualizza azioni accanto all'agente di dati che stai utilizzando.

  5. Fai clic su Modifica agente.

  6. Prendi nota dell'ID contesto in ID contesto agente. Il formato dell'ID contesto agente è simile a projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates.

Connettere l'agente di dati all'applicazione

Imposta l'ID contesto agente nella chiamata al metodo QueryData per fornire il contesto creato per le origini dati del database, come AlloyDB, Spanner, Cloud SQL e Cloud SQL per PostgreSQL. Per ulteriori informazioni, consulta Definire il contesto dell'agente di dati per le origini dati del database

Dopo aver ispezionato l'agente di dati, puoi fare riferimento all'origine dati del database nella chiamata QueryData.

Esempio di richiesta QueryData con contesto creato

L'esempio seguente mostra una richiesta QueryData che utilizza l'origine dati del database spanner_reference. Il campo agent_context_reference.context_set_id viene utilizzato per collegarsi al contesto pre-creato archiviato nel database.

{
  "parent": "projects/data-agents-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region 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"
            "region": "us-central1"
            "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
  }
}

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.
      • spanner_reference: 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 dialetto SQL del database. Imposta su GOOGLE_SQL per i database Spanner.
          • project_id: l'ID progetto dell'istanza del database.
          • region: la regione dell'istanza Spanner.
          • instance_id: l'ID istanza dell'istanza Spanner.
          • database_id: l'ID del database.
        • agent_context_reference: si collega al contesto creato nel database.
          • context_set_id: l'ID contesto agente completo del contesto archiviato nel database. Ad esempio, projects/data-agents-project/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates.
  • generationOptions: configura il tipo di output da generare.
    • generate_query_result: imposta 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.

Esempio di risposta QueryData

Di seguito è riportato un esempio di risposta riuscita 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."
}

Passaggi successivi