Flujos de trabajo basados en agentes en Google Workspace: Compila un agente de Documentos de Google con el ADK

1. Introducción

Google Workspace es donde se realiza el trabajo. Desde redactar informes en Documentos hasta analizar datos en Hojas de cálculo y colaborar en Gmail y Meet.

Ahora imagina que tus Documentos, Hojas de cálculo y Gmail no fueran solo herramientas, sino colaboradores.

Con la ayuda del Kit de desarrollo de agentes (ADK) de Google y Agent Engine de Vertex AI, ya no se trata solo de una idea, sino que usaremos estos frameworks para crear un agente inteligente, implementarlo a gran escala y, luego, integrarlo sin problemas en nuestras herramientas de Google Workspace, lo que permitirá una nueva era de productividad basada en agentes.

En este codelab, seguirás un enfoque paso a paso de la siguiente manera:

1. Desarrolla el agente de verificación de hechos con IA usando el Kit de desarrollo de agentes.
2. Implementa el agente en Agent Engine, un entorno completamente administrado para ejecutar agentes a gran escala.
3. Integra este agente en Documentos de Google para verificar los datos del texto del documento.

A continuación, se muestra un diagrama conceptual que explica cómo funciona la solución final:

Este es el resultado final de cómo funciona el agente de verificación de datos dentro de un documento de Google, en el que había un texto original que contenía algunas declaraciones y se realiza una verificación de datos para cada una de las declaraciones del documento. El límite de salida en la caja con la esquina roja es la salida del agente.

Actividades

• Diseña, compila e implementa un agente que realizará la verificación de datos dentro de un Documento de Google.

Qué aprenderás

• Desarrollar un agente con el Kit de desarrollo de agentes (ADK)
• Prueba el agente de forma local y, luego, impleméntalo en Agent Engine.
• Integra el agente en un documento de Google Workspace (Documento de Google).

Requisitos

• Navegador web Chrome
• Una cuenta de Gmail
• Un proyecto de Cloud con la facturación habilitada

Este codelab, diseñado para desarrolladores de todos los niveles (incluidos los principiantes), usa Python y Apps Script en su código de muestra. Sin embargo, el conocimiento de estos lenguajes de programación no es un requisito previo, y la capacidad básica de lectura de código será suficiente para comprender los conceptos presentados.

2. Antes de comenzar

Crea un proyecto

1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto .

Para obtener créditos de Google Cloud: Si deseas obtener créditos de Google Cloud para comenzar, usa este vínculo para canjear créditos que te ayudarán a completar el lab. Puedes seguir las instrucciones aquí para canjearlo.

3. Usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud y que viene precargado con bq. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.

4. Una vez que te conectes a Cloud Shell, verifica que ya te autenticaste y que el proyecto se configuró con el ID de tu proyecto con el siguiente comando:

gcloud auth list

5. En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.

gcloud config list project

6. Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:

gcloud config set project <YOUR_PROJECT_ID>

7. Habilita las APIs requeridas con el siguiente comando. Este proceso puede tardar unos minutos, así que ten paciencia.

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

Si el comando se ejecuta correctamente, deberías ver un mensaje similar al que se muestra a continuación:

Operation "operations/..." finished successfully.

Si olvidas alguna API, puedes habilitarla durante el proceso de implementación.

Consulta la documentación para ver los comandos y el uso de gcloud.

3. Compila el agente de ADK

Creemos el agente de ADK (Document Fact Checker Agent), un auditor basado en IA que verifica los hechos del texto, inspirado en la función personalizada de verificación de datos de Google ejemplo. A diferencia del enfoque de un solo paso del ejemplo, nuestro agente usa un razonamiento de varios pasos para extraer afirmaciones, verificarlas con google_search y generar JSON estructurado.

Paso 1 : Instala el Agent Development Kit

Abre una nueva pestaña de la terminal en Cloud Shell y crea una carpeta llamada my-agents de la siguiente manera. Navega también a la carpeta my-agents.

mkdir workspace-agents
cd workspace-agents

Ahora, crearemos un entorno virtual de Python con venv de la siguiente manera:

python -m venv .venv

Activa el entorno virtual de la siguiente manera:

