Crea agenti dati

Gli agenti di dati conversazionali ti consentono di interagire con i dati del database utilizzando un'interfaccia in linguaggio naturale. Creando questi agenti, aiuti gli utenti a "parlare con i loro dati", estraendo informazioni dai database operativi senza richiedere loro di scrivere query SQL complesse.

A livello generale, un agente di dati è una combinazione di persona, un insieme di origini dati, con accesso a un insieme di conoscenze aziendali fondamentali per i suoi scopi.

Per gli sviluppatori di applicazioni, questi agenti offrono i seguenti vantaggi:

  • Elevata precisione: utilizzando il contesto creato, puoi ottenere un'elevata precisione per domande aziendali specifiche. Il contesto creato è il fattore chiave principale che i creator di agenti possono utilizzare per migliorare l'accuratezza. Include descrizioni dello schema, istruzioni di sistema e contesto strutturato che fornisce informazioni aggiuntive sulle query di database previste.
  • Complessità ridotta: gli agenti traducono il linguaggio naturale in query SQL, esecuzione e persino riepilogo o visualizzazione dei dati.
  • Flessibilità: puoi creare agenti per test personali oppure pubblicarli per renderli disponibili ad altri utenti del tuo progetto o programmaticamente utilizzando l'API.

Prima di iniziare

  1. Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

  2. Abilita le API Cloud SQL, API Data Analytics con Gemini e Gemini for Google Cloud .

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilita le API

Ruoli obbligatori

Per lavorare con gli agenti dati, devi disporre di uno dei seguenti ruoli Identity and Access Management (IAM) dell'API Analisi conversazionale:

  • Esegui query sui dati dalle origini database supportate utilizzando il metodo QueryData: Gemini Data Analytics Data Query User (roles/geminidataanalytics.queryDataUser) a livello di progetto.
  • Crea, modifica, condividi ed elimina tutti gli agenti dati nel progetto: Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) a livello di progetto.
  • Crea i tuoi agenti dei dati nel progetto: Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) a livello di progetto. Questo ruolo ti concede automaticamente il ruolo Gemini Data Analytics Data Agent Owner per gli agenti dati che crei.
  • Visualizza e modifica tutti gli agenti dati nel progetto: Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) a livello di progetto.
  • Visualizza tutti gli agenti dati nel progetto: Gemini Data Analytics Data Agent Visualizzatore (roles/geminidataanalytics.dataAgentViewer) a livello di progetto.

Inoltre, per creare o modificare un agente di dati, devi disporre dei seguenti ruoli:

Quando gestisci l'accesso alle risorse di database Cloud SQL per PostgreSQL, considera i seguenti livelli di autorizzazioni:

  • Google Cloud IAM: controlla l'accesso all'istanza del database come risorsa cloud. Sono incluse le autorizzazioni per connettersi, gestire l'istanza ed eseguire query SQL, ad esempio utilizzando l'autorizzazione executeSql.
  • Autorizzazioni del database: controlla l'accesso agli oggetti nel database, ad esempio tabelle, viste e schemi. Questi vengono gestiti utilizzando comandi SQL come GRANT e sistemi di utenti e ruoli specifici del database.

Per Cloud SQL per PostgreSQL, devi disporre dei ruoli IAM Cloud SQL appropriati per connetterti all'istanza ed essere autorizzato a inviare query. Per interagire con oggetti come tabelle e viste, l'utente del database di connessione deve disporre dei privilegi necessari concessi utilizzando il sistema GRANT di Cloud SQL per PostgreSQL. Per saperne di più, consulta Informazioni su utenti e ruoli PostgreSQL. Se l'agente utilizza un account di servizio, puoi ottenere l'assegnazione di un ruolo di database. Per esempio, vedi Gestire gli utenti con l'autenticazione IAM dei database.

Crea un agente di dati

Le sezioni seguenti descrivono come creare un agente dati. Dopo aver creato un agente, puoi modificarne le impostazioni.

Configura le impostazioni di base

  1. Nella console Google Cloud , vai alla pagina Cloud SQL per PostgreSQL.

    Vai a Cloud SQL

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Agenti.

  4. Fai clic sulla scheda Agenti.

  5. Seleziona un database e accedi utilizzando il tuo account IAM.

  6. Fai clic su Nuovo agente. Viene visualizzata la pagina Nuovo agente.

  7. Nella sezione Editor, nel campo Nome agente, inserisci un nome descrittivo per l'agente di dati, ad esempio Q4 sales data o User activity logs.

  8. Nel campo Descrizione dell'agente, inserisci una descrizione dell'agente di dati. Una buona descrizione spiega cosa fa l'agente, quali dati utilizza e ti aiuta a determinare se si tratta dell'agente dati corretto da utilizzare per una conversazione, ad esempio What are the top 10 selling products in Q2?

  9. Nella sezione Fonti di conoscenza, fai clic su Aggiungi fonte. Viene visualizzata la pagina Aggiungi dati.

  10. Seleziona le tabelle su cui l'agente si concentrerà quando risponde alle domande. Per visualizzare altre fonti di conoscenza, seleziona Mostra altro.

  11. Fai clic su Aggiungi. Viene riaperta la nuova pagina dell'agente.

