Crea agenti dati

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

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", sbloccando informazioni dettagliate 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:

• Alta precisione: utilizzando il contesto creato, puoi ottenere un'elevata accuratezza per domande aziendali specifiche. Il contesto creato è il fattore chiave principale che i creatori 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 i test personali oppure pubblicarli per renderli disponibili ad altri utenti del tuo progetto o a livello di programmazione utilizzando l'API.

Prima di iniziare

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

2. Abilita Cloud SQL, l'API Data Analytics con Gemini e Gemini for Google Cloud APIs.

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre del ruolo IAM Amministratore di Service Usage (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

   Abilita le API

Ruoli obbligatori

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

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

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

• Un utente IAM o un account di servizio aggiunto a livello di istanza. Per ulteriori informazioni, consulta Aggiungere un'associazione di policy IAM a un utente, account di servizio o un gruppo.
• I ruoli cloudsql.studioUser e cloudsql.instanceUser concessi all'utente IAM a livello di progetto. Per ulteriori informazioni, consulta Aggiungere un'associazione di policy IAM per un progetto.

• Privilegi del database concessi a un utente IAM o a un service account accedendo come utente del database basato su password.

  GRANT ALL PRIVILEGES ON *.* TO '[e-mail]';
  

  Per ulteriori informazioni, consulta Concedere i privilegi del database a un singolo utente IAM o service account.

Quando gestisci l'accesso alle risorse del database Cloud SQL per MySQL, tieni presente 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: controllano l'accesso agli oggetti nel database, come 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 MySQL, devi disporre dei ruoli IAM di 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 MySQL. Per ulteriori informazioni, consulta Informazioni sugli utenti di Cloud SQL per MySQL. Se l'agente utilizza un account di servizio, puoi assegnare un ruolo database. Ad esempio, consulta Gestire gli utenti con l'autenticazione IAM del database.

Creare un agente di dati

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

Configura le impostazioni di base

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

   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 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 di dati corretto da utilizzare per una conversazione, ad esempio, What are the top 10 selling products in Q2?

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

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

11. Fai clic su Aggiungi. Viene riaperta la pagina del nuovo agente.

Personalizzare le descrizioni di tabelle e campi

Per migliorare l'accuratezza dell'agente di dati conversazionale, puoi fornire facoltativamente metadati aggiuntivi della tabella. Solo l'agente di dati utilizza questi metadati, che 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 delle definizioni dei dati.

Quando aggiungi descrizioni di tabelle e campi, attieniti alle seguenti best practice:

• Aggiungi le descrizioni alla definizione dei dati anziché solo alla definizione dell'agente di dati. In questo modo, anche gli altri agenti traggono vantaggio dalle descrizioni.
• Per creare un prototipo della descrizione appropriata per aiutare gli agenti di dati a comprendere i tuoi dati, aggiungi le 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 Origini di conoscenza, trova la tabella che vuoi personalizzare e poi fai clic su Personalizza.
4. Inserisci la 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. Viene riaperta la pagina del nuovo agente.
7. Ripeti questi passaggi per ogni tabella che vuoi personalizzare.

Aggiungere etichette agli agenti di dati

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

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 pagina del nuovo agente.

Vai 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 Poni una domanda e poi premi Invio.

   Per verificare che l'agente di dati restituisca i dati previsti, esamina la risposta dell'agente. Se la risposta non è quella prevista, modifica le impostazioni nella sezione Editor per perfezionare la configurazione dell'agente di 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 di 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 conversare con il tuo agente, beneficiando delle istruzioni e del contesto che hai creato.

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

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

   1. Nel riquadro Condividi autorizzazioni, 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:
      • Utente agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser): concede l'autorizzazione a chattare con l'agente di dati.
      • Editor agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor): concede l'autorizzazione a modificare l'agente di dati.
      • Visualizzatore agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer): concede l'autorizzazione a visualizzare l'agente di dati.

6. Fai clic su Salva.

7. Per tornare alla pagina del nuovo agente, fai clic su Chiudi. Dopo aver salvato o pubblicato l'agente, puoi visualizzarlo nel Catalogo agenti.

Gestire gli agenti di dati

Puoi trovare gli agenti esistenti nella scheda Catalogo 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 altri.
• I miei agenti bozza: agenti che non hai ancora pubblicato. Non puoi condividere gli agenti bozza.
• Condiviso da altri membri della tua organizzazione: agenti creati e condivisi con te da altri. Se altri ti concedono le autorizzazioni, puoi modificare questi agenti condivisi.

Modificare un agente di dati

Per modificare un agente di dati:

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

   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 IAM (Identity and Access Management).

5. Fai clic sulla scheda Catalogo agenti.

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

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

8. Modifica la configurazione dell'agente di 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 oppure fare clic su Annulla.

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

Condividere un agente di dati

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

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

   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 IAM (Identity and Access Management).

5. Fai clic sulla scheda Catalogo agenti.

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

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

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

9. Nel riquadro Condividi autorizzazioni, 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:

    • Utente agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser): concede l'autorizzazione a chattare con l'agente di dati.
    • Editor agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor): concede l'autorizzazione a modificare l'agente di dati.
    • Visualizzatore agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer): concede l'autorizzazione a visualizzare l'agente di 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 Torna indietro.

Eliminare un agente di dati

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

   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 IAM (Identity and Access Management).

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. L'eliminazione dell'agente lo rimuove definitivamente 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; non puoi scegliere la regione da utilizzare.

Passaggi successivi

• Scopri di più sull'analisi conversazionale in Cloud SQL per MySQL.
• Scopri di più sull'API Analisi conversazionale.
• Analizza i dati con le conversazioni.
• Scopri di più su come il ruolo Visualizzatore agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) concede l'autorizzazione a visualizzare l'agente di dati.