source .venv/bin/activate

Instala el ADK de la siguiente manera:

pip install google-adk

Ahora podrás invocar la utilidad adk de la siguiente manera.

adk

Se mostrará una lista de comandos.

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

Paso 2 : Desarrolla el agente de verificación de hechos de documentos con el ADK

Ahora usaremos adk para crear un andamiaje para nuestro agente a través del comando adk create con el nombre de la app **(docfactcheckeragent)**, como se indica a continuación.

adk create docfactcheckeragent

Sigue los pasos y selecciona lo siguiente:

• Modelo de Gemini para elegir un modelo para el agente raíz.
• Elige Vertex AI para el backend.
• Se mostrarán el ID y la región predeterminados de tu proyecto de Google. Selecciona el valor predeterminado.

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

Observa la carpeta en la que se crearon una plantilla predeterminada y los archivos necesarios para el agente.

Primero, está el archivo .env. El contenido se muestra a continuación:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

Los valores indican que usaremos Gemini a través de Vertex AI junto con los valores respectivos del ID y la ubicación del proyecto de Google Cloud.

Luego, tenemos el archivo __init__.py que marca la carpeta como un módulo y tiene una sola instrucción que importa el agente del archivo agent.py.

from . import agent

Por último, está el archivo agent.py. Deberás reemplazar el contenido de este archivo agent.py por el código que se muestra a continuación:

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
)

Los puntos clave del código fuente anterior son los siguientes:

• Definimos el agente de IA asignándole un nombre, seguido del modelo, la descripción y un conjunto de instrucciones muy detallado.
• El conjunto de instrucciones es la parte más importante que define cómo exactamente debe pensar y operar el agente. Esta estructura refleja cómo trabajan los verificadores de datos profesionales, lo que convierte la IA en una canalización de auditoría autónoma.
• Una vez que se completa esta declaración del agente, pasamos a otorgarle acceso a información del mundo real a través de Google Search tool. En lugar de depender de datos previamente entrenados, el agente puede realizar búsquedas en vivo, evaluar los resultados y proporcionar citas actualizadas.

Eso es lo que hace que este sistema sea agentivo: el modelo no solo genera respuestas, sino que también toma medidas (con herramientas) para verificar la información.

Paso 3 : Prueba el agente de forma local

Desde la ventana de terminal existente, ingresa el siguiente comando. Asegúrate de estar en la carpeta principal (workspace-agents) que contiene la carpeta docfactcheckeragent.

adk web

A continuación, se muestra una ejecución de muestra:

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)

Haz clic en el último vínculo, y debería aparecer una consola web para probar el agente. Nuestra primera interacción es fundamental: comprender lo que el agente puede hacer. Esto pone a prueba la capacidad del agente para resumir su description y su instruction text.

El agente proporciona un resumen conciso de sus capacidades, basado en su descripción y su conjunto de instrucciones.

Luego, le proporcionamos dos declaraciones (The sky is blue due to Rayleigh scattering. The Earth is flat.), y audita correctamente el contenido y devuelve una respuesta JSON bien estructurada.

Detrás de escena:

• La herramienta google_search recupera páginas pertinentes de la Web.
• El modelo Gemini 2.5 Flash analiza esos fragmentos y clasifica su veracidad.
• El ADK controla la organización del razonamiento y garantiza que se siga la lógica paso a paso.

Esta fase de prueba local ayuda a validar el flujo de trabajo de nuestro agente antes de que lo implementes en Vertex AI Agent Engine, donde se puede conectar a herramientas de Google Workspace, como Documentos o Hojas de cálculo.

En resumen, creamos un potente agente de auditoría de IA con el Kit de desarrollo de agentes (ADK) de Google. Nuestro agente podía leer texto, identificar afirmaciones fácticas, buscar fuentes creíbles (con la herramienta google_search) y devolver un veredicto claro.

Creamos y probamos todo de forma local a través de la interfaz web del ADK y vimos cómo el agente analizaba una declaración como la siguiente:

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

El agente verificó un reclamo como true y marcó el otro como false, una prueba pequeña pero adecuada de que nuestra configuración local funciona perfectamente.

Ahora es momento de dar el siguiente gran paso: pasar de la nube local a la nube. Sigamos con eso.

