Questo documento descrive i concetti chiave per l'utilizzo dell'API Analisi conversazionale (accessibile tramite geminidataanalytics.googleapis.com o endpoint regionali), che consente di creare e interagire con agenti per i dati che utilizzano il linguaggio naturale per rispondere alle domande sui dati strutturati. Questo documento descrive l'architettura degli agenti, i workflow tipici, le modalità conversazionali, i ruoli di Identity and Access Management (IAM) e la progettazione di sistemi multi-agente.
Per esaminare gli approcci architetturali disponibili per l'API Conversational Analytics e il modo in cui l'API gestisce il contesto della conversazione, consulta i pattern di integrazione e la gestione dello stato.
Come funzionano gli agenti per i dati
Gli agenti per i dati dell'API Analisi conversazionale utilizzano il contesto (informazioni e dati aziendali) che fornisci e strumenti (come SQL e Python) per interpretare le domande in linguaggio naturale e generare risposte dai tuoi dati strutturati.
Il seguente diagramma illustra le fasi del workflow di un agente quando un utente pone una domanda:

Come mostrato nel diagramma, quando un utente pone una domanda, l'agente elabora la richiesta nelle seguenti fasi:
- Input: l'utente invia una domanda in linguaggio naturale, insieme a qualsiasi contesto aggiuntivo fornito in precedenza.
- Origini dati: l'agente si connette ai tuoi dati in Looker, BigQuery (incluse tabelle o un grafico), Data Studio o origini dati di database (AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL in anteprima in
v1beta). - Motore di ragionamento: il nucleo dell'agente elabora la domanda dell'utente utilizzando gli strumenti disponibili per generare una risposta.
- Output: l'agente restituisce uno stream di messaggi, che possono contenere testo, dati o grafici. Questi messaggi potrebbero includere citazioni che collegano parti specifiche del testo della risposta alle fonti di contesto fornite, come termini del glossario o query di esempio. Per alcune origini dati, i messaggi forniscono informazioni dettagliate sul ragionamento dell'agente, segnalano l'avanzamento di un'azione o forniscono la risposta finale alla tua query.
Workflows per la progettazione e l'utilizzo degli agenti
L'API Analisi conversazionale supporta i workflow per i creator di agenti (che creano e configurano gli agenti) e per i consumer di agenti (che interagiscono con gli agenti esistenti).
Il seguente diagramma illustra il processo end-to-end, dalla configurazione iniziale da parte di un creator di agenti alle interazioni finali con un consumer di agenti:

Le sezioni seguenti descrivono in modo più dettagliato i workflow per i creator e i consumer di agenti.
Workflow di creazione degli agenti
Il creator dell'agente è responsabile della configurazione degli agenti. Questo workflow prevede i seguenti passaggi:
- Creazione dell'agente: il creator inizia creando un nuovo agente e fornendo il contesto necessario, incluse le istruzioni di sistema e le connessioni alle origini dati. Questo passaggio è fondamentale per consentire all'agente di comprendere e rispondere in modo efficace alle domande degli utenti.
- Condivisione dell'agente: una volta configurato l'agente, il creator lo condivide con altri utenti e imposta i controlli degli accessi basati sui ruoli appropriati per gestire le autorizzazioni.
Il workflow del consumer dell'agente
Il consumer dell'agente è in genere un utente aziendale che deve ottenere risposte da un agente configurato. Questo workflow prevede i seguenti passaggi:
- Trova un agente: l'utente inizia trovando un agente che è stato condiviso con lui.
- Fai una domanda: l'utente pone una domanda in linguaggio naturale. Questa domanda può essere una singola query o parte di una conversazione a più turni.
- L'agente "pensa": il motore di ragionamento dell'agente elabora la domanda. Il motore di ragionamento utilizza le conoscenze predefinite dell'agente e gli strumenti disponibili (come SQL, Python e grafici) in un "ciclo di ragionamento" per determinare il modo migliore per rispondere alla domanda.
- L'agente risponde: l'agente restituisce un flusso di messaggi, che possono contenere testo, dati o grafici. Per alcune origini dati, i messaggi forniscono informazioni dettagliate sul ragionamento dell'agente, segnalano l'avanzamento di un'azione o forniscono la risposta finale alla tua query.
Modalità conversazionale
Gli agenti dell'API Analisi conversazionale supportano diverse modalità conversazionali che determinano il modo in cui un agente gestisce la cronologia delle conversazioni e la persistenza del contesto nelle interazioni. Sono disponibili le seguenti modalità conversazionali:
- Modalità stateless: l'agente non memorizza la cronologia delle conversazioni. Ogni interazione viene trattata in modo indipendente. Questa modalità è utile per le applicazioni in cui non è necessario mantenere il contesto in più turni.
- Modalità stateful: l'agente conserva il contesto e la cronologia delle conversazioni, consentendo interazioni più contestualizzate. Questa modalità è utile per le applicazioni in cui è necessario mantenere il contesto in più turni. Per una maggiore precisione e risposte personalizzate, ti consigliamo di utilizzare la modalità stateful.
Scegli una modalità conversazionale in base ai requisiti della tua applicazione per la cronologia delle conversazioni e la persistenza del contesto.

