Agentic Workflows in Google Workspace: crea un agente Google Docs con ADK

1. Introduzione

Google Workspace è dove si lavora. Dalla stesura di report in Documenti all'analisi dei dati in Fogli e alla collaborazione in Gmail e Meet.

Ora immagina se Documenti, Fogli e Gmail non fossero solo strumenti, ma collaboratori.

Con l'aiuto di Agent Development Kit (ADK) e Agent Engine di Vertex AI di Google, non si tratta più solo di un'idea, ma utilizzeremo questi framework per creare un agente intelligente, eseguirne il deployment su larga scala e integrarlo perfettamente nei nostri strumenti Google Workspace, inaugurando una nuova era di produttività basata sugli agenti.

In questo codelab, utilizzerai un approccio passo passo come segue:

1. Sviluppa l'agente AI Facts Checker utilizzando Agent Development Kit.
2. Esegui il deployment dell'agente in Agent Engine, un ambiente completamente gestito per l'esecuzione degli agenti su larga scala.
3. Integra questo agente in Documenti Google per eseguire il fact checking del testo nel documento.

Di seguito è riportato un diagramma concettuale che spiega come funziona la soluzione finale:

Ecco un output finale di come funziona l'agente Fact Check all'interno di un documento Google, in cui era presente un testo originale contenente alcune affermazioni e viene eseguito un fact checking per ciascuna delle affermazioni nel documento. L'output delimitato nella casella con l'angolo rosso è l'output dell'agente.

Attività previste

• Progetta, crea e implementa un agente che esegua il fact checking all'interno di un documento Google.

Cosa imparerai a fare

• Sviluppa un agente utilizzando Agent Development Kit (ADK).
• Testa l'agente localmente ed esegui il deployment su Agent Engine.
• Integra l'agente in un documento Google Workspace (documento Google).

Che cosa ti serve

• Browser web Chrome
• Un account Gmail
• Un progetto cloud con fatturazione abilitata

Questo codelab, progettato per sviluppatori di tutti i livelli (inclusi i principianti), utilizza Python e Apps Script nel suo codice campione. Tuttavia, la conoscenza di questi linguaggi di programmazione non è un prerequisito e una capacità di lettura di base del codice sarà sufficiente per comprendere i concetti presentati.

2. Prima di iniziare

Crea un progetto

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto .

Per i crediti Google Cloud:se vuoi ricevere crediti Google Cloud per iniziare, utilizza questo link per riscattare i crediti che ti aiuteranno a completare il lab. Per riscattarlo, segui le istruzioni riportate qui.

3. Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud precaricato con bq. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.

4. Una volta eseguita la connessione a Cloud Shell, verifica di essere già autenticato e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:

gcloud auth list

5. Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.

gcloud config list project

6. Se il progetto non è impostato, utilizza il seguente comando per impostarlo:

gcloud config set project <YOUR_PROJECT_ID>

7. Abilita le API richieste tramite il comando mostrato di seguito. L'operazione potrebbe richiedere alcuni minuti.

gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       discoveryengine.googleapis.com

Se il comando viene eseguito correttamente, dovresti visualizzare un messaggio simile a quello mostrato di seguito:

Operation "operations/..." finished successfully.

Se manca un'API, puoi sempre abilitarla durante l'implementazione.

Consulta la documentazione per i comandi e l'utilizzo di gcloud.

3. Creazione dell'agente ADK

Creiamo l'agente ADK (Document Fact Checker Agent), un revisore basato sull'AI che verifica i fatti nel testo, ispirato alla funzione personalizzata di fact checking di Google esempio. A differenza dell'approccio in un solo passaggio dell'esempio, il nostro agente utilizza un ragionamento in più passaggi per estrarre le rivendicazioni, verificarle con google_search e restituire JSON strutturato.

Passaggio 1 : installa l'Agent Development Kit

Apri una nuova scheda del terminale in Cloud Shell e crea una cartella denominata my-agents nel seguente modo. Vai anche alla cartella my-agents.

