Workflows agentiques dans Google Workspace : créer un agent Google Docs avec ADK

1. Introduction

Google Workspace est l'endroit où le travail se fait. Rédigez des rapports dans Docs, analysez des données dans Sheets et collaborez dans Gmail et Meet.

Imaginez maintenant que vos outils Docs, Sheets et Gmail ne soient pas de simples outils, mais des collaborateurs.

Grâce à l'Agent Development Kit (ADK) de Google et à l'Agent Engine de Vertex AI, ce n'est plus seulement une idée. Nous allons utiliser ces frameworks pour créer un agent intelligent, le déployer à grande échelle et l'intégrer de manière transparente à nos outils Google Workspace, ouvrant ainsi une nouvelle ère de productivité agentique.

Dans cet atelier de programmation, vous allez suivre une approche pas à pas comme suit :

1. Développez l'agent de vérification des faits par IA à l'aide d'Agent Development Kit.
2. Déployez l'agent dans Agent Engine, un environnement entièrement géré pour exécuter des agents à grande échelle.
3. Intègre cet agent à Google Docs pour vérifier les faits du texte du document.

Vous trouverez ci-dessous un schéma conceptuel expliquant le fonctionnement de la solution finale :

Voici un exemple de résultat final montrant comment l'agent Fact Check fonctionne dans un document Google Docs. Le texte d'origine contient des affirmations, et l'agent effectue une vérification des faits pour chacune d'elles. La limite de sortie dans la zone avec le coin rouge est la sortie de l'agent.

Objectifs de l'atelier

• Concevez, créez et déployez un agent qui effectuera du fact-checking dans un document Google Docs.

Points abordés

• Développez un agent à l'aide d'Agent Development Kit (AK).
• Testez l'agent localement et déployez-le sur Agent Engine.
• Intégrez l'agent dans un document Google Workspace (Google Docs).

Prérequis

• Navigateur Web Chrome
• Un compte Gmail
• Un projet Cloud pour lequel la facturation est activée

Cet atelier de programmation, conçu pour les développeurs de tous niveaux (y compris les débutants), utilise Python et Apps Script dans son exemple de code. Toutefois, la connaissance de ces langages de programmation n'est pas un prérequis. Une capacité de lecture de code de base suffira à comprendre les concepts présentés.

2. Avant de commencer

Créer un projet

1. Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
2. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet .

Pour les crédits Google Cloud : si vous souhaitez obtenir des crédits Google Cloud pour vous aider à vous lancer, utilisez ce lien pour les échanger. Ils vous aideront à terminer l'atelier. Pour l'utiliser, suivez les instructions ici.

3. Vous allez utiliser Cloud Shell, un environnement de ligne de commande exécuté dans Google Cloud et fourni avec bq. Cliquez sur "Activer Cloud Shell" en haut de la console Google Cloud.

4. Une fois connecté à Cloud Shell, vérifiez que vous êtes déjà authentifié et que le projet est défini sur votre ID de projet à l'aide de la commande suivante :

gcloud auth list

5. Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet.

gcloud config list project

6. Si votre projet n'est pas défini, utilisez la commande suivante pour le définir :

gcloud config set project <YOUR_PROJECT_ID>

7. Activez les API requises à l'aide de la commande ci-dessous. Cette opération peut prendre quelques minutes. Veuillez patienter.

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

Si la commande s'exécute correctement, un message semblable à celui ci-dessous s'affiche :

Operation "operations/..." finished successfully.

Si vous oubliez d'activer une API, vous pourrez toujours le faire au cours de l'implémentation.

Consultez la documentation pour connaître les commandes gcloud ainsi que leur utilisation.

3. Créer l'agent ADK

Créons l'agent ADK (Document Fact Checker Agent), un auditeur basé sur l'IA qui vérifie les faits dans le texte, inspiré de l'exemple de fonction personnalisée Fact-Check de Google. Contrairement à l'approche en une seule étape de l'exemple, notre agent utilise un raisonnement en plusieurs étapes pour extraire les affirmations, les vérifier avec google_search et générer un JSON structuré.

Étape 1 : Installez Agent Development Kit

Ouvrez un nouvel onglet de terminal dans Cloud Shell et créez un dossier nommé my-agents comme suit. Accédez également au dossier my-agents.

mkdir workspace-agents
cd workspace-agents

Nous allons maintenant créer un environnement Python virtuel à l'aide de venv comme suit :

