Crea agenti dati

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

A livello generale, un agente per i dati è una combinazione di un'identità, un insieme di origini dati e l'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'alta 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 del database previste.
  • Complessità ridotta: gli agenti traducono il linguaggio naturale in query SQL, esecuzione e persino riepilogo o visualizzazione dei dati.
  • Flessibilità: puoi creare bozze di agenti per test personali o pubblicarli per renderli disponibili ad altri utenti nel tuo progetto o in modo programmatico utilizzando l'API.

Prima di iniziare

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

  2. Abilita le API Bigtable, Bigtable Admin, Data Analytics con Gemini e Gemini for Google Cloud , se non sono già abilitate.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

Ruoli obbligatori

Per lavorare con gli agenti per i dati, devi disporre di autorizzazioni IAM corrispondenti al tuo caso d'uso. La tabella seguente elenca i ruoli richiesti in base al fatto che tu stia creando e pubblicando agenti, eseguendo il provisioning degli agenti in Gemini Enterprise o scoprendo e utilizzando gli 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 agenti per i dati in un progetto: Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) sul progetto. Questo ruolo ti concede automaticamente il ruolo Data Agent Owner di Gemini Data Analytics sugli agenti per i dati che crei.
  • Per modificare, condividere o eliminare un agente per i dati: Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) sull'agente o sul progetto.
  • Per modificare un agente per i dati in un progetto: Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) nel progetto.
  • Per visualizzare gli agenti per i dati in un progetto: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) sul progetto.
  • Inoltre, per creare o modificare un agente per i dati, devi disporre dei seguenti ruoli:
    • Il ruolo roles/bigtable.reader o roles/bigtable.user concesso all'utente IAM a livello di progetto. Per saperne di più, consulta Aggiungi l'associazione della policy IAM per un progetto.
    • (Facoltativo) Se utilizzi i set di contesto (anteprima) con l'agente per i dati del database, per creare, caricare e gestire i set di contesto: il ruolo Dataplex Catalog Editor (roles/dataplex.catalogEditor) o Dataplex Catalog Admin (roles/dataplex.catalogAdmin) concesso all'utente IAM a livello di progetto. Per saperne di più, consulta Autorizzazioni per i set di contesti.
Esegui il provisioning degli agenti in Gemini Enterprise

Per rendere un agente pubblicato disponibile per gli utenti di Gemini Enterprise, devi disporre delle autorizzazioni per registrare e gestire gli agenti A2A nella console di amministrazione di Gemini Enterprise.
Scopri e utilizza gli agenti
  • Per chattare con gli agenti per i dati: Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser).
  • Per visualizzare tutti gli agenti per i dati nel progetto: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer).
  • Per eseguire query sulle tabelle Bigtable: il ruolo roles/bigtable.reader o roles/bigtable.user concesso all'utente IAM a livello di progetto. Per saperne di più, consulta Aggiungi l'associazione della policy IAM per un progetto.

Per lavorare con le risorse Bigtable, consulta Ruoli e autorizzazioni di Bigtable.

Crea un agente 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 console Google Cloud , vai alla pagina Bigtable.

    Vai a Bigtable

  2. Seleziona un'istanza dall'elenco.

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

  4. Fai clic sulla scheda Catalogo agenti.

  5. Fai clic su Crea agente. Viene visualizzata la pagina Editor.

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

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

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

  9. Seleziona le tabelle su cui l'agente si concentrerà quando risponde alle domande.

  10. Fai clic su Aggiungi dati. Viene visualizzata nuovamente la pagina del nuovo agente.

  11. Fai clic su Salva bozza per salvare i progressi.

Crea query verificate

Puoi selezionare le query verificate da un elenco generato dal sistema o crearne di tue.

Per creare una query verificata per l'agente per i dati, segui questi passaggi:

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

    Vai a Bigtable

  2. Seleziona un'istanza dall'elenco.

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

  4. Fai clic sulla scheda Catalogo agenti.

  5. Individua la scheda dell'agente di dati che vuoi modificare. Se l'agente per i dati è una bozza non pubblicata, fai clic su Bozze degli agenti.

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

  7. In Query verificate, fai clic su Aggiungi query.

    1. In Domanda, inserisci la domanda a cui è possibile rispondere con la query verificata.
    2. Fai clic su Genera SQL per consentire a Gemini di generare una query verificata corrispondente alla domanda che hai aggiunto.
    3. Fai clic su Esegui e verifica che la query restituisca i risultati previsti.
    4. Esamina la risposta e, se necessario, modifica la query verificata.
    5. Fai clic su Aggiungi.
    6. Fai clic su Salva bozza per salvare i progressi.

  8. Ripeti questi passaggi per creare altre query verificate.

Aggiungi etichette agli agenti per i 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 console Google Cloud , vai alla pagina Bigtable.

    Vai a Bigtable

  2. Seleziona un'istanza dall'elenco.

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

  4. Fai clic sulla scheda Catalogo agenti.

  5. Individua la scheda dell'agente di dati che vuoi modificare. Se l'agente per i dati è una bozza non pubblicata, fai clic su Bozze degli agenti.

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

  7. Nella sezione Impostazioni agente, fai clic su Aggiungi etichetta. Viene visualizzato il riquadro Gestisci etichette.

  8. Fai clic su Aggiungi etichetta.

  9. Nei campi chiave e valore, inserisci la coppia chiave-valore per l'etichetta.

  10. Se vuoi aggiungere altre etichette, fai di nuovo clic su Aggiungi etichetta.

  11. Per eliminare un'etichetta, fai clic su Elimina.

  12. Al termine, fai clic su Aggiungi. Viene visualizzata nuovamente la pagina del nuovo agente.