mkdir workspace-agents
cd workspace-agents

Ora creiamo un ambiente Python virtuale utilizzando venv come segue:

python -m venv .venv

Attiva l'ambiente virtuale come segue:

source .venv/bin/activate

Installa l'ADK come segue:

pip install google-adk

Ora potrai richiamare l'utilità adk nel seguente modo.

adk

Verrà visualizzato un elenco di comandi.

$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...

  Agent Development Kit CLI tools.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  api_server   Starts a FastAPI server for agents.
  conformance  Conformance testing tools for ADK.
  create       Creates a new app in the current folder with prepopulated agent template.
  deploy       Deploys agent to hosted environments.
  eval         Evaluates an agent given the eval sets.
  eval_set     Manage Eval Sets.
  run          Runs an interactive CLI for a certain agent.
  web          Starts a FastAPI server with Web UI for agents.

Passaggio 2 : sviluppa l'agente di verifica dei fatti dei documenti utilizzando l'ADK

Ora utilizzeremo adk per creare una struttura per il nostro agente tramite il comando adk create con un nome dell'app **(docfactcheckeragent)**come indicato di seguito.

adk create docfactcheckeragent

Segui i passaggi e seleziona quanto segue:

• Modello Gemini per la scelta di un modello per l'agente principale.
• Scegli Vertex AI per il backend.
• Verranno visualizzati l'ID progetto Google e la regione predefiniti. Seleziona il valore predefinito.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)

Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [YOUR_PROJECT_ID]: 
Enter Google Cloud region [us-central1]: 

Agent created in <YOUR_HOME_FOLDER>/workspace-agents/docfactcheckeragent:
- .env
- __init__.py
- agent.py

Osserva la cartella in cui sono stati creati un modello predefinito e i file richiesti per l'agente.

Il primo è il file .env. I cui contenuti sono mostrati di seguito:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

I valori indicano che utilizzeremo Gemini tramite Vertex AI insieme ai rispettivi valori per l'ID progetto Google Cloud e la posizione.

Poi c'è il file __init__.py che contrassegna la cartella come modulo e contiene una singola istruzione che importa l'agente dal file agent.py.

from . import agent

Infine, c'è il file agent.py. Dovrai sostituire i contenuti di questo file agent.py con il codice mostrato di seguito:

from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name='ai_auditor',
    model='gemini-2.5-flash',
    description="Fact-checks statements from a document and provides citations.",
    instruction="""
You are an AI Auditor specialized in factual verification and evidence-based reasoning.
Your goal is to analyze text from a Google Doc, identify verifiable factual claims, and produce a concise, source-backed audit report.

### 🔍 TASK FLOW

1. **Extract Claims**
   - Analyze the input text and identify factual claims that can be objectively verified.
   - A factual claim is any statement that can be proven true or false with external evidence.
   - Skip opinions, vague generalizations, or speculative language.
   - List each claim as a string in a JSON array.

2. **Verify Claims**
   - For each extracted claim:
     - Use the `google_search` tool to find relevant, credible results.
     - Evaluate at least the top 3 relevant URLs to determine the claim's accuracy.
     - Cross-check multiple sources when possible to ensure confidence.

3. **Classify Findings**
   - For each claim, determine one of the following verdicts:
     - ✅ **True:** Supported by multiple reputable sources.
     - ⚠️ **Misleading / Partially True:** Contains partially correct or context-dependent information.
     - ❌ **False:** Contradicted by credible evidence.
     - ❓ **Unverifiable:** Insufficient information to confirm or deny.
   - Provide a **confidence score (0–100)** reflecting the strength of evidence.

4. **Record Evidence**
   - For each claim, include:
     - The **verdict**
     - **Reasoning summary** (1–2 sentences)
     - **List of citation URLs** used for verification

5. **Summarize Results**
   - Compile a final report including:
     - Total number of claims analyzed
     - Distribution of verdicts (True / False / Misleading / Unverifiable)
     - Brief overall conclusion (e.g., "Most claims are accurate but some lack supporting evidence.")

### 🧾 OUTPUT FORMAT

Return your final response in structured JSON format as follows:

{
  "claims": [
    {
      "claim": "...",
      "verdict": "True | False | Misleading | Unverifiable",
      "confidence": 0-100,
      "reasoning": "...",
      "sources": ["https://...", "https://..."]
    }
  ],
  "summary": {
    "total_claims": X,
    "verdict_breakdown": {
      "True": X,
      "False": X,
      "Misleading": X,
      "Unverifiable": X
    },
    "overall_summary": "..."
  }
}

### 🧠 ADDITIONAL INSTRUCTIONS
- Always prefer authoritative domains (.gov, .edu, .org, or major media).
- Avoid low-quality or user-generated content as primary sources.
- Be concise, accurate, and transparent about uncertainty.
    """,
    tools=[google_search],  # Only use the search tool
)