python -m venv .venv

Activez l'environnement virtuel comme suit :

source .venv/bin/activate

Installez l'ADK comme suit :

pip install google-adk

Vous pouvez désormais appeler l'utilitaire adk comme suit.

adk

Une liste de commandes s'affiche.

$ 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.

Étape 2 : Développez l'agent de vérification des faits dans les documents à l'aide d'ADK

Nous allons maintenant utiliser adk pour créer un scaffold pour notre agent à l'aide de la commande adk create avec le nom d'application **(docfactcheckeragent)**comme indiqué ci-dessous.

adk create docfactcheckeragent

Suivez les étapes et sélectionnez les éléments suivants :

• Modèle Gemini permettant de choisir un modèle pour l'agent racine.
• Choisissez Vertex AI pour le backend.
• Votre ID de projet et votre région Google par défaut s'affichent. Sélectionnez la valeur par défaut.

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

Observez le dossier dans lequel un modèle par défaut et les fichiers requis pour l'agent ont été créés.

Commençons par le fichier .env. Le contenu est présenté ci-dessous :

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

Les valeurs indiquent que nous utiliserons Gemini via Vertex AI, ainsi que les valeurs respectives pour l'ID et l'emplacement du projet Google Cloud.

Ensuite, nous avons le fichier __init__.py qui marque le dossier comme module et qui contient une seule instruction qui importe l'agent à partir du fichier agent.py.

from . import agent

Enfin, il y a le fichier agent.py. Vous devrez remplacer le contenu du fichier agent.py par le code ci-dessous :

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
)

Voici les points clés du code source ci-dessus :

• Nous définissons l'agent d'IA en lui donnant un nom, suivi du modèle, de la description et d'un ensemble d'instructions très détaillées.
• L'ensemble d'instructions est la partie la plus importante, car il définit précisément comment l'agent doit réfléchir et fonctionner. Cette structure reflète la façon dont les fact-checkers professionnels travaillent, ce qui transforme l'IA en un pipeline d'audit autonome.
• Une fois cette déclaration d'agent effectuée, nous passons à l'octroi de l'accès à des informations concrètes via Google Search tool. Au lieu de s'appuyer sur des données pré-entraînées, l'agent peut effectuer des recherches en direct, évaluer les résultats et fournir des citations à jour.

C'est ce qui rend ce système agentif : le modèle ne se contente pas de générer des réponses, il prend des mesures (à l'aide d'outils) pour vérifier les informations.

Étape 3 : Testez l'agent localement

Dans la fenêtre de terminal existante, exécutez la commande suivante. Assurez-vous de vous trouver dans le dossier parent (workspace-agents) contenant le dossier docfactcheckeragent.

adk web

Voici un exemple d'exécution :

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)

Cliquez sur le dernier lien. Une console Web devrait s'afficher pour vous permettre de tester l'agent. Notre première interaction est fondamentale : comprendre ce que l'agent peut réellement faire. Cela teste sa capacité à résumer ses description et instruction text.

L'agent fournit un résumé concis de ses capacités, en s'appuyant sur sa description et son ensemble d'instructions.

Nous lui fournissons ensuite deux déclarations (The sky is blue due to Rayleigh scattering. The Earth is flat.). Il audite correctement le contenu et renvoie une réponse JSON bien structurée.

Dans le détail :

• L'outil google_search récupère les pages pertinentes sur le Web.
• Le modèle Gemini 2.5 Flash analyse ces extraits et classe leur véracité.
• L'ADK gère l'orchestration du raisonnement et s'assure que la logique étape par étape est respectée.

Cette phase de test local permet de valider le workflow de votre agent avant de le déployer sur Vertex AI Agent Engine, où il peut être connecté à des outils Google Workspace tels que Docs ou Sheets.

En résumé, nous avons créé un puissant agent d'audit IA à l'aide de Google Agent Development Kit (ADK). Notre agent pouvait lire du texte, identifier des affirmations factuelles, rechercher des sources crédibles (à l'aide de l'outil google_search) et renvoyer un verdict clair.

Nous avons tout créé et testé en local via l'interface Web de l'ADK, et nous avons vu comment l'agent analysait une déclaration telle que :

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

L'agent a validé une affirmation comme true et a signalé l'autre comme false, ce qui prouve que notre configuration locale fonctionne parfaitement.

