Verificare l'accuratezza delle affermazioni con un agente AI dell'ADK e il modello Gemini

Livello di programmazione: avanzato
Durata: 30 minuti
Tipo di progetto: funzione personalizzata

Panoramica

Una funzione personalizzata di verifica dei fatti per Fogli Google da utilizzare come progetto Apps Script associato basato su un agente Vertex AI e sul modello Gemini.

Questo esempio mostra come utilizzare due potenti tipi di risorse AI direttamente nei fogli di lavoro Google Sheets:

1. Agenti AI per funzionalità di ragionamento sofisticate, multi-strumento e multi-passaggio utilizzando gli agenti ADK di cui è stato eseguito il deployment in Vertex AI Agent Engine.
2. Modelli di AI per funzionalità avanzate di comprensione, generazione e riepilogo utilizzando i modelli Gemini di Vertex AI.

Obiettivi

• Comprendi cosa fa la soluzione.
• Scopri come viene implementata la soluzione.
• Distribuisci l'agente Vertex AI.
• Imposta lo script.
• Esegui lo script.

Informazioni su questa soluzione

La funzione personalizzata di Fogli si chiama FACT_CHECK e funziona come soluzione end-to-end. Analizza un'affermazione, basa la sua risposta sulle informazioni web più recenti e restituisce il risultato nel formato che ti serve:

• Utilizzo:
  • =FACT_CHECK("Your statement here") per un output conciso e riassuntivo.
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") per un formato di output specifico.
• Motivazione: Agente AI ADK per auditor LLM (esempio Python).
• Formattazione dell'output: modello Gemini.

Questa soluzione richiede le API REST di Vertex AI tramite UrlFetchApp.

Architettura

Il diagramma seguente mostra l'architettura delle risorse di Google Workspace e Google Cloud utilizzate dalla funzione personalizzata.

Prerequisiti

Per utilizzare questo esempio, devi soddisfare i seguenti prerequisiti:

• Un Account Google (gli account Google Workspace potrebbero richiedere l'approvazione dell'amministratore).

• Un browser web con accesso a internet.

• Prerequisiti dell'agente LLM Auditor ADK

  • Python 3.11+: per l'installazione, segui le istruzioni sul sito web ufficiale di Python.
  • Python Poetry: per l'installazione, segui le istruzioni riportate sul sito web ufficiale di Poetry.
  • Google Cloud CLI: per l'installazione, segui le istruzioni sul sito web di Google Cloud ufficiale.

Prepara l'ambiente

Questa sezione mostra come creare e configurare un progetto Google Cloud.

Crea un progetto Google Cloud

Console Google Cloud

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Crea un progetto.

   Vai a Crea un progetto

2. Nel campo Project Name (Nome progetto), inserisci un nome descrittivo per il progetto.

   (Facoltativo) Per modificare l'ID progetto, fai clic su Modifica. L'ID progetto non può essere modificato dopo la creazione del progetto, quindi scegli un ID che soddisfi le tue esigenze per l'intera durata del progetto.

3. Nel campo Posizione, fai clic su Sfoglia per visualizzare le potenziali posizioni per il tuo progetto. Quindi, fai clic su Seleziona.
   Attenzione: non riesci a trovare la tua organizzazione Google Workspace?
   Ciò significa che non hai eseguito l'accesso a un account Google Workspace. Alcune delle funzionalità descritte nella documentazione per gli sviluppatori di Google Workspace sono disponibili solo per i progetti associati a un'organizzazione.
4. Fai clic su Crea. La console Google Cloud passa alla pagina Dashboard e il tuo progetto viene creato entro pochi minuti.

Interfaccia a riga di comando gcloud

In uno dei seguenti ambienti di sviluppo, accedi a Google Cloud CLI (gcloud):

• Cloud Shell: per utilizzare un terminale online con la CLI gcloud già configurata, attiva Cloud Shell.
  Attiva Cloud Shell
• Shell locale: per utilizzare un ambiente di sviluppo locale, installa e inizializza gcloud CLI.
  Per creare un progetto Cloud, utilizza il comando gcloud projects create:

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID impostando l'ID del progetto che vuoi creare.