I punti chiave del codice sorgente riportato sopra sono:

• Definiamo l'agente AI assegnandogli un nome, seguito dal modello, dalla descrizione e da un insieme di istruzioni molto dettagliato.
• Il set di istruzioni è la parte più importante che definisce esattamente come l'agente deve pensare e operare. Questa struttura rispecchia il modo in cui lavorano i fact-checker professionisti, trasformando l'AI in una pipeline di controllo autonoma.
• Una volta completata questa dichiarazione dell'agente, passiamo a concedere all'agente l'accesso alle informazioni del mondo reale tramite Google Search tool. Invece di fare affidamento su dati pre-addestrati, l'agente può eseguire ricerche in tempo reale, valutare i risultati e fornire citazioni aggiornate.

È questo che rende questo sistema autonomo: il modello non si limita a generare risposte, ma intraprende azioni (utilizzando strumenti) per verificare le informazioni.

Passaggio 3 : testa l'agente localmente

Dalla finestra del terminale esistente, esegui il comando seguente. Assicurati di trovarti nella cartella principale (workspace-agents) contenente la cartella docfactcheckeragent.

adk web

Di seguito è riportato un esempio di esecuzione:

INFO:     Started server process [1478]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Fai clic sull'ultimo link per visualizzare una console web per testare l'agente. La nostra prima interazione è fondamentale: capire cosa può fare l'agente. In questo modo, viene testata la capacità dell'agente di riassumere le sue description e instruction text.

L'agente fornisce un riepilogo conciso delle sue capacità, basato sulla descrizione e sul set di istruzioni.

Forniamo poi due istruzioni (The sky is blue due to Rayleigh scattering. The Earth is flat.) e il modello esegue correttamente l'audit dei contenuti e restituisce una risposta JSON ben strutturata.

Dietro le quinte:

• Lo strumento google_search recupera pagine pertinenti dal web.
• Il modello Gemini 2.5 Flash analizza questi snippet e classifica la veridicità.
• ADK gestisce l'orchestrazione del ragionamento e garantisce che venga seguita la logica passo passo.

Questa fase di test locale consente di convalidare il flusso di lavoro del nostro agente prima di eseguirne il deployment su Vertex AI Agent Engine, dove può essere connesso a strumenti Google Workspace come Documenti o Fogli.

In sintesi, abbiamo creato un potente AI Auditor Agent utilizzando Google Agent Development Kit (ADK). Il nostro agente è in grado di leggere il testo, identificare le affermazioni fattuali, cercare fonti credibili (utilizzando lo strumento google_search) e restituire un verdetto chiaro.

Abbiamo creato e testato tutto localmente tramite l'interfaccia web dell'ADK e abbiamo visto come l'agente ha analizzato un'affermazione come:

The sky is blue due to Rayleigh scattering. The Earth is flat.

L'agente ha verificato una richiesta come true e ha segnalato l'altra come false, una piccola ma appropriata prova che la nostra configurazione locale funziona perfettamente.

Ora è il momento di fare il passo successivo: passare dal locale al cloud. Vediamo come fare.

4. Deployment dell'agente in Vertex AI Agent Engine