4. Implementa el agente en Vertex AI Agent Engine

Un agente real no es solo algo que pruebas en tu laptop, sino algo que puedes ejecutar a gran escala, integrar con otros sistemas y, luego, implementar para la producción en todas tus apps.

¿Por qué implementar?

Estos son algunos buenos motivos para implementar tus agentes en la nube.

• Escalabilidad: Maneja solicitudes de gran volumen sin límites de tiempo de ejecución locales.
• Confiabilidad: Supervisión y ajuste de escala automáticos integrados, con correcciones como la actualización de configuración de la herramienta del ADK del 18 de octubre de 2025.
• Listo para la integración: Expone un extremo de API para llamadas fluidas de Workspace.

¿Por qué usar Vertex AI Agent Engine?

Piensa en Vertex AI Agent Engine como el hogar de tus agentes del ADK implementados, un entorno administrado creado para brindar confiabilidad, escalabilidad e integración.

Le proporciona a tu agente lo siguiente:

• Estado y memoria persistentes
• Ejecución de herramientas integradas (p.ej., Búsqueda de Google, modelos de Vertex AI)
• Protege los extremos de la API para llamadas externas
• Registro y observabilidad a través de Cloud Logging
• Compatibilidad nativa con la organización de varios agentes

En resumen, escribes una vez con el ADK y, luego, lo amplías con Agent Engine.

Paso 1 : Configuración para la implementación

Debemos hacer algunas cosas antes de implementar el agente en Vertex AI Agent Engine. El proceso de implementación requiere que se cree un bucket de Google Cloud Storage para los artefactos del agente, y también debemos proporcionar un archivo requirements.txt para que todas las dependencias necesarias para ejecutar el código del agente estén disponibles en el entorno de ejecución de Agent Engine.

En la terminal de Cloud Shell, ejecuta el siguiente comando para crear un bucket (recuerda reemplazar YOUR_BUCKET_NAME, YOUR_PROJECT_ID y YOUR_PROJECT_REGION por valores reales específicos de tu proyecto):

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

A continuación, crea el siguiente archivo requirements.txt en la carpeta raíz (workspace-agents), cuyo contenido se muestra a continuación:

google-cloud-aiplatform
google-adk
requests

Paso 2 : Implementa el agente

El siguiente paso es implementar tu agente en Vertex AI Agent Engine con el 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/

Esto debería iniciar un proceso para implementar nuestro agente en Agent Engine. El proceso lleva tiempo y se espera que tarde aproximadamente 5 minutos. A grandes rasgos, esto es lo que sucede:

1. Comienza la creación del agente: La CLI del ADK empaqueta tu código, lo sube a tu bucket de Cloud Storage y activa Vertex AI para que cree una nueva instancia de Agent Engine.
2. Se te proporciona un vínculo a Registros, en el que puedes ver el Explorador de registros de Cloud para tu proyecto. Haz clic en él para ver el progreso detallado, incluidos los pasos de configuración, la instalación de dependencias y la inicialización del modelo. Si algo sale mal (por ejemplo, falta una dependencia o hay un problema de permisos), verás el mensaje de error aquí.
3. Mensaje de finalización: Una vez que se complete la implementación, verás un mensaje de confirmación en la terminal con tu ID de Reasoning Engine. A continuación, se muestra un ejemplo:

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

Paso 3 : Verifica el agente en la consola de Cloud (Agent Engine)

Una vez que se complete la implementación, ve a la sección Vertex AI → Agent Engine de la consola de Google Cloud. Deberías ver tu agente implementado en la consola, como se muestra a continuación:

🎉 ¡Eso es todo! Tu agente ya está disponible en Vertex AI y listo para integrarse en Google Workspace o probarse directamente.

Paso 4 : Prueba tu agente de implementación

¡Felicitaciones! Tu agente ya está disponible en Vertex AI Agent Engine. El siguiente paso es probar que se implementó correctamente y que responde a las solicitudes.

Hay varias formas de hacerlo, según tu preferencia:

