Questa pagina descrive i pattern di integrazione per incorporare le esperienze degli agenti per i dati nelle tue applicazioni. La complessità di questi pattern varia da un componente di chat incorporato a un sistema multi-agente orchestrato.
Questa guida è rivolta ad architetti cloud e data engineer che progettano applicazioni di AI generativa. Dovresti avere una conoscenza di base dei concetti di Google Cloud , di Identity and Access Management (IAM) e delle API REST. Dovresti anche avere familiarità con l'architettura dell'origine dati utilizzata dalla tua applicazione.
Panoramica dei pattern di integrazione
Questa guida è organizzata nei seguenti percorsi principali, ognuno dei quali si basa sul tuo punto di partenza:
- Percorso Looker: seleziona questo percorso se vuoi fornire funzionalità di chat tramite l'incorporamento di Looker, l'API Looker o l'API Analisi conversazionale.
- Percorso BigQuery e database: seleziona questo percorso se stai creando un'applicazione personalizzata che utilizza BigQuery, Data Studio o un database operativo supportato.
La tabella seguente riassume i pattern di integrazione disponibili:
| Pattern di integrazione | Descrizione | Origine dati |
|---|---|---|
| Incorporamento di iframe di Looker | Aggiunge l'interfaccia di chat standard a un'applicazione che richiede un codice minimo. | Looker |
| API Looker e SDK | Crea un'interfaccia di chat personalizzata che utilizza l'API Looker per l'autenticazione. | Looker |
| API Analisi conversazionale (origine Looker) | Gestisce gli agenti per i dati di Looker come risorse Google Cloud che funzionano su più piattaforme e sistemi multi-agente. | Looker |
| API diretta (agente singolo) | Utilizza un'integrazione API diretta per i flussi di testo-risposta. | BigQuery, database, Looker |
| API diretta (orchestratore) | Instrada le query tra l'API e altri strumenti utilizzando la chiamata di funzione. | BigQuery, database, Looker |
ADK (basato su schema) con BigQueryToolset |
Genera rapidamente insight dai riferimenti tabella utilizzando lo strumento ask_data_insights. |
BigQuery |
ADK (governato) con DataAgentToolset |
Esegue query su agenti per i dati preconfigurati che utilizzano lo strumento ask_data_agent per garantire un comportamento coerente. |
BigQuery, database, Looker |
| ADK (streaming personalizzato) | Supporta lo streaming in tempo reale di grafici e SQL utilizzando una classe di agenti personalizzata. | BigQuery, database, Looker |
MCP con McpToolset o ToolboxToolset |
Connette le applicazioni agli strumenti di dati che utilizzano il Model Context Protocol (MCP). | BigQuery, Looker |
| Server MCP remoto dell'API Analisi conversazionale | Fornisce un gateway sicuro e unificato che consente agli agenti principali nelle piattaforme AI di terze parti e nelle piattaforme gestite da Google (come Gemini Enterprise) di scoprire e comunicare con agenti per i dati specializzati in Google Cloud. | BigQuery, database, Looker |
| Protocollo A2A | Consente la collaborazione sicura tra agenti specializzati che operano su sistemi diversi. | Dipendente dal framework |
Opzioni di integrazione per Looker
Se utilizzi Looker, puoi fornire Analisi conversazionale di Looker ai tuoi utenti tramite i seguenti pattern:
- Incorporamento con iframe: un pattern low-code che aggiunge l'interfaccia di chat standard a un'applicazione esistente.
- Crea con l'API Looker e gli SDK: un approccio flessibile che ti consente di creare un frontend personalizzato tramite l'autenticazione di Looker e la gestione degli agenti.
- Utilizza l'API Analisi conversazionale: un'integrazione diretta con l'API che consente di utilizzare gli agenti per i dati su più Google Cloud piattaforme.
Riepilogo dei pattern di integrazione di Looker
La tabella seguente riassume i principali pattern di integrazione per Looker:
| Pattern | Ideale per | Vantaggi | Considerazioni |
|---|---|---|---|
| Incorporamento con iframe: un metodo low-code per aggiungere rapidamente l'esperienza di chat standard di Looker a un'applicazione. | Team che richiedono un'esperienza di Analisi conversazionale pronta per la produzione con uno sviluppo personalizzato minimo. |
|
|
| Crea con l'API e gli SDK di Looker: un approccio flessibile per creare un'interfaccia di chat personalizzata, mantenendo l'autenticazione e la gestione degli agenti all'interno di Looker. | Team che richiedono un'esperienza utente di chat personalizzata, ma vogliono mantenere l'autenticazione degli utenti e la gestione degli agenti all'interno dell'ecosistema Looker. Questo pattern è ideale per le applicazioni che utilizzano già l'incorporamento di Looker o l'API. |
|
|
| Utilizza l'API Analisi conversazionale: integrazione diretta con l'API per gestire gli agenti come risorse a livello di cloud. | Clienti di Looker che richiedono la portabilità multipiattaforma per i loro agenti per i dati. |
|
|
Incorporamento con iframe
Puoi incorporare Analisi conversazionale come iframe per offrire l'esperienza di chat al di fuori della UI di Looker. Questo pattern è un modo diretto per fornire Analisi conversazionale che non richiede lo sviluppo di UI personalizzate, l'orchestrazione del backend o la gestione dello stato delle API. Per utilizzare questo pattern, aggiungi un URL preformattato alla tua applicazione.
L'SDK Embed di Looker fornisce strumenti che gestiscono attività come la generazione di URL sicuri, la gestione del ciclo di vita degli iframe e il passaggio di eventi JavaScript tra l'applicazione in hosting e l'iframe. Puoi incorporare la pagina Agenti, la pagina Conversazioni o una conversazione specifica aggiungendo un URL preformattato alla tua applicazione.
Per i contenuti incorporati puoi utilizzare i seguenti metodi di autenticazione:
- Incorporamento privato: autentica gli utenti con le loro credenziali Looker esistenti. Quando imposti l'URL di incorporamento come origine dell'iframe, gli utenti accedono con i propri account Looker. Questo metodo applica automaticamente i ruoli, l'accesso ai contenuti e le autorizzazioni a livello di dati esistenti, come i filtri di accesso o le concessioni di accesso, senza richiedere ulteriori configurazioni IAM o mappature dei token.
- Incorporamento firmato: autentica gli utenti tramite la tua applicazione utilizzando il Single Sign-On (SSO). Puoi creare un URL firmato che includa il percorso dei contenuti di Analisi conversazionale, che ti consente di specificare dinamicamente le autorizzazioni esatte da concedere.
Crea con l'API Looker e gli SDK
Per una maggiore flessibilità nell'esperienza di chat, puoi utilizzare i metodi ConversationalAnalytics nell'API Looker o utilizzare un SDK Looker per creare un'applicazione personalizzata. Questo approccio ti consente di creare un frontend personalizzato che comunica direttamente con gli endpoint di Looker.
L'integrazione con l'API Looker offre i seguenti vantaggi:
- Gestisci solo l'autenticazione con Looker. Non è necessario eseguire l'autenticazione separatamente con l'API Analisi conversazionale.
- Per le applicazioni che utilizzano già l'incorporamento di Looker o l'API, questo pattern semplifica l'architettura del progetto evitando meccanismi di autenticazione secondari ed eliminando la necessità di gestire agenti per i dati esterni.
- Hai il pieno controllo sull'interfaccia di chat, sul flusso della conversazione e sul modo in cui l'applicazione visualizza i risultati (ad esempio grafici e tabelle).
Per un'implementazione di riferimento, consulta la guida all'API Looker che utilizza i metodi ConversationalAnalytics su GitHub.
Utilizza l'API Analisi conversazionale con i dati di Looker
Puoi eseguire l'integrazione direttamente con l'API Analisi conversazionale all'indirizzo geminidataanalytics.googleapis.com se devi eseguire una delle seguenti attività:
- Condividi lo stesso agente per i dati su più Google Cloud piattaforme, come applicazioni web personalizzate, Google Chat e Gemini Enterprise.
- Combina le origini dati di Looker con BigQuery o con le origini di database operativi in un unico sistema multi-agente.
- Gestisci l'agente per i dati come risorsa a livello di cloud regolata da IAM anziché dal modello di autorizzazioni di Looker.
Per ulteriori informazioni sui pattern di architettura comuni per l'API Analisi conversazionale, consulta Opzioni di integrazione per BigQuery e i database.
Opzioni di integrazione per BigQuery, Data Studio e i database
Questa sezione descrive i pattern architetturali per le applicazioni che utilizzano BigQuery, Data Studio o i database operativi Google Cloud supportati per creare esperienze personalizzate con l'API Analisi conversazionale.
Se utilizzi l'API Analisi conversazionale con un'origine dati di Looker, i pattern descritti in questa sezione si applicano anche alla tua integrazione.
L'API Analisi conversazionale fornisce i seguenti metodi principali per interagire con i dati:
- Metodo
chat: supporta BigQuery, Looker, Data Studio e i database operativi. - Metodo
queryData: supporta database operativi come AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL.
Quando crei un'applicazione personalizzata, puoi utilizzare uno o più dei seguenti pattern di integrazione:
- Integrazione diretta dell'API: un approccio personalizzato che offre la massima flessibilità, ma richiede la creazione dell'infrastruttura per l'autenticazione, la gestione delle conversazioni e l'analisi delle risposte.
- Orchestrazione basata su framework (ADK): un approccio che utilizza l'Agent Development Kit (ADK) per il routing multi-agente, l'esecuzione degli strumenti e la gestione dello stato.
- Integrazione verticale (MCP): un approccio che utilizza il Model Context Protocol (MCP) per fornire un modo uniforme di connettere le applicazioni AI a strumenti e origini dati in ambienti diversi.
- Orchestration orizzontale (A2A): un approccio che utilizza il protocollo Agent2Agent (A2A) per consentire ad agenti specializzati su sistemi diversi di collaborare in sicurezza senza richiedere codice di integrazione personalizzato.
Riepilogo dei pattern di integrazione di BigQuery e dei database
La tabella seguente riassume i pattern di implementazione specifici per BigQuery e i database operativi:
| Pattern | Ideale per | Vantaggi | Considerazioni |
|---|---|---|---|
| Integrazione con un singolo agente (API diretta): un pattern in cui l'applicazione chiama direttamente l'API per restituire insight dalle origini dati. | Applicazioni, prototipi o microservizi con un singolo agente che richiedono il controllo diretto su ogni chiamata API. |
|
|
| Orchestratore personalizzato (API diretta): un pattern che utilizza un agente root e la chiamata di funzione per instradare le query tra l'API Analisi conversazionale e altri strumenti o servizi. | Applicazioni che combinano query sui dati con altre attività, come email o documenti, in un unico flusso di conversazione. |
|
|
Integrazione basata su schema con BigQueryToolset (ADK): un pattern che utilizza i riferimenti alle tabelle per restituire rapidamente insight sui dati. |
Prototipazione rapida, strumenti interni in cui la governance dei dati è meno critica o scenari in cui gli insight sui dati sono una delle diverse funzionalità di un agente ADK. |
|
|
Integrazione controllata con DataAgentToolset (ADK): un pattern che esegue query su un agente per i dati preconfigurato facendo riferimento all'ID dell'agente. |
Applicazioni di produzione che richiedono un accesso ai dati coerente o sistemi multi-agente in cui l'agente per i dati è un componente affidabile e riutilizzabile. |
|
|
| Sub-agenti personalizzati (ADK): un pattern che utilizza una classe di agenti personalizzati per connettersi direttamente all'API e trasmettere blocchi di dati all'utente. | Applicazioni rivolte agli utenti in cui la bassa latenza di risposta è una priorità o pipeline multi-agente in cui il recupero dei dati alimenta gli agenti downstream. |
|
|
| Model Context Protocol (MCP): un pattern che utilizza uno standard aperto per connettere le applicazioni AI a origini dati e strumenti in ambienti diversi. | Organizzazioni che richiedono l'interoperabilità degli strumenti tra più client AI e IDE o team che hanno bisogno che gli stessi strumenti di dati siano accessibili dal framework ADK, dagli IDE e dalle applicazioni personalizzate. |
|
|
| Agent-to-Agent (A2A): un pattern che utilizza il protocollo A2A, uno standard aperto che consente ad agenti specializzati su sistemi diversi di collaborare in modo sicuro senza richiedere codice di integrazione personalizzato. | Ambienti aziendali altamente distribuiti in cui un agente di routing centrale deve delegare le attività ad agenti per i dati che operano su sistemi o reti diversi. |
|
|
Integrazione diretta dell'API
L'integrazione diretta dell'API offre un controllo granulare sulla logica e sull'architettura dell'applicazione, ma richiede la creazione dell'infrastruttura di supporto. Con questo approccio, sei responsabile di attività come l'autenticazione, la gestione delle conversazioni, l'analisi delle risposte e il deployment.
In questa sezione sono trattati i seguenti argomenti:
- Integrazione con un singolo agente: un pattern in cui la tua applicazione chiama direttamente l'API Analisi conversazionale per restituire insight dalle tue origini dati.
- Integrazione dell'orchestratore personalizzato: un pattern avanzato che utilizza un agente root e la chiamata di funzione per instradare le query tra l'API Analisi conversazionale e altri strumenti o servizi.
Integrazione con un singolo agente
Con un'integrazione con un singolo agente, il tuo backend chiama direttamente l'API Analisi conversazionale utilizzando REST o una libreria client e passa la query e il contesto dell'utente. Questo pattern è adatto per applicazioni a bassa complessità, come app web, strumenti di chat interni o microservizi, che utilizzano un flusso di testo-risposta semplice. Puoi utilizzare questo approccio anche per la prototipazione e il lavoro di proof of concept.
Questo pattern supporta sia la chat stateful, in cui Google gestisce la cronologia delle conversazioni, sia la chat stateless, in cui la cronologia è gestita dalla tua applicazione.
Per le implementazioni di riferimento, consulta la guida rapida all'API Analisi conversazionale o la demo d'oro dell'API Analisi conversazionale su GitHub.
Integrazione dell'orchestratore personalizzato
Con questo approccio, crei un agente root che funge da punto di contatto principale e coordinatore per la tua applicazione. L'agente principale utilizza un modello Gemini standard dotato di strumenti tramite la chiamata di funzione. Quando un utente pone una domanda relativa ai dati, l'agente principale emette una chiamata allo strumento all'API Analisi conversazionale, riceve il risultato e può quindi continuare il ragionamento o chiamare altri strumenti a valle.
La chiamata di funzione prevede le seguenti fasi:
- Dichiarazione: definisci gli schemi degli strumenti come oggetti
FunctionDeclarationche includono le definizioni dei parametri. - Richiamo: il modello restituisce un messaggio
functionCallstrutturato che contiene il nome e gli argomenti della funzione. - Esecuzione: l'applicazione esegue la chiamata API e restituisce il risultato in un messaggio
FunctionResponse. - Sintesi: il modello Gemini utilizza il risultato per generare una risposta finale o per determinare l'azione successiva.
Questo approccio è adatto per le applicazioni in cui gli utenti potrebbero richiedere insight sui dati insieme ad altre attività. Ad esempio, un utente potrebbe chiedere all'agente di "Mostrami le vendite e poi scrivi una bozza di email per il team di vendita". L'agente principale può indirizzare la domanda sui dati all'API Analisi conversazionale e utilizzare altri strumenti per le attività non relative ai dati.
Per un'implementazione di riferimento, consulta le pagine orchestrate o multimodal nella demo d'oro dell'API Analisi conversazionale su GitHub.
Orchestrazione basata su framework (ADK)
Agent Development Kit (ADK) è un framework code-first per la creazione di agenti AI che gestisce la complessità del routing multi-agente, dell'esecuzione degli strumenti e della gestione dello stato. Il framework ADK è lo stesso framework su cui si basa Gemini Enterprise.
Utilizzando l'ADK, puoi concatenare l'API Analisi conversazionale con altri strumenti e agenti per eseguire azioni complesse.
In questa sezione sono trattati i seguenti argomenti:
- Integrazione basata su schema: un pattern che utilizza lo strumento
ask_data_insightsdel set di strumentiBigQueryToolsetper restituire insight sui dati dai riferimenti alle tabelle BigQuery. - Integrazione regolamentata: un pattern che utilizza lo strumento
ask_data_agentdel set di strumentiDataAgentToolsetper eseguire query su un agente per i dati preconfigurato facendo riferimento all'ID dell'agente. - Integrazione UX avanzata con sub-agenti personalizzati: un pattern che utilizza un componente sub-agente personalizzato per connettersi direttamente all'API Analisi conversazionale e trasmettere i blocchi di dati all'utente in modo asincrono.
Integrazione basata su schema con BigQueryToolset
Il set di strumenti BigQueryToolset nel framework ADK include uno strumento ask_data_insights predefinito. Per utilizzare questo strumento, devi passare i nomi delle tabelle e la domanda dell'utente allo strumento, che poi chiama l'API Analisi conversazionale utilizzando il contesto incorporato.
Quando chiami lo strumento, questo invia all'API Analisi conversazionale una richiesta stateless che include i riferimenti alla tabella BigQuery specificati. L'API deduce lo schema del database, genera ed esegue la query SQL e restituisce una risposta di testo. Il risultato viene quindi restituito all'agente ADK come risposta dello strumento.
Questo pattern è un modo efficace per aggiungere rapidamente l'analisi conversazionale a un agente. Tuttavia, poiché la chiamata all'API è stateless e priva di governance, l'API genera un SQL basato interamente sullo schema della tabella senza guardrail semantici. Questo pattern è più veloce da implementare, ma più rischioso per la logica di business di produzione in cui si applicano convenzioni di denominazione, logica di business o controlli degli accessi.
Integrazione controllata con DataAgentToolset
Il set di strumenti DataAgentToolset nel framework ADK fornisce un'integrazione predefinita che fa riferimento a un agente per i dati preconfigurato tramite il suo ID. L'agente ADK passa la domanda dell'utente allo strumento ask_data_agent, che chiama l'API Analisi conversazionale con il contesto dell'agente per i dati specificato.
Puoi creare un agente per i dati in modo programmatico utilizzando l'API Analisi conversazionale o tramite il Catalogo degli agenti nella console Google Cloud . Un agente per i dati è dotato dei seguenti componenti:
- Fonti di conoscenza: tabelle, viste o funzioni definite dall'utente (UDF) su cui l'agente può eseguire query
- Contesto strutturato: descrizioni di tabelle e colonne che aiutano l'agente a comprendere i dati sottostanti
- Istruzioni: indicazioni aggiuntive per l'agente per interpretare ed eseguire query sulle origini dati
- Query verificate: query SQL pre-convalidate che fungono da esempi per domande comuni
- Glossario: definizioni di termini aziendali che aiutano l'agente a comprendere il linguaggio specifico del dominio
Per una guida approfondita sulla creazione di agenti tramite il catalogo degli agenti, consulta il codelab sull'analisi conversazionale in BigQuery.
Poiché l'agente è definito come un'unità governata, utilizza la stessa logica, lo stesso contesto e le stesse misure di protezione affidabili, indipendentemente dall'applicazione o dal sub-agente che lo chiama.
Integrazione UX avanzata con sub-agenti personalizzati
I set di strumenti BigQueryToolset e DataAgentToolset non restituiscono risultati all'utente finché l'elaborazione della richiesta API non è terminata. Poiché il framework ADK tratta l'API come uno strumento che blocca le risposte fino al completamento, le query con tempi di esecuzione più lunghi potrebbero lasciare gli utenti senza feedback.
In alternativa, per le applicazioni in cui la bassa latenza di risposta è una priorità o in cui il recupero dei dati alimenta gli agenti downstream, puoi creare una classe di agenti ADK personalizzata che si connette direttamente all'API Analisi conversazionale e trasmette i dati in modo asincrono all'utente in blocchi. Questo pattern supporta i seguenti tipi di risposta man mano che vengono prodotti:
- Messaggi di pensiero: il processo di ragionamento dell'agente per i dati durante l'interpretazione della domanda.
- Messaggi di avanzamento: aggiornamenti di stato durante il recupero dei dati per le origini dati.
- Generazione di query: la query SQL o Looker generata, che viene trasmessa in streaming man mano che viene prodotta.
- Dati: i risultati dei dati in formato JSON.
- Visualizzazione: specifiche del grafico Vega-Lite.
- Riepilogo: la risposta finale basata su testo.
Per un elenco completo dei tipi di dati restituiti, consulta il tipo SystemMessage nella documentazione di riferimento dell'API.
Questo approccio asincrono garantisce che gli utenti non debbano attendere il completamento di un processo di recupero dei dati complesso. Mentre l'agente per i dati esegue il processo di query, condivide continuamente aggiornamenti incrementali, come riepiloghi di testo, dati non elaborati o configurazioni di grafici, in un'area di lavoro condivisa temporanea. Questi dati possono poi essere visualizzati dall'utente in tempo reale e condivisi con sub-agenti specializzati per eseguire attività aggiuntive.
Per un'implementazione di riferimento che include un agente root, un sub-agente di dati e un agente di visualizzazione, consulta la demo di streaming ADK su GitHub.
Integrazione verticale (MCP)
Il Model Context Protocol (MCP) è uno standard aperto che fornisce un modo uniforme per le applicazioni AI di connettersi a strumenti esterni e origini dati. L'MCP standardizza l'interfaccia tra i modelli di AI e gli strumenti che utilizzano.
In questa sezione sono trattati i seguenti argomenti:
- Server MCP remoto dell'API Analisi conversazionale: descrive come gli agenti root di terze parti e gestiti da Google comunicano con l'API Analisi conversazionale tramite il gateway del server MCP remoto, inclusa la propagazione dell'identità e l'accesso ai metodi API.
- MCP Toolbox for Databases: descrive gli strumenti predefiniti per la connessione a BigQuery e Looker.
- Modelli di implementazione MCP per architetture autonome e ADK: descrive i modelli per l'utilizzo di MCP come server autonomo o all'interno di un workflow dell'Agent Development Kit (ADK).
Server MCP remoto dell'API Analisi conversazionale
L'API Analisi conversazionale fornisce un server MCP remoto all'indirizzo https://geminidataanalytics.googleapis.com/mcp, basato sul server MCP gestito di Google. Questo gateway fornisce un'interfaccia HTTP e Server-Sent Events (SSE) unificata e sicura che consente agli agenti root nelle piattaforme AI di terze parti e nelle piattaforme gestite da Google (come Gemini Enterprise) di scoprire e comunicare con agenti per i dati specializzati in Google Cloud.
Panoramica della comunicazione dell'agente principale
La comunicazione tra un agente root esterno o gestito da Google e l'API Analisi conversazionale prevede tre ruoli distinti:
- Gli operatori dei dati creano e configurano agenti per i dati con ambito definito su tutte le piattaforme di analisi conversazionale, scrivono descrizioni chiare delle origini dati a cui ogni agente può accedere e delle domande a cui può rispondere e condividono questi agenti con gli utenti aziendali.
- Gli amministratori della piattaforma registrano una connessione MCP personalizzata nella loro piattaforma agentica che punta all'endpoint
https://geminidataanalytics.googleapis.com/mcp. Gli amministratori configurano le credenziali client OAuth 2.0 (ID client e client secret) utilizzando l'endpoint di autorizzazione di Google (https://accounts.google.com/o/oauth2/v2/auth), l'endpoint del token (https://oauth2.googleapis.com/token) e gli ambiti di autorizzazione richiesti (https://www.googleapis.com/auth/geminidataanalyticsehttps://www.googleapis.com/auth/bigquery.readonly). - Gli utenti aziendali pongono domande in linguaggio naturale nella piattaforma agentica. Anziché eseguire query direttamente sui database non elaborati, l'agente principale della piattaforma (l'LLM orchestratore) comunica con il server MCP remoto dell'API Analisi conversazionale per scoprire gli agenti per i dati pertinenti, indirizzare la domanda dell'utente all'agente per i dati con ambito appropriato e restituire la risposta sintetizzata.
Propagazione dell'identità
Per mantenere la governance dei dati aziendali quando le richieste provengono da agenti root di terze parti o esterni, il server MCP remoto applica la propagazione dell'identità end-to-end:
- Autenticazione delegata dall'utente: quando un utente aziendale interagisce con l'agente root, la piattaforma agentica autentica l'utente tramite un flusso OAuth 2.0 a tre vie e include il token di accesso OAuth delegato dall'utente nelle intestazioni HTTP delle richieste inviate al gateway MCP.
- Inoltro delle credenziali dell'utente finale (EUC): il server MCP remoto convalida il token e propaga le credenziali dell'utente finale attraverso il livello dell'API Conversational Analytics ai motori di dati sottostanti, tra cui BigQuery e database operativi come Spanner, AlloyDB e Cloud SQL.
- Accesso ai dati regolamentato: poiché le query vengono eseguite utilizzando l'identità dell'utente autenticato anziché un account di servizio condiviso, le origini dati sottostanti applicano automaticamente le autorizzazioni IAM esistenti, le policy di sicurezza a livello di riga e di colonna e i limiti di accesso ai dati regolamentati. Gli utenti possono solo scoprire gli agenti per i dati ed eseguire query sui set di dati per i quali hanno già l'autorizzazione di accesso.
- Modello a due identità di Looker: per BigQuery e i database operativi, le query vengono eseguite con le credenziali Google OAuth inoltrate del singolo utente. Per gli agenti per i dati basati su Looker, l'autenticazione utilizza un modello a due identità: il token OAuth di Google dell'utente autorizza l'accesso all'agente per i dati in Google IAM, ma la query viene eseguita in Looker utilizzando le credenziali fornite per un utente dell'API Looker (passate nel blocco delle credenziali dello strumento di chat). L'accesso al modello di Looker, le autorizzazioni e le regole a livello di riga riflettono l'utente API configurato anziché l'identità di Looker del singolo utente finale.
Come gli agenti root accedono ai metodi API
Quando un client MCP si connette a https://geminidataanalytics.googleapis.com/mcp, chiama il metodo MCP standard tools/list per importare dinamicamente gli schemi degli strumenti esposti dall'API Analisi conversazionale. L'agente principale interagisce quindi con l'API Analisi conversazionale richiamando questi strumenti e risorse MCP, che vengono mappati direttamente ai metodi dell'API REST sottostante:
| Strumento o risorsa MCP | Metodo API Analisi conversazionale mappato | Come viene utilizzato dall'agente principale |
|---|---|---|
list_data_agents |
projects.
|
Rileva gli agenti per i dati disponibili. L'agente principale passa il target PROJECT_ID (e LOCATION) e riceve un elenco di agenti per i dati attivi a cui l'utente è autorizzato ad accedere, inclusi l'ID e la descrizione di ciascun agente. L'agente principale valuta queste descrizioni per determinare quale agente per i dati può rispondere alla domanda dell'utente. Suggerimento: includi l'PROJECT_ID di destinazione nelle istruzioni di sistema personalizzate dell'agente principale, in modo che non chieda agli utenti aziendali di fornire un ID progetto. |
|
(o la risorsa MCP |
projects.
|
Esamina i metadati e il contesto di un agente per i dati specifico. L'agente principale passa il target AGENT_ID per recuperare i dettagli di configurazione, come le tabelle BigQuery collegate, le istruzioni di sistema, i glossari o le query verificate, quando le descrizioni degli agenti da sole non sono sufficienti per instradare un prompt complesso. |
chat
|
projects.
|
Funge da proxy di esecuzione per le query di conversazione. Per eseguire una query su un agente per i dati rilevato, l'agente principale passa |
MCP Toolbox for Databases
Puoi anche accedere all'API Analisi conversazionale tramite il server open source MCP Toolbox for Databases. Questo server fornisce strumenti predefiniti compatibili con MCP che espongono il metodo chat nell'API Analisi conversazionale:
bigquery-conversational-analytics: esegue il wrapping del metodochatper le origini dati BigQuery.looker-conversational-analytics: esegue il wrapping del metodochatper le origini dati di Looker.
MCP è un livello di interoperabilità che espone le funzionalità di analisi come strumenti ai client compatibili con MCP, anziché un modello di esecuzione separato dell'API Analisi conversazionale.
Pattern di implementazione MCP per architetture autonome e ADK
Puoi implementare l'MCP tramite i seguenti pattern:
| Pattern | Dettagli |
|---|---|
| MCP autonomo (senza ADK) |
Utilizza il server MCP Toolbox for Databases come server autonomo per connetterti a qualsiasi client conforme a MCP. Questo pattern è di uso comune per le seguenti attività:
|
| MCP all'interno di ADK |
Il framework ADK fornisce i seguenti meccanismi per l'integrazione dei server MCP nei workflow degli agenti:
|
Puoi anche creare server MCP utilizzando il framework FastMCP per esporre gli strumenti creati con il framework ADK a qualsiasi client conforme a MCP. Questo approccio rende i tuoi agenti ADK disponibili come strumenti in altri ecosistemi.
Scegli un pattern di integrazione che soddisfi i requisiti di architettura specifici della tua applicazione:
- L'utilizzo di set di strumenti integrati di Agent Development Kit (ADK), come
BigQueryToolsetoDataAgentToolset, offre un'integrazione più stretta senza dipendenze da server esterni. Questo approccio è ideale per i sistemi che esistono interamente all'interno del framework ADK. - L'utilizzo degli strumenti di MCP Toolbox garantisce l'interoperabilità tra i client conformi a MCP. Questo approccio è ideale per gli strumenti di dati che devono servire più applicazioni consumer o IDE di terze parti.
Orchestrazione orizzontale (A2A)
Il protocollo Agent2Agent (A2A) è uno standard aperto che consente ad agenti specializzati su sistemi diversi di comunicare e collaborare in modo sicuro senza richiedere un codice di integrazione personalizzato.
Man mano che i sistemi scalano, le organizzazioni spesso implementano più agenti specializzati basati su framework o infrastrutture cloud diversi. A2A stabilisce un livello di messaggistica universale per questi agenti autonomi. Anziché utilizzare API personalizzate, ogni agente pubblica una scheda agente, ovvero un profilo rilevabile che descrive in dettaglio le funzionalità dell'agente, i formati dei dati supportati e i requisiti di sicurezza.
Quando un orchestratore centrale o un agente peer richiede dati analitici, delega l'attività in modo sicuro a un agente per i dati tramite messaggistica A2A strutturata. L'agente per i dati elabora la richiesta in modo autonomo e restituisce i risultati, separando la logica di esecuzione dal richiedente.
Per scoprire come trovare le schede degli agenti, inviare messaggi e trasmettere artefatti strutturati utilizzando il protocollo A2A, consulta Orchestra gli agenti per i dati con A2A.
Scegli un pattern di integrazione
Utilizza la tabella seguente per confrontare la complessità, la governance e le funzionalità di ciascun pattern di integrazione.
I livelli di complessità sono definiti come segue:
- Basso: pattern che richiedono un codice personalizzato minimo e si basano su interfacce utente o strumenti predefiniti.
- Medio: pattern che richiedono lo sviluppo di frontend personalizzati e l'integrazione di API o SDK, ma evitano un'infrastruttura di orchestrazione di backend complessa.
- Alta: pattern che richiedono lo sviluppo di applicazioni full-stack, la gestione dello stato della conversazione, più livelli di autenticazione o un'infrastruttura di orchestrazione intermedia.
- Variabile: pattern in cui la complessità dipende dal metodo di integrazione sottostante scelto.
| Pattern di integrazione | complessità | Personalizzazione | Agent Governance | Controllo degli accessi | Multi-agente | Streaming | Portabilità |
|---|---|---|---|---|---|---|---|
| Incorporamento di iframe di Looker | Bassa | Bassa | Gestito tramite Looker | Looker | No | Integrato | Solo Looker |
| API Looker e SDK | Media | Alta | Gestito tramite Looker | Looker | No | Integrato | Solo Looker |
| API Analisi conversazionale con origine Looker | Variabile | Alta | Funzionalità gestita tramite l'API | Looker e IAM | Sì | Sì | Qualsiasi Google Cloud superficie |
| Agente singolo (API diretta) | Media | Alta | Funzionalità gestita tramite l'API | IAM | No | Sì (supportato) | Qualsiasi Google Cloud superficie |
| Orchestratore personalizzato | Alta | Molto alta | Funzionalità gestita tramite l'API | IAM | Manuale | Manuale | Qualsiasi Google Cloud superficie |
Basato su schema con BigQueryToolset (ADK) |
Bassa | Media | Nessuno (inferenza dello schema) | IAM | Sì (ADK) | No (bloccante) | Ecosistema ADK |
Gestito con DataAgentToolset (ADK) |
Bassa | Media | Funzionalità gestita tramite l'API | IAM | Sì (ADK) | No (bloccante) | Ecosistema ADK |
| Sub-agente di streaming personalizzato (ADK) | Alta | Molto alta | Funzionalità gestita tramite l'API | IAM | Sì (ADK) | Sì (personalizzato) | Ecosistema ADK |
| MCP autonomo | Media | Media | Nessuno (inferenza dello schema) | IAM | No | No | Qualsiasi client MCP |
| MCP all'interno di ADK | Media | Alta | Nessuno (inferenza dello schema) | IAM | Sì (ADK) | No | Client ADK e MCP |
| Protocollo A2A | Alta | Alta | Dipendente dal framework | IAM | Sì | Sì | Multipiattaforma |
Passaggi successivi
- Scopri di più sull'architettura e sui concetti chiave dell'API Conversational Analytics.
- 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 orchestrare gli agenti per i dati con A2A.
- Scopri come eseguire il rendering delle risposte dell'agente per le origini dati di Looker.