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 approfondite 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 attivata per il tuo progetto Google Cloud .

  2. Abilita le API Cloud SQL, 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 di dati, devi disporre delle autorizzazioni IAM che corrispondono al tuo caso d'uso. La tabella seguente elenca i ruoli richiesti in base alla creazione e alla pubblicazione di agenti, al provisioning degli agenti in Gemini Enterprise o all'individuazione e all'utilizzo degli agenti. Per saperne di più, consulta Ruoli di Identity and Access Management dell'API Conversational Analytics.

Caso d'uso Ruoli obbligatori
Creare, modificare, pubblicare, condividere ed eliminare agenti
  • Per creare data agent in un progetto: Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) nel progetto. Questo ruolo ti concede automaticamente il ruolo di proprietario di Gemini Data Analytics Data Agent per i data agent che crei.
  • Per modificare, condividere o eliminare un agente dati: Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) sull'agente o sul progetto.
  • Per modificare un agente dati in un progetto: Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) nel progetto.
  • Per visualizzare gli agenti dati in un progetto: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) nel progetto.
  • Inoltre, per creare o modificare un agente dati, devi disporre dei seguenti ruoli:
Esegui il provisioning degli agenti in Gemini Enterprise

Per rendere disponibile un agente pubblicato agli utenti di Gemini Enterprise, devi disporre delle autorizzazioni per registrare e gestire gli agenti A2A nella console di amministrazione di Gemini Enterprise.
Scoprire e utilizzare gli agenti
  • Per chattare con gli agenti dati: Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser).
  • Per visualizzare tutti gli agenti dati nel progetto: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer).

Quando gestisci l'accesso alle risorse del database Cloud SQL per MySQL, 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 MySQL, 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 MySQL. Per ulteriori informazioni, consulta Informazioni sugli utenti di Cloud SQL per MySQL. Se l'agente utilizza un account di servizio, puoi ottenere un ruolo di database assegnato. 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 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 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 delle 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 Google Cloud risorse. 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 Poni 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 degli 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 del 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 dati utilizzando l'API Conversational Analytics.

  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.
    5. Fai clic su Salva.

  6. (Facoltativo) Puoi pubblicare l'agente dati su Gemini Enterprise. Per saperne di più, consulta Pubblicare un agente dati in Gemini Enterprise.

  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 altri.
  • I miei agenti bozza: gli agenti che non hai ancora pubblicato. Non puoi condividere bozze di agenti.
  • Condiviso 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 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 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 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 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 a modificare il data agent.
    • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer): concede l'autorizzazione a visualizzare il data agent.

  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 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 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.

Pubblica un agente dati in Gemini Enterprise

La pubblicazione di un agente virtuale richiede la collaborazione tra analisti dei dati, amministratori di Gemini Enterprise e utenti aziendali. Per scoprire i ruoli richiesti per questi utenti, vedi Ruoli richiesti.

Crea e pubblica un agente

Per creare, modificare e pubblicare un agente:

  1. Crea o modifica l'agente dati in Cloud SQL per MySQL.
  2. Pubblica l'agente. Quando pubblichi l'agente, seleziona Gemini Enterprise come opzione di pubblicazione.
  3. Per copiare il JSON dell'endpoint A2A, fai clic su Copia JSON.
  4. Condividi il JSON dell'endpoint A2A e l'elenco degli utenti con l'amministratore di Gemini Enterprise in modo che possa registrare l'agente personalizzato nella console Google Cloud e configurare le autorizzazioni di accesso. Per maggiori informazioni, consulta Provisioning di un agente.
  5. Condividi l'agente con gli utenti e i gruppi che devono accedervi.

Esegui il provisioning di un agente

Per rendere disponibile un agente pubblicato agli utenti nella console Google Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai a Gemini Enterprise.

    Gemini Enterprise

  2. Fai clic sul nome dell'app in cui vuoi registrare l'agente.

  3. Fai clic su Agenti > Aggiungi agenti.

  4. Nella sezione Scegli un tipo di agente, fai clic su Aggiungi per Agente personalizzato tramite A2A.

  5. Nel campo JSON della scheda dell'agente, inserisci i dettagli della scheda dell'agente che hai ricevuto in precedenza dall'analista dei dati in formato JSON.

  6. Fai clic su Visualizza dettagli agente > Avanti.

  7. Per consentire all'agente di accedere Google Cloud alle risorse per tuo conto, segui questi passaggi:

    1. Inserisci l'ID client e il client secret che hai generato nella sezione Configura i dettagli di autorizzazione.

    2. Nel campo URI di autorizzazione, inserisci quanto segue:

      https://accounts.google.com/o/oauth2/v2/auth?client_id=client_id&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

      Sostituisci client_id con l'ID client che hai generato in Configura i dettagli di autorizzazione.

    3. Nel campo URI token, inserisci quanto segue:

      https://oauth2.googleapis.com/token

    4. Nel campo Ambiti, inserisci quanto segue:

      https://www.googleapis.com/auth/cloud-platform

  8. Fai clic su Fine.

  9. Condividi l'agente con gli utenti o i gruppi.

Per saperne di più, consulta Registrare e gestire gli agenti A2A.

Trovare e utilizzare un agente

Puoi trovare e utilizzare un agente dati in Gemini Enterprise utilizzando uno dei seguenti metodi:

  • Individua l'agente nella Galleria degli agenti e avvia una chat dedicata.
  • Utilizza l'URL dedicato dell'agente per aprire Gemini Enterprise direttamente in una sessione con l'agente di dati Cloud SQL per MySQL specifico.
  • Richiama l'agente scrivendo un @mention, ad esempio @sales_pipeline_agent, nella chat principale di Gemini Enterprise.
  • Fai una domanda analitica generale, ad esempio "Qual è l'andamento della nostra pipeline di vendita negli ultimi tre mesi?", per consentire a Gemini Enterprise di indirizzare automaticamente la query all'agente di dati pertinente.

Dopo aver trovato l'agente, puoi interagire con lui utilizzando uno dei seguenti metodi:

  • Completa l'accesso OAuth una tantum per l'autenticazione sicura a Cloud SQL per MySQL.
  • Fare domande in linguaggio naturale. L'agente di analisi conversazionale elabora le tue richieste e trasmette la risposta a Gemini Enterprise come testo, Markdown, grafici o tabelle.
  • Visualizza la cronologia delle conversazioni nel riquadro della cronologia, dove le conversazioni vengono salvate automaticamente.

Località

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

Passaggi successivi