Un agente reale non è solo qualcosa che testi sul laptop, ma qualcosa che puoi eseguire su larga scala, integrare con altri sistemi ed eseguire il deployment per la produzione nelle tue app.

Perché eseguire il deployment?

Ecco alcuni buoni motivi per eseguire il deployment degli agenti nel cloud.

• Scalabilità: gestisci richieste di volumi elevati senza limiti di runtime locali.
• Affidabilità: monitoraggio e scalabilità automatica integrati, con correzioni come l'aggiornamento della configurazione dello strumento ADK del 18 ottobre 2025.
• Pronto per l'integrazione: espone un endpoint API per chiamate Workspace senza interruzioni.

Perché Vertex AI Agent Engine?

Considera Vertex AI Agent Engine come la sede dei tuoi agenti ADK di cui è stato eseguito il deployment: un ambiente gestito creato per affidabilità, scalabilità e integrazione.

Fornisce all'agente:

• Stato e memoria persistenti
• Esecuzione di strumenti integrati (ad es. Ricerca Google, modelli Vertex AI)
• Proteggere gli endpoint API per le chiamate esterne
• Logging e osservabilità tramite Cloud Logging
• Supporto nativo per l'orchestrazione multi-agente

In breve, scrivi una volta con l'ADK e poi lo aumenti di scala utilizzando Agent Engine.

Passaggio 1 : configurazione per l'implementazione

Prima di eseguire il deployment dell'agente Vertex AI Agent Engine, dobbiamo fare alcune cose. Il processo di deployment richiede la creazione di un bucket Google Cloud Storage per gli artefatti dell'agente e dobbiamo anche fornire un file requirements.txt, in modo che tutte le dipendenze necessarie per eseguire il codice dell'agente siano disponibili per l'ambiente di runtime di Agent Engine.

Nel terminale Cloud Shell, esegui il comando seguente per creare un bucket (ricorda di sostituire YOUR_BUCKET_NAME, YOUR_PROJECT_ID e YOUR_PROJECT_REGION con valori effettivi specifici per il tuo progetto):

gcloud storage buckets create gs://YOUR_BUCKET_NAME \
                              --project=YOUR_PROJECT_ID \
                              --location=YOUR_PROJECT_REGION

Poi, crea il seguente file requirements.txt nella cartella principale (workspace-agents), i cui contenuti sono mostrati di seguito:

google-cloud-aiplatform
google-adk
requests

Passaggio 2 : esegui il deployment dell'agente

Il passaggio successivo consiste nel deployment dell'agente in Vertex AI Agent Engine utilizzando il comando adk deploy.

adk deploy agent_engine \
    --project=YOUR_PROJECT_ID \
    --region=YOUR_PROJECT_REGION \
    --display_name "Doc Fact Checker" \
    --staging_bucket gs://YOUR_BUCKET_NAME \
    --requirements_file requirements.txt \
    docfactcheckeragent/

In questo modo dovrebbe avviarsi un processo per il deployment dell'agente in Agent Engine. La procedura richiede tempo e può durare circa 5 minuti. A livello generale, ecco cosa succede:

1. Inizia la creazione dell'agente: la CLI ADK pacchettizza il codice, lo carica nel bucket Cloud Storage e attiva Vertex AI per creare una nuova istanza di Agent Engine.
2. Ti viene fornito un link ai log, dove puoi visualizzare Esplora log di Cloud Logging per il tuo progetto. Fai clic per visualizzare l'avanzamento dettagliato, inclusi i passaggi di configurazione, l'installazione delle dipendenze e l'inizializzazione del modello. Se si verifica un problema (ad esempio una dipendenza mancante o un problema di autorizzazione), qui troverai il messaggio di errore.
3. Messaggio di completamento: una volta completata l'implementazione, nel terminale verrà visualizzato un messaggio di conferma con l'ID del motore di ragionamento. Di seguito è riportato un esempio:

AgentEngine created. Resource name: projects/SOME_ID/locations/REGION/reasoningEngines/SOME_ID

