Questo documento descrive i concetti chiave per l'utilizzo dell'API Analisi conversazionale (geminidataanalytics.googleapis.com), che consente di creare e interagire con agenti di 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à di conversazione, i ruoli Identity and Access Management (IAM) e la progettazione di sistemi multi-agente.
Come funzionano gli agenti di dati
Gli agenti di dati dell'API Analisi conversazionale utilizzano il contesto (informazioni sull'attività e dati) che fornisci e strumenti (come SQL e Python) per interpretare le domande in linguaggio naturale e generare risposte dai 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 e Looker Studio per le funzionalità di chat. Può anche eseguire query sui dati dai database AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL utilizzando il metodo
QueryData. - 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. Per alcune origini dati, i messaggi di testo forniscono informazioni dettagliate passo passo sul ragionamento dell'agente, segnalano l'avanzamento di un'azione o forniscono la risposta finale alla query.
Workflows per la progettazione e l'utilizzo degli agenti
L'API Analisi conversazionale supporta i workflow per i creatori 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 creatore di agenti alle interazioni finali con un consumer di agenti:
Le sezioni seguenti descrivono in modo più dettagliato i workflow per i creatori di agenti e i consumer di agenti.
Il workflow del creatore di agenti
Il creatore di agenti è responsabile della configurazione degli agenti. Questo workflow prevede i seguenti passaggi:
- Crea agente: il creatore 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.
- Condividi l'agente: una volta configurato l'agente, il creatore lo condivide con altri utenti e imposta i controlli di accesso basati sui ruoli appropriati per gestire le autorizzazioni.
Il workflow del consumer di agenti
Il consumer di agenti è 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 cercando un agente che è stato condiviso con lui.
- Poni 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 dell'agente 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 uno stream di messaggi che possono contenere testo, dati o grafici. Per alcune origini dati, i messaggi di testo forniscono informazioni dettagliate passo passo sul ragionamento dell'agente, segnalano l'avanzamento di un'azione o forniscono la risposta finale alla query.
Modalità di conversazione
Gli agenti dell'API Analisi conversazionale supportano diverse modalità di conversazione 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à di conversazione:
- Modalità senza stato: 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à con stato: 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à con stato.
Scegli una modalità conversazione 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 seguente tabella descrive i ruoli IAM chiave per l'API Analisi conversazionale:
| Ruolo | Ambito tipico | Cosa consente il ruolo | Chi potrebbe utilizzare questo ruolo |
|---|---|---|---|
Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) |
Progetto | Crea agenti ed eredita le autorizzazioni del proprietario sull'agente. | Qualsiasi analista di dati |
Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) |
Progetto, agente | Modifica, condividi o elimina gli agenti con altri utenti. | Senior data analyst |
Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) |
Agente, progetto | Aggiorna 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 del negozio |
Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) |
Progetto, agente | Elenca gli agenti e ottieni i relativi dettagli. Non puoi modificare l'agente. | Qualsiasi utente |
Gemini Data Analytics Data Query User (roles/geminidataanalytics.queryDataUser) |
Progetto | Esegui query sui dati dalle origini 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 consiste nell'utilizzare 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 consente di creare un sistema in grado di gestire un'ampia gamma di domande combinando i punti di forza di più agenti.
Il seguente diagramma illustra questo pattern multi-agente e mostra come un agente principale può delegare una domanda sui dati a un agente di analisi conversazionale specializzato:
Il workflow tipico per un sistema multi-agente prevede i seguenti passaggi:
- Un utente aziendale o un analista di dati 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ù alte. Ecco un grafico".
Passaggi successivi
Dopo aver compreso i concetti di base dell'API Analisi conversazionale, scopri come implementare queste funzionalità:
- Scopri come autenticare 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.
- Scopri il controllo dell'accesso con IAM per l'API Analisi conversazionale.
- Scopri come proteggere gli agenti di dati e le conversazioni utilizzando CMEK.
- Scopri come eseguire il rendering delle risposte degli agenti per le origini dati di Looker.