Abilita la fatturazione per il progetto Cloud

Se non riesci a collegare un account di fatturazione, non disponi delle autorizzazioni necessarie per apportare questa modifica. Per ulteriori informazioni, vedi Autorizzazioni richieste per attivare la fatturazione.

Console Google Cloud

1. Nella console di Google Cloud, vai a Fatturazione. Fai clic su Menu > Fatturazione > I miei progetti.

   Vai a Fatturazione per i miei progetti

2. In Seleziona un'organizzazione, scegli l'organizzazione associata al tuo progetto Google Cloud.
3. Nella riga del progetto, apri il menu Azioni (), fai clic su Modifica fatturazione e scegli l'account Cloud Billing.
4. Fai clic su Imposta account.

Interfaccia a riga di comando gcloud

1. Per elencare gli account di fatturazione disponibili, esegui:

   gcloud billing accounts list

2. Collega un account di fatturazione a un progetto Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Sostituisci quanto segue:

   • PROJECT_ID è l'ID progetto del progetto Cloud per il quale vuoi attivare la fatturazione.
   • BILLING_ACCOUNT_ID è l'ID account di fatturazione da collegare al progetto Google Cloud.

Abilita l'API Vertex AI

Console Google Cloud

1. Nella console Google Cloud, abilita l'API Vertex AI.

   Abilita le API

2. Verifica di abilitare l'API Vertex AI nel progetto Cloud corretto, poi fai clic su Avanti.

3. Verifica di abilitare l'API corretta, poi fai clic su Abilita.

Interfaccia a riga di comando gcloud

1. Se necessario, imposta il progetto Cloud corrente su quello che hai creato con il comando gcloud config set project:

   gcloud config set project PROJECT_ID

   Sostituisci PROJECT_ID con l'ID progetto del progetto Cloud che hai creato.

2. Abilita l'API Vertex AI con il comando gcloud services enable:

   gcloud services enable aiplatform.googleapis.com

Crea un service account nella console Google Cloud

Crea un nuovo service account con il ruolo Vertex AI User seguendo questi passaggi:

Console Google Cloud

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Service account.

   Vai a Service account

2. Fai clic su Crea account di servizio.
3. Compila i dettagli del service account, quindi fai clic su Crea e continua.
   Nota: per impostazione predefinita, Google crea un ID service account univoco. Se vuoi modificare l'ID, modificalo nel campo ID account di servizio.
4. (Facoltativo) Assegna ruoli al tuo service account per concedere l'accesso alle risorse del tuo progetto Google Cloud. Per ulteriori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.
5. Fai clic su Continua.
6. (Facoltativo) Inserisci gli utenti o i gruppi che possono gestire ed eseguire azioni con questo service account. Per maggiori dettagli, consulta Gestione della simulazione dell'identità dei service account.
7. Fai clic su Fine. Prendi nota dell'indirizzo email del service account.

Interfaccia a riga di comando gcloud

1. Crea l'account di servizio:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. (Facoltativo) Assegna ruoli al tuo service account per concedere l'accesso alle risorse del tuo progetto Google Cloud. Per ulteriori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.

L'account di servizio viene visualizzato nella pagina degli account di servizio. Successivamente, crea una chiave privata per il service account.

Crea una chiave privata

Avviso: questo esempio utilizza una chiave del service account esportata per semplicità. L'esportazione di una chiave privata non è consigliata in produzione perché non deve essere archiviata in una posizione non sicura, ad esempio il controllo del codice sorgente.

Per scoprire di più sulle implementazioni sicure dei service account e sulle best practice, consulta Scegliere quando utilizzare i service account.

Per creare e scaricare una chiave privata per il service account, segui questi passaggi:

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Service account.

   Vai a Service account

2. Seleziona il tuo service account.
3. Fai clic su Chiavi > Aggiungi chiave > Crea nuova chiave.
4. Seleziona JSON, quindi fai clic su Crea.

   Una nuova coppia di chiavi pubblica/privata viene generata e scaricata sul tuo computer come nuovo file. Salva il file JSON scaricato come credentials.json nella tua directory di lavoro. Questo file è l'unica copia di questa chiave. Per informazioni su come archiviare la chiave in modo sicuro, consulta la sezione Gestione delle chiavi degli account di servizio.

