Creare agenti di dati e chattare con i tuoi dati

Importante:l'API Data QnA è ritirata. Se esegui la migrazione dall'API Data QnA, consulta la guida alla migrazione per una panoramica delle differenze principali e dei passaggi di migrazione richiesti.

Gli sviluppatori possono utilizzare l'API Conversational Analytics, a cui si accede tramite geminidataanalytics.googleapis.com o endpoint regionali, per creare un'interfaccia di chat basata sull'intelligenza artificiale (AI) o un agente di dati. L'API utilizza il linguaggio naturale per rispondere a domande sui dati strutturati in BigQuery, Looker, Data Studio e origini dati di database (AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL in anteprima in v1beta). Oltre alla chat a più turni, puoi utilizzare il metodo QueryData per eseguire query single-turn.

Con l'API Conversational Analytics, fornisci all'agente dati informazioni sull'attività e dati (contesto), nonché l'accesso a strumenti come SQL, Python e librerie di visualizzazione. Queste risposte dell'agente vengono presentate all'utente e possono essere registrate dall'applicazione client, creando un'esperienza di chat con i dati fluida e verificabile.

Scopri come e quando Gemini per Google Cloud utilizza i tuoi dati.

Poiché si tratta di una tecnologia in fase iniziale, Gemini per i prodotti Google Cloud può generare output apparentemente plausibili, ma di fatto errati. Ti consigliamo di verificare tutti gli output di Gemini per i prodotti Google Cloud prima di utilizzarli. Per saperne di più, consulta Gemini for Google Cloud e l'AI responsabile.

Inizia a utilizzare l'API Conversational Analytics

Per iniziare a utilizzare l'API Conversational Analytics, consulta la seguente documentazione per comprendere gli approcci di integrazione e i concetti di base disponibili:

• Architettura e concetti chiave: scopri come gli agenti di dati elaborano le richieste, i workflow per i creatori e gli utenti di agenti, le modalità di conversazione e i ruoli Identity and Access Management (IAM) richiesti.
• Pattern di integrazione per gli agenti di dati: confronta gli approcci architetturali per determinare il metodo di connessione migliore per la tua applicazione.
• Gestione dello stato: scopri le modalità di conversazione con stato e senza stato, come l'API gestisce la cronologia delle conversazioni e gli ambiti dello stato della sessione dell'ADK.
• Sicurezza, privacy, rischio e conformità: scopri le opzioni di sicurezza e conformità per l'API Conversational Analytics.
• Posizioni dell'API Conversational Analytics: fornisce una panoramica degli endpoint API regionali o multiregionali che ti consentono di controllare la posizione geografica delle risorse, della configurazione e dei dati del tuo agente.

Per iniziare a creare agenti di dati, completa i passaggi descritti nella documentazione relativa alla configurazione e ai prerequisiti. Per procedure dettagliate guidate, applicazioni di esempio, SDK e altri strumenti di sviluppo, consulta Tutorial, demo e strumenti dell'API Conversational Analytics.

Configurazione e prerequisiti

Prima di utilizzare l'API o gli esempi, completa i seguenti passaggi:

• Abilita l'API Conversational Analytics: descrive i prerequisiti per abilitare l'API Conversational Analytics.
• Controllo dell'accesso con IAM: descrive come utilizzare Identity and Access Management per condividere e gestire l'accesso agli agenti di dati.
• Autenticazione e connessione a un'origine dati: fornisce istruzioni per l'autenticazione all'API e la configurazione delle connessioni alle origini dati BigQuery, Lakehouse, Looker, Data Studio e database (AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL).
• Chiavi di crittografia gestite dal cliente (CMEK): descrive come utilizzare le tue chiavi di crittografia in Cloud Key Management Service per proteggere gli agenti di dati e le conversazioni che utilizzano le origini dati di Looker.
• Vincoli delle policy dell'organizzazione: descrive come utilizzare i vincoli delle policy dell'organizzazione predefiniti per controllare le risorse a livello di organizzazione, cartella o progetto.

Creare e interagire con un agente di dati

Dopo aver completato i passaggi precedenti, utilizza l'API Conversational Analytics per creare un agente dati e interagire con lui seguendo questi passaggi:

• Crea un agente di dati utilizzando HTTP: fornisce un esempio completo di creazione e interazione con un agente di dati utilizzando richieste HTTP dirette con Python.
• Crea un agente di dati utilizzando l'SDK Python: fornisce un esempio completo di creazione e interazione con un agente di dati utilizzando l'SDK Python.
• Orchestrare gli agenti di dati con A2A: scopri come individuare le funzionalità degli agenti, delegare le query analitiche e trasmettere in streaming le query SQL e le visualizzazioni dei grafici nei sistemi multi-agente.
• Guida il comportamento dell'agente con il contesto creato: scopri come fornire un contesto creato per guidare il comportamento dell'agente e migliorare l'accuratezza delle risposte. Puoi anche visualizzare esempi di contesto creato con origini dati BigQuery e con origini dati Looker.