Passaggio 3 : verifica l'agente nella console Cloud (Agent Engine)

Al termine del deployment, vai alla sezione Vertex AI → Agent Engine della console Google Cloud. Dovresti vedere l'agente di cui hai eseguito il deployment elencato nella console come mostrato di seguito:

🎉 Fatto! L'agente è ora attivo su Vertex AI e pronto per essere integrato in Google Workspace o testato direttamente.

Passaggio 4 : testa l'agente di deployment

Congratulazioni. Il tuo agente è ora attivo su Vertex AI Agent Engine. Il passaggio successivo consiste nel verificare che sia stato eseguito il deployment correttamente e che risponda alle richieste.

Esistono diversi modi per farlo, a seconda delle tue preferenze:

1. Tramite la console Google Cloud: un'interfaccia visiva per visualizzare, gestire e testare direttamente gli agenti di cui è stato eseguito il deployment.
2. Utilizzo dell'API REST (cURL): ideale per gli sviluppatori che vogliono inviare manualmente le richieste ed esaminare le risposte.
3. Con l'SDK Vertex AI per Python: un'opzione più programmatica per integrare i test nel flusso di lavoro di sviluppo.

Ogni approccio ti offre informazioni sul comportamento dell'agente una volta implementato, ad esempio se elabora query, gestisce sessioni o restituisce risposte. Per esplorare passaggi dettagliati, esempi e configurazioni avanzate per ogni metodo, consulta la documentazione ufficiale qui.

Il tuo AI Auditor è ora un agente basato sul cloud, di cui è stato eseguito il deployment in Vertex AI Agent Engine, pronto per il fact-checking su larga scala con google_search. Si è trasformato in un compagno di squadra digitale affidabile e basato su API, che produce JSON come:

{ "claims": [{"claim": "The sky is blue...", "verdict": "True", "confidence": 95}] }

Lo proveremo direttamente nella sezione successiva, dove integreremo l'agente in un documento Google e convalideremo i fatti riportati nel documento.

5. Integrare l'agente di controllo dei fatti in Documenti Google

In questa sezione, collegheremo tutto, portando l'agente di cui è stato eseguito il deployment in Documenti Google. Con poche righe di Apps Script, trasformerai un documento Google standard in un editor basato sull'AI in grado di analizzare e verificare automaticamente i contenuti utilizzando l'agente di cui hai eseguito il deployment.

Passaggio 1: configura l'ambiente Documenti Google

Inizia aprendo un documento Google nuovo o esistente (docs.new).

Il documento Google che utilizziamo per questo tutorial contiene i seguenti contenuti (puoi utilizzare questi o i tuoi contenuti che prevedi di sottoporre a fact checking):

Climate change is mainly caused by solar activity cycles, not human activities. The Earth's temperature has not increased significantly in the last 100 years. Wind energy now produces more electricity than coal in every country in Europe. In 2015, nearly all world nations signed the Paris Agreement to limit global warming.

Passaggio 2: configura il progetto e i file Apps Script

Per questa configurazione, nel tuo progetto Apps Script sono necessari due file:

1. AIVertex.gs: gestisce tutte le comunicazioni con Vertex AI e l'agente ADK.
2. Code.gs: controlla l'interfaccia, i menu e le azioni sui documenti di Documenti Google.

Nel menu, vai a Extensions -> Apps Script per aprire l'editor. Utilizzeremo questo spazio per connetterci all'agente ADK di cui è stato eseguito il deployment. Troverai un file Code.gs già creato e dovrai sostituire il suo contenuto con il codice Code.gs fornito nella sezione successiva.

Vediamoli uno per uno.

AIVertex.gs

Crea un nuovo file tramite il segno + accanto alla sezione File a sinistra, selezionalo come Script e copia i seguenti contenuti.