Personalizzare le descrizioni di tabelle e campi

Per migliorare l'accuratezza dell'agente di dati conversazionali, puoi fornire facoltativamente metadati aggiuntivi della tabella. Solo l'agente dati utilizza questi metadati e non influiscono sulla tabella di origine. Puoi aggiungere i seguenti metadati:

  • Descrizioni dello schema:aggiungi descrizioni per tabelle e colonne per aiutare l'agente a comprendere i tuoi dati. Se non aggiungi descrizioni, l'agente utilizza le descrizioni dello schema dalle definizioni dei dati.

Segui queste best practice quando aggiungi descrizioni di tabelle e campi:

  • Aggiungi descrizioni alla definizione dei dati anziché solo alla definizione dell'agente dati. In questo modo, anche altri agenti possono trarre vantaggio dalle descrizioni.
  • Per prototipare la descrizione appropriata per aiutare gli agenti di dati a comprendere i tuoi dati, aggiungi descrizioni al tuo agente specifico. Dopo aver verificato che la descrizione abbia l'impatto previsto, puoi decidere se aggiungerla alla definizione dei dati.

Per configurare le descrizioni di tabelle e campi:

  1. Nella scheda Catalogo agenti, apri l'agente che vuoi personalizzare.
  2. Fai clic su Modifica agente.
  3. In Fonti di conoscenza, trova la tabella che vuoi personalizzare e fai clic su Personalizza.
  4. Inserisci una descrizione della tabella.
  5. Per modificare la descrizione di un campo, fai clic su Modifica accanto al campo. Viene visualizzato il riquadro Modifica campo.
    1. Nel campo ID, inserisci una descrizione del campo.
    2. Per salvare la descrizione del campo, fai clic su Aggiorna.
  6. Per salvare la descrizione e gli aggiornamenti dei campi, fai clic su Aggiorna. Si riapre la nuova pagina dell'agente.
  7. Ripeti questi passaggi per ogni tabella che vuoi personalizzare.

Aggiungere etichette agli agenti dati

Nella sezione Impostazioni agente, puoi creare etichette per organizzare le tue risorse Google Cloud . Le etichette sono coppie chiave-valore che consentono di raggruppare oggetti correlati fra loro o con altre risorse Google Cloud.

  1. Nella scheda Catalogo agenti, apri l'agente a cui vuoi aggiungere un'etichetta.
  2. Fai clic su Modifica agente.
  3. Nella sezione Impostazioni agente, fai clic su Aggiungi etichetta. Viene visualizzato il riquadro Gestisci etichette.
  4. Fai clic su Aggiungi etichetta.
  5. Nei campi chiave e valore, inserisci la coppia chiave-valore per l'etichetta.
  6. Se vuoi aggiungere altre etichette, fai di nuovo clic su Aggiungi etichetta.
  7. Per eliminare un'etichetta, fai clic su Elimina.
  8. Al termine, fai clic su Aggiungi. Viene riaperta la nuova pagina dell'agente.

Continua alla sezione successiva per mettere l'agente in modalità bozza o per pubblicarlo.

Visualizzare l'anteprima e pubblicare l'agente

  1. Nella sezione Anteprima, inserisci una domanda di esempio nel campo Fai una domanda e poi premi Invio.

    Per verificare che l'agente dati restituisca i dati che ti aspetti, esamina la risposta dell'agente. Se la risposta non è quella che ti aspetti, modifica le impostazioni nella sezione Editor per perfezionare la configurazione dell'agente dati finché non ottieni risposte soddisfacenti. Puoi continuare a testare e modificare l'agente per perfezionarne i risultati.

  2. Fai clic su Salva.

  3. Per mettere l'agente di dati in modalità bozza, che puoi modificare di nuovo in un secondo momento, fai clic su Torna indietro per tornare alla pagina Catalogo agenti. Poiché l'agente è ora in modalità bozza, viene visualizzato nella sezione I miei agenti bozza della scheda Catalogo agenti.

    Per pubblicare l'agente, rimani nella pagina di creazione dell'agente e vai al passaggio successivo.

  4. Per pubblicare l'agente dati e renderlo disponibile per l'utilizzo nel progetto, fai clic su Pubblica. La pubblicazione dell'agente consente ad altri utenti, che hanno accesso alle stesse tabelle di database, di visualizzare e interagire con il tuo agente, beneficiando delle istruzioni e del contesto che hai creato.

    Puoi creare conversazioni con l'agente dati utilizzando la pagina Agenti nella console Google Cloud . Puoi anche creare la tua interfaccia per chattare con l'agente di dati utilizzando l'API Analisi conversazionale.

  5. (Facoltativo) Nella finestra di dialogo Il tuo agente è stato pubblicato, fai clic su Condividi per condividere l'agente dati con altri utenti.

    1. Nel riquadro Autorizzazioni di condivisione, fai clic su Aggiungi entità.
    2. Nel campo Nuove entità, inserisci una o più entità.
    3. Fai clic sull'elenco Seleziona un ruolo.
    4. Nell'elenco Ruolo, seleziona uno dei seguenti ruoli:
      • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser): concede l'autorizzazione per chattare con il data agent.
      • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor): concede l'autorizzazione a modificare il data agent.
      • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer): concede l'autorizzazione a visualizzare il data agent.

  6. Fai clic su Salva.

  7. Per tornare alla nuova pagina dell'agente, fai clic su Chiudi. Dopo aver salvato o pubblicato l'agente, puoi visualizzarlo nel catalogo degli agenti.