• Esegui il rendering di una risposta dell'agente dell'API Conversational Analytics come visualizzazione: fornisce un esempio di elaborazione delle specifiche del grafico dalle risposte dell'API e del rendering come visualizzazioni utilizzando l'SDK Python e la libreria Vega-Altair.

  Nota: il rendering delle visualizzazioni non è supportato per le origini dati del database (AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL).

Best practice

Consulta le seguenti guide per scoprire le best practice per l'utilizzo dell'API Conversational Analytics:

• Gestisci i costi di BigQuery per i tuoi agenti: scopri come monitorare e gestire i costi di BigQuery per gli agenti dell'API Conversational Analytics impostando limiti di spesa a livello di progetto, utente e query.
• Poni domande efficaci: scopri come formulare domande efficaci per i tuoi agenti per ottenere il massimo dall'API Conversational Analytics.
• Conservazione ed eliminazione dei dati: scopri di più sulla conservazione e l'eliminazione dei dati per gli agenti e le conversazioni dell'API Conversational Analytics.
• Quote e limiti: scopri di più su quote e limiti per l'API Conversational Analytics.
• Risolvi i problemi relativi agli errori dell'API Conversational Analytics: risolvi i problemi relativi agli errori comuni dell'API Conversational Analytics.
• Limitazioni note: fornisce informazioni dettagliate sulle limitazioni note dell'API Conversational Analytics, incluse quelle relative a query, dati, visualizzazioni e domande.
• Rendering delle risposte dell'agente per le origini dati di Looker: scopri le best practice per il rendering delle risposte dell'API Conversational Analytics in un'interfaccia utente quando utilizzi le origini dati di Looker.

Librerie client e riferimento API

• Riferimento REST di Gemini Data Analytics: fornisce descrizioni dettagliate di versioni, metodi, endpoint e definizioni dei tipi dell'API.
• SDK e strumenti di sviluppo: elenca le librerie client specifiche per la lingua.

Operazioni API chiave

L'API fornisce i seguenti endpoint principali per la gestione degli agenti di dati e delle conversazioni. Gli endpoint v1 nella tabella seguente supportano le origini dati BigQuery, Looker e Data Studio. Poiché le origini dati del database sono in anteprima in v1beta, specifica i percorsi /v1beta/ corrispondenti per le origini del database.

Quando crei questi percorsi (o i nomi delle risorse SDK corrispondenti), sostituisci i caratteri jolly (*) con l'ID progetto, l'identificatore di località (ad esempio global o us) e l'ID risorsa (ad esempio l'ID agente o l'ID conversazione), se applicabile.

Importante: la località nel percorso della richiesta deve corrispondere a quella dell'endpoint che stai chiamando. Ad esempio, se chiami l'endpoint geminidataanalytics.us.rep.googleapis.com, specifica us nel percorso della richiesta (ad esempio /locations/us). Per informazioni dettagliate sulla residenza dei dati e sulla configurazione degli endpoint, consulta Residenza dei dati.