const LOCATION = PropertiesService.getScriptProperties().getProperty('LOCATION');
const GEMINI_MODEL_ID = PropertiesService.getScriptProperties().getProperty('GEMINI_MODEL_ID');
const REASONING_ENGINE_ID = PropertiesService.getScriptProperties().getProperty('REASONING_ENGINE_ID');
const SERVICE_ACCOUNT_KEY = PropertiesService.getScriptProperties().getProperty('SERVICE_ACCOUNT_KEY');

const credentials = credentialsForVertexAI();

/**
 * @param {string} statement The statement to fact-check.
 */
function requestLlmAuditorAdkAiAgent(statement) {
  return UrlFetchApp.fetch(
    `https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${credentials.projectId}/locations/${LOCATION}/reasoningEngines/${REASONING_ENGINE_ID}:streamQuery?alt=sse`,
    {
      method: 'post',
      headers: { 'Authorization': `Bearer ${credentials.accessToken}` },
      contentType: 'application/json',
      muteHttpExceptions: true,
      payload: JSON.stringify({
        "class_method": "async_stream_query",
        "input": {
          "user_id": "google_sheets_custom_function_fact_check",
          "message": statement,
        }
      })
    }
  ).getContentText();
}

/**
 * @param {string} prompt The Gemini prompt to use.
 */
function requestOutputFormatting(prompt) {
  const response = UrlFetchApp.fetch(
    `https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${credentials.projectId}/locations/${LOCATION}/publishers/google/models/${GEMINI_MODEL_ID}:generateContent`,
    {
      method: 'post',
      headers: { 'Authorization': `Bearer ${credentials.accessToken}` },
      contentType: 'application/json',
      muteHttpExceptions: true,
      payload: JSON.stringify({
        "contents": [{
          "role": "user",
          "parts": [{ "text": prompt }]
        }],
        "generationConfig": { "temperature": 0.1, "maxOutputTokens": 2048 },
        "safetySettings": [
          {
            "category": "HARM_CATEGORY_HARASSMENT",
            "threshold": "BLOCK_NONE"
          },
          {
            "category": "HARM_CATEGORY_HATE_SPEECH",
            "threshold": "BLOCK_NONE"
          },
          {
            "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
            "threshold": "BLOCK_NONE"
          },
          {
            "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
            "threshold": "BLOCK_NONE"
          }
        ]
      })
    }
  );
  return JSON.parse(response).candidates[0].content.parts[0].text
}

/**
 * Gets credentials required to call Vertex API using a Service Account.
 * Requires use of Service Account Key stored with project.
 * 
 * @return {!Object} Containing the Google Cloud project ID and the access token.
 */
function credentialsForVertexAI() {
  const credentials = SERVICE_ACCOUNT_KEY;
  if (!credentials) {
    throw new Error("service_account_key script property must be set.");
  }

  const parsedCredentials = JSON.parse(credentials);

  const service = OAuth2.createService("Vertex")
    .setTokenUrl('https://oauth2.googleapis.com/token')
    .setPrivateKey(parsedCredentials['private_key'])
    .setIssuer(parsedCredentials['client_email'])
    .setPropertyStore(PropertiesService.getScriptProperties())
    .setScope("https://www.googleapis.com/auth/cloud-platform");
  return {
    projectId: parsedCredentials['project_id'],
    accessToken: service.getAccessToken(),
  }
}

Ricorda di salvare il file.

Questo file esegue le seguenti operazioni:

• Esegue l'autenticazione in modo sicuro su Vertex AI utilizzando una chiave del service account. Invoca l'agente ADK di cui è stato eseguito il deployment per analizzare o verificare i fatti nel testo del documento.
• Utilizza Gemini per la formattazione delle risposte intelligenti , rendendo i risultati leggibili.

Code.gs

/**
 * Adds a custom menu in Google Docs to run the AI Audit directly.
 */
function onOpen() {
  DocumentApp.getUi()
    .createMenu('AI Audit Tools')
    .addItem('Run AI Audit', 'runAuditAndInsert')
    .addToUi();
}

/**
 * Returns the entire text content of the document.
 */
function getDocumentText() {
  const doc = DocumentApp.getActiveDocument();
  const body = doc.getBody();
  let text = body.getText();
  return text.trim();
}

