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

Livello di codifica: Avanzato
Durata: 30 minuti
Tipo di progetto: Funzione personalizzata

Panoramica

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

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

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

Obiettivi

• Comprendere cosa fa la soluzione.
• Comprendere come viene implementata la soluzione.
• Eseguire il deployment dell'agente Vertex AI.
• Configurare lo script.
• Eseguire 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 risposta utilizzando le informazioni web più recenti e restituisce il risultato nel formato di cui hai bisogno:

• 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.
• Ragionamento: Agente AI LLM Auditor ADK (esempio Python).
• Formattazione dell'output: Modello Gemini.

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

Architettura

Il seguente diagramma mostra l'architettura delle risorse 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 ADK LLM Auditor

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

Prepara l'ambiente

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

Creare un progetto Google Cloud

Console Google Cloud

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

   Vai a Crea un progetto

2. Nel campo 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 la durata del progetto.

3. Nel campo Località, fai clic su Sfoglia per visualizzare le potenziali località per il tuo progetto. Quindi, fai clic su Seleziona.
4. Fai clic su Crea. La console Google Cloud passa alla pagina Dashboard e il progetto viene creato in 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 gcloud CLI 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.

Abilitare la fatturazione per il progetto Cloud

Console Google Cloud

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

   Vai alla 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 (more_vert), fai clic su Modifica fatturazione e scegli l' account di fatturazione Cloud.
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 abilitare la fatturazione.
   • BILLING_ACCOUNT_ID è l'ID account di fatturazione da collegare al progetto Google Cloud.

Abilitare l'API Vertex AI

Creare un account di servizio nella console Google Cloud

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

Console Google Cloud

1. Nella console Google Cloud, vai a Menu menu > IAM e amministrazione > Account di servizio.

   Vai a Service account

2. Fai clic su Crea account di servizio.
3. Compila i dettagli dell'account di servizio, quindi fai clic su Crea e continua.
4. (Facoltativo) Assegna ruoli al tuo account di servizio per concedere l'accesso alle risorse del tuo progetto Google Cloud. Per maggiori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.
5. Fai clic su Continua.
6. (Facoltativo) Inserisci utenti o gruppi che possono gestire ed eseguire azioni con questo service account. Per maggiori dettagli, consulta Gestire la simulazione dell'identità dei service account.
7. Fai clic su Fine. Prendi nota dell'indirizzo email dell'account di servizio.

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 account di servizio per concedere l'accesso alle risorse del tuo progetto Google Cloud. Per maggiori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.

L'account di servizio viene visualizzato nella pagina degli account di servizio. Poi, crea una chiave privata per l'account di servizio.

Crea una chiave privata

Per creare e scaricare una chiave privata per l'account di servizio, segui questi passaggi:

1. Nella console Google Cloud, vai a Menu menu > IAM e amministrazione > Account di servizio.

   Vai a Service account

2. Seleziona il tuo account di servizio.
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 Gestire le chiavi degli account di servizio.

5. Fai clic su Chiudi.

Per saperne di più sugli account di servizio, consulta gli account di servizio nella documentazione di Google Cloud IAM.

Eseguire il deployment dell'agente AI ADK LLM Auditor

1. Se non l'hai già fatto, autenticati con il tuo account Google Cloud e configura Google Cloud CLI in modo che utilizzi il tuo progetto 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 che preferisci, 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 bucket univoco che vuoi utilizzare.
   2. PROJECT_ID con l'ID del progetto Cloud che hai creato.
   3. PROJECT_LOCATION con la località del progetto Cloud che hai creato.

5. Imposta 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 con l'ID del progetto Cloud che hai creato.
   3. PROJECT_LOCATION con la località 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 un secondo momento per configurare la funzione personalizzata.

   python3 deployment/deploy.py --list

Rivedere il codice campione

(Facoltativo) Prima di creare il nuovo foglio di lavoro, prenditi un momento per esaminare e familiarizzare con il codice campione ospitato su GitHub.

Visualizza su GitHub

Creare e configurare in un nuovo foglio di lavoro

1. Per creare una copia completa del foglio di lavoro di esempio di Fogli, incluso il progetto Apps Script associato al container, fai clic sul seguente pulsante:

   Copia il foglio di lavoro di Fogli Google

2. Nel foglio di lavoro appena creato, vai a Estensioni > Apps Script.

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

   1. LOCATION con la località 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 del service account scaricata nei passaggi precedenti, ad esempio { ... }.

4. Fai clic su Salva proprietà script.

Testare la funzione personalizzata

1. Vai al foglio di lavoro appena creato.
2. Modifica le istruzioni nella colonna A.
3. Le formule nella colonna B vengono eseguite e poi visualizzano i risultati del controllo dei fatti.

Libera spazio

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, ti consigliamo di eliminare il progetto Cloud.

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

   Vai a Resource Manager

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina delete.
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
• Creare agenti Gemini Enterprise strettamente integrati con i datastore, le API e i componenti aggiuntivi di Workspace
• Creare agenti Vertex AI strettamente integrati con i datastore, le API e i componenti aggiuntivi di Workspace
• Funzioni personalizzate in Fogli
• Estendere Fogli