1. A través de la consola de Google Cloud: Una interfaz visual para ver, administrar y probar directamente los agentes implementados.
2. Usa la API de REST (cURL): Es ideal para los desarrolladores que desean enviar solicitudes de forma manual y, luego, inspeccionar las respuestas.
3. Con el SDK de Vertex AI para Python: Una opción más programática para integrar las pruebas en tu flujo de trabajo de desarrollo.

Cada enfoque te brinda información sobre el comportamiento de tu agente una vez que se implementa, es decir, si procesa consultas, controla sesiones o devuelve respuestas. Para explorar los pasos detallados, los ejemplos y las configuraciones avanzadas de cada método, consulta la documentación oficial aquí.

Tu auditor de IA ahora es un agente potenciado por la nube, implementado en Vertex AI Agent Engine y listo para verificar datos a gran escala con google_search. Se transforma en un compañero digital confiable y basado en la API, que genera JSON como el siguiente:

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

Probaremos esto directamente en la siguiente sección, en la que integraremos el agente en un documento de Google y validaremos los hechos que se indican en el documento.

5. Integra el agente de Verificación de datos en Documentos de Google

En esta sección, conectaremos todo para incorporar tu agente implementado en Documentos de Google. Con unas pocas líneas de Apps Script, transformarás un documento de Google estándar en un editor asistido por IA que puede analizar y verificar la información automáticamente con tu agente implementado.

Paso 1: Configura tu entorno de Documentos de Google

Para comenzar, abre un documento de Google nuevo o existente (docs.new).

El documento de Google que usamos para este instructivo contiene el siguiente contenido (puedes usarlo o tu propio contenido que planeas verificar):

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.

Paso 2: Configura tu proyecto y archivos de Apps Script

Para esta configuración, necesitarás dos archivos en tu proyecto de Apps Script:

1. AIVertex.gs: Controla toda la comunicación con Vertex AI y el agente del ADK.
2. Code.gs: Controla la interfaz, los menús y las acciones del documento de Documentos de Google.

En el menú, ve a Extensions -> Apps Script para abrir el editor. Usaremos este espacio para conectarnos al agente del ADK implementado. Verás que ya se creó un archivo Code.gs, y deberás reemplazar su contenido por el código Code.gs que se proporciona en la siguiente sección.

Veamos cada una.

AIVertex.gs

Crea un archivo nuevo con el signo + que se encuentra junto a la sección Files a la izquierda, selecciónalo como Script y copia el siguiente contenido en él.

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

Recuerda guardar el archivo.

Este archivo hace lo siguiente:

• Se autentica de forma segura en Vertex AI con una clave de cuenta de servicio. Invoca a tu agente de ADK implementado para analizar o verificar los datos del texto del documento.
• Utiliza Gemini para dar formato a las respuestas inteligentes , lo que hace que los resultados sean legibles.

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

Este archivo conecta la IU de Documentos con la lógica del ADK mencionada anteriormente. Te permite activar la auditoría directamente desde un menú personalizado de Documentos. En un nivel alto, hace lo siguiente:

• Agrega un menú personalizado en Documentos de Google llamado Herramientas de auditoría de IA.
• Toma el texto de tu documento y lo envía a tu agente del ADK para su análisis.
• Muestra los resultados de la auditoría generados por IA en el documento.

Paso 3 : Crea una cuenta de servicio

Cuando integras la funcionalidad de llamada a agentes en un documento de Google, debemos proporcionar una identidad al documento de Google para que tenga el rol correcto para invocar al agente implementado en Agent Engine. Para ello, usaremos una cuenta de servicio que tendrá el rol correcto: roles/aiplatform.user.

En Cloud Shell, ejecuta la siguiente secuencia de comandos paso a paso:

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"

Esto creará la cuenta de servicio con los permisos correctos.

Generaremos una clave JSON para la cuenta de servicio. Esto es lo que usará tu proyecto de Apps Script para la autenticación. Estos son los pasos para obtener la clave:

1. En la consola de Google Cloud, ve a IAM y administración > Cuentas de servicio.
2. Haz clic en la cuenta de servicio específica que acabas de crear.
3. Ve a la pestaña Claves.
4. Haz clic en Agregar clave → Crear clave nueva.
5. Selecciona JSON y, luego, haz clic en Crear.
6. Se descargará automáticamente un archivo JSON que debes guardar en un lugar seguro. Pegarás su contenido en las propiedades de la secuencia de comandos en la siguiente sección.