Vai alla sezione successiva per impostare l'agente in modalità bozza o per pubblicarlo.

Visualizza l'anteprima e pubblica l'agente

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

    Per verificare che l'agente per i 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 per i dati fino a ottenere risposte soddisfacenti. Puoi continuare a testare e modificare l'agente per perfezionare i suoi risultati.

  2. Fai clic su Salva bozza.

  3. Per impostare l'agente per i dati in modalità bozza, che puoi modificare in un secondo momento, fai clic su Torna indietro per tornare alla pagina Catalogo degli agenti. Poiché l'agente è ora in modalità bozza, viene visualizzato nella sezione Bozze di agenti 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 per i dati e renderlo disponibile per l'utilizzo nel progetto, fai clic su Pubblica. Nella finestra di dialogo Canali di pubblicazione, seleziona i canali di pubblicazione da utilizzare. Fai clic su Pubblica agente (o Pubblica aggiornamenti).

    La pubblicazione dell'agente consente ad altri utenti che hanno accesso alle stesse tabelle del database di visualizzare e conversare con il tuo agente, sfruttando le istruzioni e il contesto che hai creato.

    Puoi creare conversazioni con l'agente per i dati utilizzando la pagina Agenti nella console Google Cloud . Puoi anche creare la tua interfaccia per chattare con l'agente per i dati utilizzando l'API Conversational Analytics.

  5. (Facoltativo) Nella finestra di dialogo L'agente è stato pubblicato ed è pronto per essere condiviso, fai clic su Condividi per condividere l'agente per i 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:
      • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser): concede l'autorizzazione per interagire con l'agente per i dati.
      • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor): concede l'autorizzazione per modificare l'agente per i dati.
      • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer): concede l'autorizzazione per visualizzare l'agente per i dati.
    5. Fai clic su Salva.

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

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

Gestisci gli agenti per i dati

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

  • Tutti gli agenti: un elenco di tutti gli agenti che crei e pubblichi e di quelli che altri creano e condividono con te.
  • I miei agenti: un elenco di tutti gli agenti che crei e pubblichi. Puoi modificare e condividere gli agenti pubblicati con altri utenti.

  • Bozze di agenti: agenti che non hai ancora pubblicato. Non puoi condividere le bozze degli agenti.

Modifica un agente di dati

Per modificare un agente per i dati, segui questi passaggi:

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

    Vai a Bigtable

  2. Seleziona un'istanza dall'elenco.

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

  4. Fai clic sulla scheda Catalogo agenti.

  5. Individua la scheda dell'agente di dati che vuoi modificare. Se l'agente per i dati è una bozza non pubblicata, fai clic su Bozze degli agenti.

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

  7. Modifica la configurazione dell'agente per i dati in base alle esigenze.

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

  9. Per pubblicare l'agente per i dati e renderlo disponibile per l'utilizzo nel progetto, fai clic su Pubblica. Nella finestra di dialogo Canali di pubblicazione, seleziona i canali di pubblicazione da utilizzare. Fai clic su Pubblica agente (o Pubblica aggiornamenti). Nella finestra di dialogo Condividi, puoi condividere l'agente con altri utenti o fare clic su Chiudi.

  10. Per tornare al riquadro Catalogo agenti, fai clic su Indietro.

Condividi un agente per i dati

Segui questi passaggi per condividere un agente per i dati pubblicato. Non puoi condividere agenti in bozza.

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

    Vai a Bigtable

  2. Seleziona un'istanza dall'elenco.

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

  4. Fai clic sulla scheda Catalogo agenti.

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

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

  7. Per condividere l'agente per i dati con altri utenti, fai clic su Condividi.

  8. Nel riquadro Condividi autorizzazioni, fai clic su Aggiungi entità.

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

  10. Fai clic su Seleziona un ruolo.

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

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

  12. Fai clic su Salva.

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

  14. Per tornare al riquadro Catalogo agenti, fai clic su Indietro.

Elimina un agente di dati

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

    Vai a Bigtable

  2. Seleziona un'istanza dall'elenco.

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

  4. Seleziona la scheda Catalogo degli agenti.

  5. Individua la scheda dell'agente per i dati che vuoi eliminare. Se l'agente per i dati è una bozza non pubblicata, fai clic su Bozze degli agenti.

  6. Fai clic su Apri azioni > Elimina.

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

Pubblica un agente di dati in Gemini Enterprise

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

Crea e pubblica un agente

Per creare, modificare e pubblicare un agente, segui questi passaggi:

  1. Crea o modifica l'agente per i dati in Bigtable.
  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 saperne di più, consulta Esegui il provisioning di un agente.
  5. Condividi l'agente con gli utenti e i gruppi che necessitano di accesso.

Esegui il provisioning di un agente

Per rendere un agente pubblicato disponibile 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 di dati in formato JSON.

  6. Fai clic su Visualizza l'anteprima dei dettagli dell'agente > Avanti.

  7. Per consentire all'agente di accedere alle risorse Google Cloud 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 Registra e gestisci gli agenti A2A.

Trova e utilizza un agente

Puoi trovare e utilizzare un agente per i 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 quell'agente per i dati Bigtable 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 è la tendenza della nostra pipeline di vendita negli ultimi 3 mesi?", per consentire a Gemini Enterprise di indirizzare automaticamente la query all'agente per i dati pertinente.

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

  • Completa l'accesso OAuth una tantum per autenticarti in modo sicuro su Bigtable.
  • Fai domande in linguaggio naturale. L'agente di analisi conversazionale elabora le tue richieste e trasmette la risposta a Gemini Enterprise sotto forma di 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; non puoi scegliere quale regione utilizzare.

Passaggi successivi