Operazione	Metodo HTTP	Endpoint	Descrizione
Crea un agente	POST	/v1/projects/*/locations/*/dataAgents	Crea un nuovo agente di dati.
Crea un agente in modo sincrono	POST	/v1/projects/*/locations/*/dataAgents:createSync	Crea un nuovo agente di dati in modo sincrono.
Trovare un agente	GET	/v1/projects/*/locations/*/dataAgents/*	Recupera i dettagli di un agente dati specifico.
Ottieni il criterio Identity and Access Management	POST	/v1/projects/*/locations/*/dataAgents/*:getIamPolicy	Recupera le autorizzazioni di Identity and Access Management assegnate a ogni utente per un agente dati specifico. Gli utenti con il ruolo Proprietario agente dati possono chiamare questo endpoint per visualizzare la policy di Identity and Access Management dell'agente dati prima di utilizzare l'endpoint setIAMpolicy per condividere un agente dati con altri utenti.
Imposta il criterio Identity and Access Management	POST	/v1/projects/*/locations/*/dataAgents/*:setIamPolicy	Imposta il criterio Identity and Access Management per un agente dati specifico. Gli utenti con un ruolo Proprietario agente dati devono chiamare questo endpoint per condividere un agente dati con altri utenti, il che aggiorna effettivamente le autorizzazioni di Identity and Access Management di questi utenti.
Aggiornare un agente	PATCH	/v1/projects/*/locations/*/dataAgents/*	Modifica un agente dati esistente.
Aggiorna un agente in modo sincrono	PATCH	/v1/projects/*/locations/*/dataAgents/*:updateSync	Modifica in modo sincrono un agente dati esistente.
Elenca agenti	GET	/v1/projects/*/locations/*/dataAgents	Elenca gli agenti di dati disponibili in un progetto.
Elenco degli agenti accessibili	GET	/v1/projects/*/locations/*/dataAgents:listaccessible	Elenca gli agenti di dati accessibili in un progetto. Un agente dati è considerato accessibile se l'utente che richiama questa API dispone dell'autorizzazione get per l'agente. Puoi utilizzare il campo creator_filter per gestire gli agenti restituiti da questo metodo: NONE (impostazione predefinita): restituisce tutti gli agenti di dati accessibili all'utente, indipendentemente da chi li ha creati. CREATOR_ONLY: restituisce solo gli agenti di dati accessibili all'utente e creati da quest'ultimo. NOT_CREATOR_ONLY: restituisce solo gli agenti di dati accessibili all'utente e creati da altri.
Eliminare un agente	DELETE	/v1/projects/*/locations/*/dataAgents/*	Rimuove un agente di dati.
Eliminare un agente in modo sincrono	DELETE	/v1/projects/*/locations/*/dataAgents/*:deleteSync	Rimuove un agente di dati in modo sincrono.
Crea una conversazione	POST	/v1/projects/*/locations/*/conversations	Avvia una nuova conversazione persistente.
Chattare utilizzando un riferimento alla conversazione	POST	/v1/projects/*/locations/*:chat	Continua una conversazione stateful inviando un messaggio chat che fa riferimento a una conversazione esistente e al relativo contesto dell'agente. Per le conversazioni multi-turno, Google Cloud memorizza e gestisce la cronologia della conversazione.
Chattare utilizzando un riferimento dell'agente di dati	POST	/v1/projects/*/locations/*:chat	Invia un messaggio chat stateless che fa riferimento a un agente dati salvato per il contesto. Per le conversazioni multi-turno, la tua applicazione deve gestire e fornire la cronologia della conversazione a ogni richiesta.
Chattare utilizzando il contesto in linea	POST	/v1/projects/*/locations/*:chat	Invia un messaggio chat stateless fornendo tutto il contesto direttamente nella richiesta, senza utilizzare un agente dati salvato. Per le conversazioni multi-turno, la tua applicazione deve gestire e fornire la cronologia della conversazione a ogni richiesta.
Recuperare una conversazione	GET	/v1/projects/*/locations/*/conversations/*	Recupera i dettagli di una conversazione specifica.
Elenca conversazioni	GET	/v1/projects/*/locations/*/conversations	Elenca le conversazioni in un progetto specifico.
Elencare i messaggi in una conversazione	GET	/v1/projects/*/locations/*/conversations/*/messages	Elenca i messaggi all'interno di una conversazione specifica.
Eliminare una conversazione	DELETE	/v1/projects/*/locations/*/conversations/*	Elimina una conversazione specifica. Per chiamare questo endpoint è necessario il ruolo Identity and Access Management Topic Admin o almeno l'autorizzazione Identity and Access Management cloudaicompanion.topics.delete.
Esegui query sui dati	POST	/v1beta/projects/*/locations/*/conversations:queryData	Esegue query sui dati dei database AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL utilizzando il linguaggio naturale.
Ottenere la scheda agente (A2A)	GET	/v1/a2a/projects/*/locations/*/agents/*/v1/card	Recupera le funzionalità, le competenze e le estensioni supportate per un agente dati integrato o personalizzato utilizzando il protocollo A2A.
Invia messaggio (A2A)	POST	/v1/a2a/projects/*/locations/*/agents/*/v1/message:send	Invia un messaggio a un agente di dati utilizzando il protocollo A2A.
Inviare un messaggio di streaming (A2A)	POST	/v1/a2a/projects/*/locations/*/agents/*/v1/message:stream	Invia un messaggio di streaming a un agente dati utilizzando il protocollo A2A, restituendo lo stato di avanzamento del ragionamento in tempo reale e artefatti strutturati (come query SQL e visualizzazioni di grafici).

Assistenza e feedback

Per ricevere assistenza o segnalare un problema, contatta l'assistenza clienti. Segui le indicazioni riportate in Crea e gestisci le richieste di assistenza per aprire la tua richiesta di assistenza. Segui queste linee guida quando crei la richiesta:

• Per l'assistenza per l'API Conversational Analytics con BigQuery, seleziona BigQuery nell'elenco Seleziona un prodotto e AI e machine learning::API Conversational Analytics in BigQuery nel campo Funzionalità.
• Per l'assistenza per l'API Conversational Analytics con Looker, nell'elenco Seleziona un prodotto, seleziona Looker (originale) e nel campo Funzionalità, seleziona Gemini in Looker::API Conversational Analytics.

Nota:il supporto per l'API Conversational Analytics (Analisi conversazionale) copre i problemi tecnici relativi all'utilizzo del servizio API. Il debug del codice generale e personalizzato non rientra nell'ambito di questa verifica. I clienti sono responsabili del debug del proprio codice personalizzato.

Se hai feedback o domande generali sull'API Conversational Analytics, invia un'email all'indirizzo [e-mail]. Non garantiamo una risposta alle comunicazioni via email, ma leggiamo le email e facciamo riferimento a questo feedback durante la pianificazione della roadmap.

Puoi anche inviare una richiesta di funzionalità per nuove funzionalità dell'API Conversational Analytics.