Il est maintenant temps de passer à l'étape suivante : passer du local au cloud. Allons-y.

4. Déployer l'agent sur Vertex AI Agent Engine

Un véritable agent n'est pas seulement quelque chose que vous testez sur votre ordinateur portable. Il s'agit d'un élément que vous pouvez exécuter à grande échelle, intégrer à d'autres systèmes et déployer en production dans vos applications.

Pourquoi déployer ?

Voici quelques bonnes raisons de déployer vos agents dans le cloud.

• Évolutivité : gérez les demandes à volume élevé sans limites d'exécution locales.
• Fiabilité : surveillance et autoscaling intégrés, avec des correctifs tels que la mise à jour de la configuration de l'outil ADK du 18 octobre 2025.
• Prêt pour l'intégration : exposez un point de terminaison d'API pour des appels Workspace fluides.

Pourquoi utiliser Vertex AI Agent Engine ?

Considérez Vertex AI Agent Engine comme l'emplacement de vos agents ADK déployés : un environnement géré conçu pour la fiabilité, l'évolutivité et l'intégration.

Il donne à votre agent :

• État et mémoire persistants
• Exécution d'outils intégrés (par exemple, Recherche Google, modèles Vertex AI)
• Sécuriser les points de terminaison d'API pour les appels externes
• Journalisation et observabilité via Cloud Logging
• Compatibilité native avec l'orchestration multi-agents

En bref, vous écrivez le code une seule fois avec ADK, puis vous le mettez à l'échelle à l'aide d'Agent Engine.

Étape 1 : Configuration pour le déploiement

Nous devons effectuer quelques opérations avant de déployer l'agent Vertex AI Agent Engine. Le processus de déploiement nécessite la création d'un bucket Google Cloud Storage pour les artefacts de l'agent. Nous devons également fournir un fichier requirements.txt afin que toutes les dépendances requises pour exécuter le code de l'agent soient disponibles pour l'environnement d'exécution Agent Engine.

