Creare agenti di dati e chattare con i tuoi dati

Importante: l'API Data QnA è stata ritirata. Se stai eseguendo 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 per i dati. L'API utilizza il linguaggio naturale per rispondere alle domande sui dati strutturati in BigQuery, Looker, Data Studio e nelle origini dati dei 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 a turno singolo.

Con l'API Analisi conversazionale, fornisci all'agente per i dati informazioni e dati aziendali (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 risultati 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 in 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 disponibili e i concetti fondamentali:

• Architettura e concetti chiave: scopri come gli agenti per i dati elaborano le richieste, i workflow per i creator e gli utenti degli agenti, le modalità conversazionali e i ruoli Identity and Access Management (IAM) richiesti.
• Modelli di integrazione per gli agenti per i dati: confronta gli approcci architetturali per determinare il metodo di connessione migliore per la tua applicazione.
• Gestione dello stato: scopri le modalità di conversazione stateful e stateless, come l'API gestisce la cronologia delle conversazioni e gli ambiti dello stato della sessione ADK.
• Sicurezza, privacy, rischio e conformità: scopri le opzioni di sicurezza e conformità per l'API Conversational Analytics.
• Località 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 dell'agente.

Per iniziare a creare agenti per i dati, completa i passaggi descritti nella documentazione relativa alla configurazione e ai prerequisiti. Per procedure dettagliate, applicazioni di esempio, SDK e altri strumenti per sviluppatori, 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 degli accessi con IAM: descrive come utilizzare Identity and Access Management per condividere e gestire l'accesso agli agenti per i dati.
• Autenticati e connettiti 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 del database (AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL).
• Connettiti a BigQuery: descrive i ruoli richiesti e come connettere un agente per i dati a tabelle BigQuery e grafici.
• Connettiti a Looker: descrive come connettere un agente per i dati alle esplorazioni di Looker ed eseguire l'autenticazione nell'istanza di Looker.
• Chiavi di crittografia gestite dal cliente (CMEK): descrive come utilizzare le tue chiavi di crittografia in Cloud Key Management Service per proteggere gli agenti per i dati e le conversazioni.
• 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.

Crea e interagisci con un agente per i dati

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

• Crea un agente per i dati utilizzando HTTP: fornisce un esempio completo di creazione e interazione con un agente per i dati utilizzando richieste HTTP dirette con Python.
• Crea un agente per i dati utilizzando l'SDK Python: fornisce un esempio completo di creazione e interazione con un agente per i dati utilizzando l'SDK Python.
• Orchestra gli agenti per i dati con A2A: scopri come identificare le capacità agentiche, delegare query analitiche e trasmettere in streaming query SQL e visualizzazioni di grafici tra 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 dei grafici dalle risposte dell'API e di 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.
• Fai 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 per i dati e le conversazioni dell'API Conversational Analytics.
• Quote e limiti: scopri le quote e i limiti per l'API Conversational Analytics.
• Risolvere i problemi relativi agli errori dell'API Conversational Analytics: risolvi gli errori comuni dell'API Conversational Analytics.
• Limitazioni note: fornisce informazioni dettagliate sulle limitazioni note dell'API Conversational Analytics, incluse le limitazioni di query, dati, visualizzazioni e domande.
• Esegui il rendering delle risposte dell'agente per le origini dati di Looker: scopri le best practice per eseguire il rendering delle risposte dell'API Conversational Analytics in un'interfaccia utente quando utilizzi le origini dati di Looker.

Riferimento API e librerie client

• Riferimento REST di Gemini Data Analytics: fornisce descrizioni dettagliate delle versioni, dei metodi, degli endpoint e delle definizioni dei tipi dell'API.
• SDK e strumenti per sviluppatori: elenca le librerie client specifiche per i linguaggi.

Operazioni API chiave

L'API fornisce i seguenti endpoint principali per la gestione degli agenti per i 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 della 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 alla località 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 i dettagli 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 per i dati.
Crea un agente in modo sincrono	POST	/v1/projects/*/locations/*/dataAgents:createSync	Crea un nuovo agente per i dati in modo sincrono.
Ottieni un agente	GET	/v1/projects/*/locations/*/dataAgents/*	Recupera i dettagli di un agente per i dati specifico.
Ottieni policy di Identity and Access Management	POST	/v1/projects/*/locations/*/dataAgents/*:getIamPolicy	Recupera le autorizzazioni di Identity and Access Management assegnate a ciascun utente per un agente per i dati specifico. Gli utenti con un ruolo Data Agent Owner possono chiamare questo endpoint per visualizzare la policy di Identity and Access Management dell'agente per i dati prima di utilizzare l'endpoint setIAMpolicy per condividere un agente per i dati con altri utenti.
Imposta la policy di Identity and Access Management	POST	/v1/projects/*/locations/*/dataAgents/*:setIamPolicy	Imposta la policy di Identity and Access Management per un agente per i dati specifico. Gli utenti con un ruolo Data Agent Owner devono chiamare questo endpoint per condividere un agente per i dati con altri utenti, aggiornando di fatto le autorizzazioni di Identity and Access Management di questi utenti.
Aggiorna un agente	PATCH	/v1/projects/*/locations/*/dataAgents/*	Modifica un agente per i dati esistente.
Aggiorna un agente in modo sincrono	PATCH	/v1/projects/*/locations/*/dataAgents/*:updateSync	Modifica un agente per i dati esistente in modo sincrono.
Elenca agenti	GET	/v1/projects/*/locations/*/dataAgents	Elenca gli agenti per i dati disponibili in un progetto.
Elenca gli agenti accessibili	GET	/v1/projects/*/locations/*/dataAgents:listaccessible	Elenca gli agenti per i dati accessibili in un progetto. Un agente per i dati è considerato accessibile se l'utente che richiama questa API dispone dell'autorizzazione get sull'agente. Puoi utilizzare il campo creator_filter per gestire gli agenti restituiti da questo metodo: NONE (predefinito): restituisce tutti gli agenti per i dati accessibili all'utente, indipendentemente da chi li ha creati. CREATOR_ONLY: restituisce solo gli agenti per i dati accessibili all'utente e creati da quest'ultimo. NOT_CREATOR_ONLY: restituisce solo gli agenti per i dati accessibili all'utente e creati da altri.
Elimina un agente	DELETE	/v1/projects/*/locations/*/dataAgents/*	Rimuove un agente per i dati.
Elimina un agente in modo sincrono	DELETE	/v1/projects/*/locations/*/dataAgents/*:deleteSync	Rimuove un agente per i dati in modo sincrono.
Crea una conversazione	POST	/v1/projects/*/locations/*/conversations	Avvia una nuova conversazione persistente.
Chatta 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 contesto dell'agente associato. Per le conversazioni multi-turno, Google Cloud archivia e gestisce la cronologia delle conversazioni.
Chatta utilizzando un riferimento all'agente per i dati	POST	/v1/projects/*/locations/*:chat	Invia un messaggio chat stateless che fa riferimento a un agente per i dati salvato per il contesto. Per le conversazioni multi-turno, l'applicazione deve gestire e fornire la cronologia delle conversazioni con ogni richiesta.
Chatta 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 per i dati salvato. Per le conversazioni multi-turno, l'applicazione deve gestire e fornire la cronologia delle conversazioni con ogni richiesta.
Recupera 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.
Elenca i messaggi di 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.
Ottieni la scheda agente (A2A)	GET	/v1/a2a/projects/*/locations/*/agents/*/v1/card	Recupera le funzionalità, le competenze e le estensioni supportate per un agente per i 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 per i dati utilizzando il protocollo A2A.
Invia messaggio in streaming (A2A)	POST	/v1/a2a/projects/*/locations/*/agents/*/v1/message:stream	Invia un messaggio in streaming a un agente per i dati utilizzando il protocollo A2A, restituendo l'avanzamento del ragionamento in tempo reale e gli 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. Quando crei la richiesta, segui queste linee guida:

• Per l'assistenza per l'API Conversational Analytics con BigQuery, nell'elenco Seleziona un prodotto, seleziona BigQuery e nel campo Funzionalità, seleziona AI e machine learning::API Conversational Analytics in BigQuery.
• 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: l'assistenza per l'API Conversational Analytics copre i problemi tecnici relativi all'utilizzo del servizio API. Il debug del codice generale e personalizzato non rientra nell'ambito. I clienti sono responsabili del debug del proprio codice personalizzato.

Se hai domande o feedback 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.