5. Fai clic su Chiudi.

Per ulteriori informazioni sugli account di servizio, consulta la sezione account di servizio nella documentazione di Google Cloud IAM.

Distribuisci l'agente AI ADK di LLM Auditor

1. Se non l'hai ancora fatto, autenticati con il tuo account Google Cloud e configura Google Cloud CLI in modo da utilizzare il tuo progetto Google Cloud.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   Sostituisci PROJECT_ID con l'ID del progetto Cloud che hai creato.

2. Scarica questo repository GitHub

   Scarica

3. Nell'ambiente di sviluppo locale preferito, estrai il file di archivio scaricato e apri la directory adk-samples/python/agents/llm-auditor.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. Crea un nuovo bucket Cloud Storage dedicato all'agente ADK.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   Sostituisci quanto segue:

   1. CLOUD_STORAGE_BUCKET_NAME con un nome di bucket univoco che vuoi utilizzare.
   2. PROJECT_ID: l'ID del progetto Cloud che hai creato.
   3. PROJECT_LOCATION con la posizione del progetto Cloud che hai creato.

5. Impostare le seguenti variabili di ambiente:

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   Sostituisci quanto segue:

   1. CLOUD_STORAGE_BUCKET_NAME con il nome del bucket che hai creato.
   2. PROJECT_ID: l'ID del progetto Cloud che hai creato.
   3. PROJECT_LOCATION con la posizione del progetto Cloud che hai creato.

6. Installa ed esegui il deployment dell'agente ADK dall'ambiente virtuale.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. Recupera l'ID agente: ti servirà in seguito per configurare la funzione personalizzata.

   python3 deployment/deploy.py --list

Rivedi il codice campione

Se vuoi, prima di creare il nuovo foglio di lavoro, prenditi un momento per esaminare e familiarizzare con il codice di esempio ospitato su GitHub.

Visualizza su GitHub

Creare e configurare in un nuovo foglio di lavoro

1. Fai clic sul pulsante seguente e crea una copia completa del foglio di lavoro Google Sheets di esempio, incluso il progetto Apps Script associato al contenitore.

   Copiare il foglio di lavoro Fogli Google

2. Nel foglio di calcolo appena creato, vai su Estensioni > Apps Script.

3. Nel progetto Apps Script, vai a Impostazioni progetto, fai clic su Modifica proprietà script, poi su Aggiungi proprietà script per aggiungere le seguenti proprietà script:

   1. LOCATION con la posizione del progetto Google Cloud creato nei passaggi precedenti, ad esempio us-central1.
   2. GEMINI_MODEL_ID con il modello Gemini che vuoi utilizzare, ad esempio gemini-2.5-flash-lite.
   3. REASONING_ENGINE_ID con l'ID dell'agente ADK LLM Auditor di cui è stato eseguito il deployment nei passaggi precedenti, ad esempio 1234567890.
   4. SERVICE_ACCOUNT_KEY con la chiave JSON dall'account di servizio scaricato nei passaggi precedenti, ad esempio { ... }.

4. Fai clic su Salva proprietà script

Testare la funzione personalizzata

1. Vai al foglio di calcolo appena creato.
2. Modificare le istruzioni nella colonna A.
3. Le formule nella colonna B vengono eseguite e quindi visualizzano i risultati del fact-checking.

Esegui la pulizia

Per evitare di incorrere in addebiti sul tuo account Google Cloud per le risorse utilizzate in questo tutorial, ti consigliamo di eliminare il progetto Cloud.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per questo tutorial, eliminandolo eliminerai anche qualsiasi altro lavoro svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL su appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più tutorial e guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. Nella console Google Cloud, vai alla pagina Gestisci risorse. Fai clic su Menu > IAM e amministrazione > Gestisci risorse.

   Vai a Resource Manager

2. Nell'elenco dei progetti, seleziona quello da eliminare e fai clic su Elimina .
3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

Passaggi successivi

• Pianificare i viaggi con un agente AI accessibile in Google Workspace
• Funzioni personalizzate in Fogli Google
• Estensione di Fogli Google