Dans votre terminal Cloud Shell, exécutez la commande suivante pour créer un bucket (n'oubliez pas de remplacer YOUR_BUCKET_NAME, YOUR_PROJECT_ID et YOUR_PROJECT_REGION par des valeurs réelles spécifiques à votre projet) :

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

Créez ensuite le fichier requirements.txt suivant dans le dossier racine (workspace-agents), dont le contenu est indiqué ci-dessous :

google-cloud-aiplatform
google-adk
requests

Étape 2 : Déployez l'agent

L'étape suivante consiste à déployer votre agent sur Vertex AI Agent Engine à l'aide de la commande 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/

Cela devrait lancer un processus de déploiement de notre agent dans Agent Engine. Ce processus prend du temps (environ cinq minutes). Voici ce qui se passe de manière générale :

1. La création de l'agent commence : l'interface de ligne de commande de l'ADK package votre code, l'importe dans votre bucket Cloud Storage et déclenche la création d'une instance Agent Engine par Vertex AI.
2. Un lien vers les journaux vous est fourni. Il vous permet d'afficher l'explorateur de journaux Cloud pour votre projet. Cliquez dessus pour afficher la progression détaillée, y compris les étapes de configuration, l'installation des dépendances et l'initialisation du modèle. En cas de problème (par exemple, une dépendance manquante ou un problème d'autorisation), le message d'erreur s'affiche ici.
3. Message de confirmation : une fois le déploiement terminé, un message de confirmation s'affiche dans le terminal avec votre ID Reasoning Engine. En voici un exemple :

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

Étape 3 : Validez l'agent dans la console Cloud (Agent Engine)

Une fois le déploiement terminé, accédez à la section Vertex AI → Agent Engine de la console Google Cloud. L'agent que vous avez déployé doit s'afficher dans la console, comme indiqué ci-dessous :

🎉 Et voilà ! Votre agent est désormais disponible sur Vertex AI. Vous pouvez l'intégrer à Google Workspace ou le tester directement.

Étape 4 : Testez votre agent de déploiement

Félicitations ! Votre agent est désormais actif sur Vertex AI Agent Engine. L'étape suivante consiste à vérifier qu'il est correctement déployé et qu'il répond aux requêtes.

Vous pouvez procéder de différentes manières, selon votre façon de travailler :

1. Via la console Google Cloud : une interface visuelle permettant d'afficher, de gérer et de tester directement vos agents déployés.
2. Utilisation de l'API REST (cURL) : idéale pour les développeurs qui souhaitent envoyer manuellement des requêtes et inspecter les réponses.
3. Avec le SDK Vertex AI pour Python : une option plus programmatique pour intégrer les tests à votre workflow de développement.

Chaque approche vous permet de comprendre le comportement de votre agent une fois déployé, c'est-à-dire s'il traite les requêtes, gère les sessions ou renvoie des réponses. Pour découvrir des étapes détaillées, des exemples et des configurations avancées pour chaque méthode, consultez la documentation officielle ici.

Votre auditeur d'IA est désormais un agent optimisé par le cloud, déployé sur Vertex AI Agent Engine, prêt à vérifier les faits à grande échelle avec google_search. Il est transformé en un coéquipier numérique fiable, piloté par une API, qui génère du JSON comme suit :

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

Nous allons tester cela directement dans la section suivante, où nous intégrerons l'agent dans un document Google et validerons les faits énoncés dans le document.

5. Intégrer l'agent Fact Checker à Google Docs

Dans cette section, nous allons tout relier en intégrant votre agent déployé dans Google Docs. En quelques lignes d'Apps Script, vous transformerez un document Google Docs standard en un éditeur assisté par l'IA capable d'analyser et de vérifier les faits automatiquement à l'aide de votre agent déployé.

Étape 1 : Configurez votre environnement Google Docs

Commencez par ouvrir un document Google Docs (docs.new) nouveau ou existant.

Le document Google Docs que nous utilisons pour ce tutoriel contient les éléments suivants (vous pouvez utiliser ce document ou votre propre contenu que vous prévoyez de fact-checker) :

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.

Étape 2 : Configurez votre projet et vos fichiers Apps Script

Pour cette configuration, vous aurez besoin de deux fichiers dans votre projet Apps Script :

1. AIVertex.gs : gère toutes les communications avec Vertex AI et l'ADK Agent.
2. Code.gs : contrôle l'interface, les menus et les actions liées aux documents Google Docs.

Dans le menu, accédez à Extensions -> Apps Script pour ouvrir l'éditeur. Nous utiliserons cet espace pour nous connecter à l'agent ADK déployé. Vous trouverez un fichier Code.gs déjà créé. Vous devrez remplacer son contenu par le code Code.gs fourni dans la section suivante.

Passons-les en revue.

AIVertex.gs

Créez un fichier en cliquant sur le signe + à côté de la section "Fichiers" à gauche, sélectionnez-le comme Script et copiez-y le contenu suivant.

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(),
  }
}

N'oubliez pas d'enregistrer le fichier.

Ce fichier effectue les opérations suivantes :

• S'authentifie de manière sécurisée auprès de Vertex AI à l'aide d'une clé de compte de service. Il appelle votre agent ADK déployé pour analyser ou vérifier les faits du texte du document.
• Utilise Gemini pour mettre en forme les réponses de manière intelligente et les rendre lisibles par un humain.

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;
}

Ce fichier connecte l'UI Docs à la logique ADK ci-dessus. Il vous permet de déclencher l'audit directement à partir d'un menu Docs personnalisé. De manière générale, il effectue les opérations suivantes :

• Ajoute un menu personnalisé dans Google Docs appelé "Outils d'audit IA".
• Récupère le texte de votre document et l'envoie à votre agent ADK pour analyse.
• Affiche les résultats de l'audit générés par l'IA dans le document.

Étape 3 : Créer un compte de service

Lorsque vous intégrez la fonctionnalité d'appel d'agent dans un document Google Docs, nous devons fournir une identité au document Google Docs afin qu'il dispose du rôle approprié pour appeler l'agent déployé dans Agent Engine. Pour ce faire, nous allons utiliser un compte de service qui disposera du rôle approprié : roles/aiplatform.user.

Dans Cloud Shell, exécutez le script suivant, étape par étape :

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"

Cela créera le compte de service avec les autorisations appropriées.

Nous générerons une clé JSON pour le compte de service. C'est ce que votre projet Apps Script utilisera pour s'authentifier. Pour obtenir la clé, procédez comme suit :

1. Dans la console Google Cloud, accédez à IAM et administration > Comptes de service.
2. Cliquez sur le compte de service spécifique que vous venez de créer.
3. Accédez à l'onglet "Clés".
4. Cliquez sur Ajouter une clé → Créer une clé.
5. Sélectionnez JSON, puis cliquez sur "Créer".
6. Un fichier JSON est téléchargé automatiquement. Conservez-le précieusement. Vous collerez son contenu dans les propriétés du script dans la section suivante.