Paso 4 : Agrega propiedades de secuencia de comandos

Regresa al editor de Apps Script en el documento de Google.

Para conectar tu secuencia de comandos a los recursos implementados, ve a Project Settings → Script Properties → Add Script Property.

Agrega lo siguiente a las propiedades de la secuencia de comandos:

1. LOCATION: Es la región de tu implementación de Vertex AI. P.ej., us-central1
2. GEMINI_MODEL_ID: Es el modelo de Gemini que se usará. Usa el valor gemini-2.5-flash.
3. REASONING_ENGINE_ID: Es el ID del agente del ADK implementado. Puedes obtenerlo en la opción Agent Engine de la consola de tu agente específico que implementaste. Verás el nombre del recurso del agente implementado. El ID del agente es el último valor numérico del nombre del recurso (es decir, RESOURCE_ID). Por ejemplo, projects/SOME_ID/locations/REGION/reasoningEngines/RESOURCE_ID
4. SERVICE_ACCOUNT_KEY: Copia todo el contenido de la clave JSON que descargaste para la cuenta de servicio que creamos en el paso anterior.

Haz clic en Guardar las propiedades de la secuencia de comandos.

Paso 5 : Agrega la biblioteca de OAuth2

Nuestro proyecto de Apps Script necesita la biblioteca de OAuth2 para autenticar las llamadas a la API.

Para agregarlo, sigue estos pasos:

1. Ir a Services → Libraries
2. Haz clic en Add a Library.
3. Ingresa el ID del script: 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

Paso 6 : Prueba el agente de documentos Fact Checker en Documentos de Google

Estamos en el último paso para probar el agente dentro de Documentos de Google. Para ello, haz lo siguiente:

1. En el editor de Apps Script, ejecuta la función onOpen() una vez. Se agregará un nuevo menú de Herramientas de auditoría de IA en Documentos de Google.
2. Regresa a tu documento. Verás un elemento de menú adicional en el menú principal llamado AI Audit Tools. Haz clic en él y, luego, en Run AI Audit.

A continuación, se muestra una ejecución de ejemplo:

6. Limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud, es importante que borres los recursos que creamos durante este taller.

Si ya no necesitas que el agente se implemente en Agent Engine, puedes borrarlo siguiendo los pasos que se indican a continuación:

1. Navega a la página Vertex AI Agent Engine en la consola de Google Cloud.
2. Busca el agente que deseas borrar en la lista de agentes implementados.
3. Haz clic en el menú de tres puntos (más acciones) junto al nombre del agente.
4. Selecciona Borrar en el menú desplegable.
5. Para confirmar la eliminación, haz clic en Borrar agente en el cuadro de diálogo de confirmación.

Como práctica recomendada, también borra la cuenta de servicio.

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

7. Felicitaciones

Ahora implementaste tu agente de IA, lo conectaste a Documentos de Google y lo viste en acción: analiza, razona y resume directamente donde se encuentra tu contenido. Lo que creamos aquí no es solo una demostración independiente. Es la base de la colaboración inteligente impulsada por agentes dentro de Google Workspace.

Al combinar las capacidades de razonamiento del ADK con los modelos generativos de Gemini, convertimos Google Docs en un asistente vivo y pensante que puede leer, auditar y perfeccionar tu texto con contexto.

El mismo diseño se extiende de forma natural a Hojas de cálculo, Presentaciones, Drive y Gmail. Imagina agentes que hagan lo siguiente:

• Audita datos financieros y marca incoherencias en Hojas de cálculo
• Genera automáticamente resúmenes y presentaciones de ventas en Presentaciones
• Etiqueta y organiza documentos de forma inteligente en Drive
• O incluso redactar y verificar la información de los correos electrónicos directamente en Gmail

Esta demostración sienta las bases para crear flujos de trabajo basados en agentes que se integran a la perfección en tus herramientas diarias de Workspace, lo que convierte los documentos estáticos en colaboradores dinámicos de IA.

Documentos de referencia

• Kit de desarrollo de agentes
• Motor del agente