Architettura e concetti chiave dell'API Conversational Analytics

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:

Diagramma dell'architettura dell'API Analisi conversazionale, che mostra il flusso dall'input utente dell'utente attraverso un motore di ragionamento fino all'output finale.

Come mostrato nel diagramma, quando un utente pone una domanda, l'agente elabora la richiesta nelle seguenti fasi:

  1. Input: l'utente invia una domanda in linguaggio naturale, insieme a qualsiasi contesto aggiuntivo fornito in precedenza.
  2. 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).
  3. Motore di ragionamento: il nucleo dell'agente elabora la domanda dell'utente utilizzando gli strumenti disponibili per generare una risposta.
  4. 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:

Il workflow end-to-end per la progettazione e l'utilizzo degli agenti, dalle attività dei creator, come la creazione e la condivisione, alle attività degli utenti dei dati, come l'interazione con un agente.

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:

  1. 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.
  2. 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:

  1. Trova un agente: l'utente inizia trovando un agente che è stato condiviso con lui.
  2. 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.
  3. 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.
  4. 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.

Le diverse modalità di chat per un agente dell'API Analisi conversazionale.

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:

Un agente orchestratore principale delega una domanda sui dati a un agente di vendita specializzato, che poi restituisce una risposta all'utente.

Il workflow tipico di un sistema multi-agente prevede i seguenti passaggi:

  1. Un utente aziendale o un data analyst pone una domanda in linguaggio naturale, ad esempio "Mostrami i primi tre negozi per entrate".
  2. Un agente "orchestratore" principale delega la richiesta all'agente specializzato appropriato.
  3. 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.
  4. 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à: