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 a domande sui dati strutturati. Questo documento descrive l'architettura degli agenti, i flussi di lavoro tipici, le modalità di conversazione, i ruoli Identity and Access Management (IAM) e la progettazione di sistemi multi-agente. Per esaminare gli approcci architetturali disponibili per l'API Analisi conversazionale e come l'API gestisce il contesto della conversazione, consulta pattern di integrazione e gestione dello stato.
Come funzionano gli agenti dei 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 tuoi dati strutturati.
Il seguente diagramma illustra le fasi del flusso di lavoro 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 che hai fornito in precedenza.
- Origini dati: l'agente si connette ai tuoi dati in Looker, BigQuery e Data Studio per le funzionalità di chat. Può anche eseguire query sui dati dei database AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL utilizzando il metodo
QueryData. - Motore di ragionamento: il cuore dell'agente elabora la domanda dell'utente utilizzando gli strumenti disponibili per generare una risposta.
- Output: l'agente restituisce un flusso di messaggi, che possono contenere testo, dati o grafici. Per alcune origini dati, i messaggi forniscono informazioni passo passo 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 flussi di lavoro per i creatori di agenti (che creano e configurano gli agenti) e per i consumatori di agenti (che interagiscono con gli agenti esistenti).
Il seguente diagramma illustra la procedura end-to-end, dalla configurazione iniziale da parte di un creatore di agenti alle interazioni finali con un consumatore di agenti:
Le sezioni seguenti descrivono in modo più dettagliato i flussi di lavoro per i creatori e i consumatori di agenti.
Il workflow di creazione dell'agente
Il creatore dell'agente è responsabile della configurazione degli agenti. Questo flusso di lavoro 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.
- Condividere 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 consumatore dell'agente
Il consumatore dell'agente è in genere un utente aziendale che deve ricevere risposte da un agente configurato. Questo flusso di lavoro 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 in 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.
- Risposta dell'agente: l'agente restituisce un flusso di messaggi, che possono contenere testo, dati o grafici. Per alcune origini dati, i messaggi forniscono informazioni passo passo sul ragionamento dell'agente, segnalano l'avanzamento di un'azione o forniscono la risposta finale alla tua 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à 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à con stato: l'agente conserva il contesto e la cronologia delle conversazioni, consentendo interazioni più contestualizzate. Questa modalità è utile per le applicazioni in cui devi mantenere il contesto in più turni. L'utilizzo della modalità con stato è consigliato per una maggiore precisione e risposte personalizzate.
Scegli una modalità di 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 API di 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) |
Project, Agent | Modificare, condividere o eliminare 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 operatore. | Professionista del marketing, proprietario del negozio |
Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) |
Project, Agent | 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 è 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 ti 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 il fatturato più alto. Ecco un grafico."
Passaggi successivi
Dopo aver compreso i concetti di base dell'API Analisi conversazionale, scopri come implementare queste funzionalità:
- Confronta i pattern di integrazione architetturali per determinare l'approccio migliore per la tua applicazione.
- Comprendere la gestione dello stato per gli agenti di dati e come l'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.
- Scopri il controllo dell'accesso con IAM per l'API Analisi conversazionale.
- Scopri come proteggere gli agenti e le conversazioni con CMEK.
- Scopri come visualizzare le risposte dell'agente per le origini dati di Looker.