Gestisci agenti dati

Puoi trovare gli agenti esistenti nella scheda Catalogo degli agenti, che è composta da tre sezioni:

  • I miei agenti: un elenco di tutti gli agenti che crei e pubblichi. Puoi modificare e condividere gli agenti pubblicati con altre persone.
  • Le mie bozze di agenti: gli agenti che non hai ancora pubblicato. Non puoi condividere le bozze di agenti.
  • Condivisi da altri membri della tua organizzazione: agenti creati e condivisi con te da altri utenti. Se altri ti concedono le autorizzazioni, puoi modificare questi agenti condivisi.

Modificare un agente dati

Per modificare un agente dati:

  1. Nella console Google Cloud , vai alla pagina Cloud SQL per PostgreSQL.

    Vai a Cloud SQL

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Agenti.

  4. Accedi ad Agenti utilizzando l'autenticazione Identity and Access Management (IAM).

  5. Fai clic sulla scheda Catalogo agenti.

  6. Individua la scheda dell'agente dati che vuoi modificare.

  7. Per aprire l'agente dati nell'editor degli agenti, fai clic su Apri azioni e poi su Modifica nella scheda dell'agente.

  8. Modifica la configurazione dell'agente dati in base alle esigenze.

  9. Per salvare le modifiche senza pubblicarle, fai clic su Salva.

  10. Per pubblicare le modifiche, fai clic su Pubblica. Nella finestra di dialogo Condividi, puoi condividere l'agente con altri utenti o fare clic su Annulla.

  11. Per tornare al riquadro Agenti, fai clic su Torna indietro.

Condividere un agente dati

Per condividere un agente dati pubblicato: Non puoi condividere agenti bozza.

  1. Nella console Google Cloud , vai alla pagina Cloud SQL per PostgreSQL.

    Vai a Cloud SQL

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Agenti.

  4. Accedi ad Agenti utilizzando l'autenticazione Identity and Access Management (IAM).

  5. Fai clic sulla scheda Catalogo agenti.

  6. Individua la scheda dell'agente dati che vuoi modificare.

  7. Per aprire l'agente dati nell'editor degli agenti, fai clic su Apri azioni > fai clic su Modifica nella scheda dell'agente.

  8. Per condividere l'agente dati con altri utenti, fai clic su Condividi.

  9. Nel riquadro Autorizzazioni di condivisione, fai clic su Aggiungi entità.

  10. Nel campo Aggiungi entità, inserisci una o più entità.

  11. Fai clic su Seleziona un ruolo.

  12. Nell'elenco Ruolo, seleziona uno dei seguenti ruoli:

    • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser): concede l'autorizzazione a chattare con il data agent.
    • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor): concede l'autorizzazione per modificare il data agent.
    • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer): concede l'autorizzazione a visualizzare l'agente dati.

  13. Fai clic su Salva.

  14. Per tornare alla pagina di modifica dell'agente, fai clic su Chiudi.

  15. Per tornare al riquadro Agenti, fai clic su Indietro.

Eliminare un agente di dati

  1. Nella console Google Cloud , vai alla pagina Cloud SQL per PostgreSQL.

    Vai a Cloud SQL

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Agenti.

  4. Accedi ad Agenti utilizzando l'autenticazione Identity and Access Management (IAM).

  5. Seleziona la scheda Catalogo agenti.

  6. Nella sezione Agenti della scheda Catalogo agenti, individua la scheda dell'agente di dati che vuoi eliminare.

  7. Fai clic su Apri azioni > Elimina.

  8. Nella finestra di dialogo Eliminare l'agente?, fai clic su Elimina. Se elimini l'agente in modo definitivo, questo viene rimosso dal progetto.

    Dopo aver eliminato un agente, le conversazioni esistenti sono disponibili in modalità di sola visualizzazione. Non puoi porre nuove domande all'agente eliminato.

Località

L'analisi conversazionale opera a livello globale, quindi non puoi scegliere la regione da utilizzare.

Passaggi successivi