/**
 * Runs the AI Audit and inserts the result as text at the end of the document.
 */
function runAuditAndInsert() {
  const docText = getDocumentText();
  const result = runAudit(docText);

  if (result) {
    const doc = DocumentApp.getActiveDocument();
    const body = doc.getBody();
    // Append the audit result as a new paragraph at the end of the document
    body.appendParagraph('AI Audit Result: ' + result);
  }
}

/**
 * Runs the AI Audit using ADK Agent and Gemini formatting.
 */
function runAudit(docText) {
  console.log('[INFO] Starting AI audit process...');
  if (!docText) {
    console.log('[WARN] No text in document.');
    return '⚠️ The document is empty. Please add some text to audit.';
  }

  // Check for excessive document length to avoid token limits
  if (docText.length > 10000) {
    console.log('[WARN] Document too long.');
    return '⚠️ Document exceeds 10,000 characters. Please shorten the text.';
  }

  console.log('[STEP] Sending text to ADK Agent...');
  const rawAudit = requestLlmAuditorAdkAiAgent(docText);

  // Check if rawAudit is an error message
  if (rawAudit.startsWith('ERROR:')) {
    console.error('[ERROR] ADK Agent returned error:', rawAudit);
    return rawAudit;
  }

  console.log('[STEP] Formatting AI response...');
  let formatted;
  try {
    formatted = requestOutputFormatting(
      `Here is a fact-checking result: ${rawAudit}.
       Summarize it. Keep the main verdict and reasoning. Remove markdown and make it concise.`
    );
  } catch (error) {
    console.error('[ERROR] Formatting failed:', error.toString());
    return `ERROR: Failed to format audit result - ${error.toString()}`;
  }

  console.log('[SUCCESS] Audit completed successfully.');
  console.log('[RESULT] Final Output:', formatted);
  return formatted;
}

Questo file collega l'interfaccia utente di Documenti alla logica dell'ADK riportata sopra. Consente di attivare il controllo direttamente da un menu personalizzato di Documenti. A livello generale, esegue le seguenti operazioni:

• Aggiunge un menu personalizzato in Documenti Google chiamato Strumenti di controllo AI.
• Acquisisce il testo del documento e lo invia all'agente ADK per l'analisi.
• Visualizza i risultati dell'audit generati dall'AI nel documento.

Passaggio 3 : crea l'account di servizio

Quando integri la funzionalità di chiamata dell'agente in un documento Google, dobbiamo fornire un'identità al documento Google, in modo che abbia il ruolo corretto per richiamare l'agente distribuito in Agent Engine. A questo scopo, utilizzeremo un service account con il ruolo corretto: roles/aiplatform.user.

In Cloud Shell, esegui il seguente script, passo dopo passo:

export PROJECT_ID="YOUR_PROJECT_ID"
export SA_NAME="docfactcheckeragentsa"

gcloud iam service-accounts create $SA_NAME \
  --project=$PROJECT_ID \
  --display-name="Doc Fact Checker Agent Service Account"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountTokenCreator"

Verrà creato il service account con le autorizzazioni corrette.

Genereremo una chiave JSON per il service account. Questo è ciò che il tuo progetto Apps Script utilizzerà per l'autenticazione. I passaggi per ottenere la chiave sono:

1. Nella console Google Cloud, vai a IAM e amministrazione > Service account.
2. Fai clic sul service account specifico che hai appena creato.
3. Vai alla scheda Chiavi.
4. Fai clic su Aggiungi chiave → Crea nuova chiave.
5. Seleziona JSON, quindi fai clic su Crea.
6. Verrà scaricato automaticamente un file JSON, che dovrai conservare in un luogo sicuro. Incollerai i contenuti nelle proprietà dello script nella sezione successiva.

Passaggio 4 : aggiungi le proprietà dello script

Torna all'editor Apps Script in Documenti Google.

Per collegare lo script alle risorse di cui è stato eseguito il deployment, vai a Project Settings → Script Properties → Add Script Property.