Ruoli IAM
I ruoli IAM controllano chi può creare, gestire, condividere e interagire con gli agenti dell'API Analisi conversazionale. La tabella seguente descrive i ruoli IAM principali per l'API Analisi conversazionale:
| Ruolo | Ambito tipico | Cosa consente di fare il ruolo | Chi potrebbe utilizzare questo ruolo |
|---|---|---|---|
Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) |
Progetto | Creare agenti ed ereditare le autorizzazioni del proprietario sull'agente. | Qualsiasi analista di dati |
Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) |
Progetto, agente | Modificare, condividere o eliminare gli agenti con altri utenti. | Senior data analyst |
Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) |
Agente, progetto | Aggiornare la configurazione o il contesto di un agente. | Junior data analyst |
Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser) |
Agente, progetto | Chatta con un agente. | Professionista del marketing, proprietario di un negozio |
Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) |
Progetto, agente | Elencare gli agenti e ottenere i relativi dettagli. Non puoi modificare l'agente. | Qualsiasi utente |
Gemini Data Analytics Query Data User (roles/geminidataanalytics.queryDataUser) |
Progetto | Esegui query sui dati delle origini di database supportate utilizzando il metodo QueryData. |
Sviluppatore di applicazioni, analista di dati |
Gemini Data Analytics Stateless Chat User (roles/geminidataanalytics.dataAgentStatelessUser) |
Progetto | Chatta con un agente senza memorizzare il contesto o la cronologia delle conversazioni. | Qualsiasi utente |
Sistemi con più agenti
Puoi progettare sistemi complessi integrando più agenti dell'API Analisi conversazionale. Un pattern comune è l'utilizzo di un agente "orchestratore" principale che delega le attività a uno o più agenti specializzati che gestiscono domini specifici, come i dati di vendita o di marketing. Questo approccio ti consente di creare un sistema in grado di gestire un'ampia gamma di domande combinando i punti di forza di più agenti.
L'API Analisi conversazionale supporta il protocollo aperto Agent-to-Agent (A2A), che fornisce un'interfaccia standardizzata per scoprire funzionalità, delegare query e trasmettere in streaming artefatti SQL e grafici strutturati tra gli agenti. Per scoprire come implementare workflow multi-agente utilizzando il protocollo A2A, consulta Orchestra gli agenti per i dati con A2A.
Il seguente diagramma illustra questo pattern multi-agente e mostra come un agente principale può delegare una domanda sui dati a un agente Analisi conversazionale specializzato:

Il workflow tipico di un sistema multi-agente prevede i seguenti passaggi:
- Un utente aziendale o un data analyst pone una domanda in linguaggio naturale, ad esempio "Mostrami i primi tre negozi per entrate".
- Un agente "orchestratore" principale delega la richiesta all'agente specializzato appropriato.
- Un agente specializzato riceve la richiesta delegata, si connette alle origini dati pertinenti, utilizza i suoi strumenti per generare le query SQL e i grafici necessari e genera una risposta.
- La risposta dell'agente specializzato viene restituita all'utente, ad esempio "I negozi 4, 9 e 3 hanno le entrate più elevate. Ecco un grafico."
Passaggi successivi
Dopo aver compreso i concetti fondamentali dell'API Analisi conversazionale, scopri come implementare queste funzionalità:
- Scopri come orchestrare gli agenti per i dati con A2A.
- Confronta i pattern di integrazione dell'architettura per determinare l'approccio migliore per la tua applicazione.
- Comprendi la gestione dello stato per gli agenti per i dati e il modo in cui la gestione delle API gestisce il contesto della conversazione.
- Scopri come eseguire l'autenticazione e connetterti a un'origine dati.
- Scopri come creare e configurare un agente con HTTP.
- Scopri come creare e configurare un agente con Python.
- Scopri di più su come guidare il comportamento di un agente con il contesto creato.
- Comprendi il controllo degli accessi con IAM per l'API Analisi conversazionale.
- Scopri come proteggere gli agenti per i dati e le conversazioni utilizzando CMEK.
- Scopri come eseguire il rendering delle risposte dell'agente per le origini dati di Looker.