Étape 4 : Ajoutez des propriétés de script

Revenez à l'éditeur Apps Script dans Google Docs.

Pour associer votre script à vos ressources déployées, accédez à Project Settings → Script Properties → Add Script Property.

Ajoutez les éléments suivants aux propriétés du script :

1. LOCATION : région de votre déploiement Vertex AI. Exemple : us-central1
2. GEMINI_MODEL_ID : modèle Gemini à utiliser. Utilisez la valeur : gemini-2.5-flash
3. REASONING_ENGINE_ID : ID de l'agent ADK déployé. Vous pouvez l'obtenir à partir de l'option Agent Engine de la console pour l'agent spécifique que vous avez déployé. Le nom de ressource de l'agent déployé s'affiche. L'ID d'agent correspond à la dernière valeur numérique du nom de la ressource (c'est-à-dire RESOURCE_ID). Par exemple : projects/SOME_ID/locations/REGION/reasoningEngines/RESOURCE_ID
4. SERVICE_ACCOUNT_KEY : copiez l'intégralité du contenu de la clé JSON que vous avez téléchargée pour le compte de service que nous avons créé à l'étape précédente.

Cliquez sur Enregistrer les propriétés de script.

Étape 5 : Ajoutez la bibliothèque OAuth2

Notre projet Apps Script a besoin de la bibliothèque OAuth2 pour authentifier les appels d'API.

Pour l'ajouter :

1. Accéder à Services → Libraries
2. Cliquez sur Add a Library.
3. Saisissez l'ID du script : 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

Étape 6 : Tester l'agent Fact Checker Doc dans Google Docs

Nous voici à la dernière étape pour tester l'agent dans Google Docs. Pour ce faire, procédez comme suit :

1. Dans l'éditeur Apps Script, exécutez la fonction onOpen() une seule fois. Un nouveau menu "Outils d'audit de l'IA" est alors ajouté à Google Docs.
2. Revenez à votre document. Un élément de menu supplémentaire intitulé AI Audit Tools s'affiche dans le menu principal. Cliquez dessus, puis sur Run AI Audit.

Voici un exemple d'exécution :

6. Nettoyage

Pour éviter que des frais ne soient facturés en permanence sur votre compte Google Cloud, il est important de supprimer les ressources que nous avons créées lors de cet atelier.

Si vous n'avez plus besoin de déployer l'agent dans Agent Engine, vous pouvez le supprimer en suivant les étapes ci-dessous :

1. Accédez à la page Vertex AI Agent Engine dans la console Google Cloud.
2. Dans la liste des agents déployés, recherchez celui que vous souhaitez supprimer.
3. Cliquez sur le menu à trois points (autres actions) à côté du nom de l'agent.
4. Sélectionnez Supprimer dans le menu déroulant.
5. Confirmez la suppression en cliquant sur Supprimer l'agent dans la boîte de dialogue de confirmation.

Il est recommandé de supprimer également le compte de service.

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

7. Félicitations

Vous avez maintenant déployé votre agent d'IA, l'avez associé à Google Docs et l'avez vu à l'œuvre : il analyse, raisonne et résume directement là où se trouve votre contenu. Ce que nous avons créé ici n'est pas qu'une simple démo autonome. Il s'agit de la base de la collaboration intelligente et axée sur les agents dans Google Workspace.

En combinant les capacités de raisonnement de l'ADK avec les modèles génératifs de Gemini, nous avons transformé Google Docs en un assistant vivant et pensant, capable de lire, d'auditer et d'affiner votre texte en tenant compte du contexte.

Le même plan s'étend naturellement à Sheets, Slides, Drive et Gmail. Imaginez des agents qui :

• Vérifier les données financières et signaler les incohérences dans Sheets
• Générer automatiquement des présentations et des résumés dans Slides
• Libeller et organiser intelligemment des documents dans Drive
• ou même rédiger et vérifier des e-mails directement dans Gmail.

Cette démonstration pose les bases de la création de workflows agentifs qui s'intègrent parfaitement à vos outils Workspace quotidiens, transformant les documents statiques en collaborateurs dynamiques basés sur l'IA.

Documents de référence

• Agent Development Kit
• Agent Engine