Aggiungi quanto segue alle proprietà dello script:

1. LOCATION: la regione del deployment di Vertex AI. Ad es. us-central1
2. GEMINI_MODEL_ID: modello Gemini da utilizzare. Utilizza il valore: gemini-2.5-flash
3. REASONING_ENGINE_ID: l'ID agente ADK di cui è stato eseguito il deployment. Puoi ottenerlo dall'opzione Agent Engine nella console dell'agente specifico che hai implementato. Vedrai il nome di una risorsa per l'agente di cui è stato eseguito il deployment. L'ID agente è l'ultimo valore numerico nel nome della risorsa (ovvero RESOURCE_ID). Ad esempio, projects/SOME_ID/locations/REGION/reasoningEngines/RESOURCE_ID
4. SERVICE_ACCOUNT_KEY: copia l'intero contenuto della chiave JSON scaricata per l'account di servizio creato nel passaggio precedente.

Fai clic su Salva proprietà script.

Passaggio 5 : aggiungi la libreria OAuth2

Il nostro progetto Apps Script ha bisogno della libreria OAuth2 per autenticare le chiamate API.

Per aggiungerlo:

1. Vai a Services → Libraries
2. Fai clic su Add a Library.
3. Inserisci l'ID script: 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

Passaggio 6 : testa l'agente di controllo dei fatti in Documenti Google

Siamo all'ultimo passaggio per testare l'agente in Documenti Google. Per farlo:

1. Nell'editor di Apps Script, esegui la funzione onOpen() una volta. Verrà aggiunto un nuovo menu Strumenti di controllo AI in Documenti Google.
2. Torna al documento. Nel menu principale vedrai una voce di menu aggiuntiva intitolata AI Audit Tools. Fai clic su questo pulsante e poi su Run AI Audit.

Ecco un esempio di esecuzione:

6. Esegui la pulizia

Per evitare addebiti continui al tuo account Google Cloud, è importante eliminare le risorse che abbiamo creato durante questo workshop.

Se non hai più bisogno che l'agente venga implementato in Agent Engine, puoi eliminarlo seguendo i passaggi riportati di seguito:

1. Vai alla pagina Vertex AI Agent Engine nella console Google Cloud.
2. Individua l'agente che vuoi eliminare dall'elenco degli agenti di cui è stato eseguito il deployment.
3. Fai clic sul menu con tre puntini (altre azioni) accanto al nome dell'agente.
4. Seleziona Elimina dal menu a discesa.
5. Conferma l'eliminazione facendo clic su Elimina agente nella finestra di dialogo di conferma.

Come best practice, elimina anche il service account.

gcloud iam service-accounts delete ${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

7. Complimenti

Ora hai eseguito il deployment dell'agente AI, lo hai collegato a Documenti Google e lo hai visto in azione: analizza, ragiona e riassume direttamente dove si trovano i tuoi contenuti. Quello che abbiamo creato qui non è solo una demo autonoma. È la base per una collaborazione intelligente e guidata dagli agenti all'interno di Google Workspace.

Combinando le funzionalità di ragionamento di ADK con i modelli generativi di Gemini, abbiamo trasformato Google Docs in un assistente vivo e pensante, in grado di leggere, controllare e perfezionare il testo con il contesto.

Lo stesso modello si estende naturalmente a Fogli, Presentazioni, Drive e Gmail. Immagina agenti che:

• Controllare i dati finanziari e segnalare le incongruenze in Fogli
• Generare automaticamente pitch deck e riepiloghi in Presentazioni
• Etichettare e organizzare i documenti in modo intelligente in Drive
• Oppure, puoi creare bozze di email e verificarne l'accuratezza direttamente in Gmail

Questa dimostrazione pone le basi per la creazione di flussi di lavoro agentici che si integrano perfettamente negli strumenti Workspace che utilizzi quotidianamente, trasformando i documenti statici in collaboratori AI dinamici.

Documenti di riferimento

• Agent Development Kit
• Motore agente