Рабочие процессы Agentic в Google Workspace: создание агента Google Docs с помощью ADK

1. Введение

Google Workspace — это место, где происходит работа. От составления отчётов в Документах до обработки данных в Таблицах и совместной работы в Gmail и Meet.

А теперь представьте, если бы ваши Документы, Таблицы и Gmail были не просто инструментами, а средствами совместной работы.

Благодаря Agent Development Kit (ADK) от Google и Agent Engine от Vertex AI это уже не просто идея: мы будем использовать эти фреймворки для создания интеллектуального агента, масштабного его развертывания и бесшовной интеграции в инструменты Google Workspace, открывая новую эру производительности агентов.

В этой лабораторной работе вы будете использовать следующий пошаговый подход:

1. Разработайте агента проверки фактов на основе ИИ с помощью комплекта разработки агентов.
2. Разверните агента в Agent Engine — полностью управляемой среде для запуска агентов в любом масштабе.
3. Интегрируйте этот агент в Google Doc для проверки фактов в тексте документа.

Ниже представлена ​​концептуальная схема, поясняющая принцип работы окончательного решения:

Вот окончательный вывод работы Fact Check Agent в документе Google Doc. В исходном тексте, содержащем несколько утверждений, Fact Check Agent проверяет каждое из них. Вывод, обведённый красным уголком, — это результат работы Fact Check Agent.

Что ты будешь делать?

• Спроектируйте, создайте и разверните агента, который будет выполнять проверку фактов внутри Google Doc.

Чему вы научитесь

• Разработайте агента с помощью Agent Development Kit (AK).
• Протестируйте Agent локально и разверните его на Agent Engine.
• Интегрируйте Агент в документ Google Workspace (Google Doc).

Что вам понадобится

• веб-браузер Chrome
• Аккаунт Gmail
• Облачный проект с включенным биллингом

Эта лабораторная работа, предназначенная для разработчиков любого уровня (включая новичков), использует примеры кода на Python и Apps Script. Однако знание этих языков программирования не является обязательным требованием, и базовых навыков чтения кода будет достаточно для понимания представленных концепций.

2. Прежде чем начать

Создать проект

1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud.
2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .

Для получения кредитов Google Cloud: если вы хотите получить кредиты Google Cloud для начала работы, воспользуйтесь этой ссылкой , чтобы активировать кредиты, которые помогут вам выполнить лабораторную работу. Инструкции по активации приведены здесь .

3. Вы будете использовать Cloud Shell — среду командной строки, работающую в Google Cloud и предустановленную вместе с bq. Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud.

4. После подключения к Cloud Shell вы проверяете, что вы уже прошли аутентификацию и что проекту присвоен ваш идентификатор проекта, с помощью следующей команды:

gcloud auth list

5. Выполните следующую команду в Cloud Shell, чтобы подтвердить, что команда gcloud знает о вашем проекте.

gcloud config list project

6. Если ваш проект не настроен, используйте следующую команду для его настройки:

gcloud config set project <YOUR_PROJECT_ID>

7. Включите необходимые API с помощью команды, показанной ниже. Это может занять несколько минут, поэтому, пожалуйста, наберитесь терпения.

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

При успешном выполнении команды вы должны увидеть сообщение, похожее на показанное ниже:

Operation "operations/..." finished successfully.

Если какой-либо API отсутствует, вы всегда можете включить его в ходе реализации.

Информацию о командах и использовании gcloud см. в документации .

3. Создание агента ADK

Давайте создадим агента ADK ( Document Fact Checker Agent ) — аудитора на основе искусственного интеллекта, который проверяет текстовые факты, вдохновлённого примером пользовательской функции Fact-Check от Google. В отличие от одношагового подхода, представленного в примере, наш агент использует многошаговый подход для извлечения утверждений, их проверки с помощью Google_search и вывода структурированного JSON-файла.

Шаг 1: Установка комплекта разработки агента

Откройте новую вкладку терминала в Cloud Shell и создайте папку с именем my-agents как показано ниже. Перейдите в папку my-agents .

mkdir workspace-agents
cd workspace-agents

Теперь давайте создадим виртуальную среду Python с помощью venv следующим образом:

python -m venv .venv

Активируйте виртуальную среду следующим образом:

source .venv/bin/activate

Установите ADK следующим образом:

pip install google-adk

Теперь вы сможете вызвать утилиту adk следующим образом.

adk

Он покажет вам список команд.

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

Шаг 2: Разработка агента проверки фактов документа с использованием ADK

Теперь мы собираемся использовать adk для создания каркаса для нашего агента с помощью команды adk create с именем приложения ** (docfactcheckeragent) **, как указано ниже.

adk create docfactcheckeragent

Следуйте инструкциям и выберите следующее:

• Модель Gemini для выбора модели корневого агента.
• Выберите Vertex AI для бэкэнда.
• Будут отображены идентификатор и регион вашего проекта Google по умолчанию. Выберите регион по умолчанию.

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

Обратите внимание на папку, в которой были созданы шаблон по умолчанию и необходимые файлы для Агента.

Первым идёт файл .env . Его содержимое показано ниже:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

Значения указывают на то, что мы будем использовать Gemini через Vertex AI вместе с соответствующими значениями идентификатора и местоположения проекта Google Cloud.

Затем у нас есть файл __init__.py , который отмечает папку как модуль и содержит единственный оператор, который импортирует агента из файла agent.py .

from . import agent

Наконец, файл agent.py . Вам нужно заменить его содержимое кодом agent.py приведённым ниже:

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
)

Ключевые моменты исходного кода выше:

• Мы определяем агента ИИ, давая ему имя, а затем модель, описание и очень подробный набор инструкций.
• Набор инструкций — важнейшая часть, определяющая, как именно должен мыслить и действовать агент. Эта структура отражает принципы работы профессиональных фактчекеров, превращая ИИ в автономный конвейер аудита.
• После завершения объявления агента мы переходим к предоставлению агенту доступа к реальной информации через Google Search tool . Вместо того, чтобы полагаться на предварительно обученные данные, агент может выполнять поиск в режиме реального времени, оценивать результаты и предоставлять актуальные цитаты.

Именно это делает данную систему агентной — модель не просто генерирует ответы, она предпринимает действия (используя инструменты) для проверки информации.

Шаг 3: локальное тестирование агента

В окне терминала выполните следующую команду. Убедитесь, что вы находитесь в родительской папке (workspace-agents) содержащей папку docfactcheckeragent .

adk web

Пример выполнения показан ниже:

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)

Нажмите на последнюю ссылку, и должна открыться веб-консоль для тестирования агента. Наш первый шаг — основополагающий: понимание того, что агент может делать. Это позволяет проверить способность агента кратко излагать текст своего description и instruction text .

Агент предоставляет краткий обзор своих возможностей, основанный на его описании и наборе инструкций.

Затем мы передаем ему два утверждения ( The sky is blue due to Rayleigh scattering. The Earth is flat. ), и он успешно проверяет содержимое и возвращает хорошо структурированный ответ JSON.

Под капотом:

• Инструмент google_search извлекает релевантные страницы из Интернета.
• Модель Gemini 2.5 Flash анализирует эти фрагменты и классифицирует их на предмет достоверности.
• ADK управляет организацией рассуждений и обеспечивает пошаговое соблюдение логики.

Эта локальная фаза тестирования помогает проверить рабочий процесс нашего агента перед его развертыванием в Vertex AI Agent Engine, где его можно подключить к инструментам Google Workspace, таким как Docs или Sheets.

Подводя итог, мы создали мощный ИИ-аудитор с помощью набора инструментов Google Agent Development Kit (ADK). Наш агент мог читать текст, определять фактические утверждения, искать достоверные источники (с помощью инструмента google_search) и выносить однозначный вердикт.

Мы построили и протестировали все локально через веб-интерфейс ADK и увидели, как агент анализирует такое утверждение:

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

Агент подтвердил одно утверждение как true и пометил другое как false — небольшое, но убедительное доказательство того, что наша локальная настройка работает идеально.

Теперь пришло время сделать следующий большой шаг — перейти от локального хранилища к облаку. Давайте сделаем это сейчас.

4. Развертывание агента в Vertex AI Agent Engine

Настоящий агент — это не просто то, что вы тестируете на своем ноутбуке, это то, что вы можете запускать в любом масштабе, интегрировать с другими системами и развертывать в рабочих средах своих приложений.

Зачем развертывать?

Вот несколько веских причин развернуть ваших агентов в облаке.

• Масштабируемость: обработка больших объемов запросов без локальных ограничений времени выполнения.
• Надежность: встроенный мониторинг и автоматическое масштабирование, а также исправления, такие как обновление конфигурации инструмента ADK от 18 октября 2025 г.
• Готовность к интеграции: предоставление конечной точки API для бесперебойных вызовов Workspace.

Почему Vertex AI Agent Engine?

Думайте о Vertex AI Agent Engine как о доме для развернутых агентов ADK — управляемой среде, созданной для надежности, масштабируемости и интеграции.

Это дает вашему агенту:

• Постоянное состояние и память
• Интегрированное выполнение инструментов (например, Google Search, Vertex AI Models)
• Безопасные конечные точки API для внешних вызовов
• Ведение журнала и наблюдение с помощью Cloud Logging
• Встроенная поддержка многоагентной оркестровки

Короче говоря — вы пишете один раз с помощью ADK, а затем масштабируете с помощью Agent Engine.

Шаг 1: Настройка для развертывания

Перед развертыванием агента Vertex AI Agent Engine необходимо выполнить несколько действий. Для развертывания необходимо создать контейнер Google Cloud Storage для артефактов агента, а также предоставить файл requirements.txt , чтобы все зависимости, необходимые для запуска кода агента, были доступны в среде выполнения Agent Engine.

В терминале Cloud Shell введите следующую команду для создания контейнера (не забудьте заменить YOUR_BUCKET_NAME , YOUR_PROJECT_ID и YOUR_PROJECT_REGION фактическими значениями, специфичными для вашего проекта):

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

Затем создайте следующий файл requirements.txt в корневой папке ( workspace-agents ), содержимое которого показано ниже:

google-cloud-aiplatform
google-adk
requests

Шаг 2: Развертывание агента

Следующим шагом будет развертывание вашего агента в Vertex AI Agent Engine с помощью команды 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/

Это должно запустить процесс развертывания нашего агента в Agent Engine. Этот процесс занимает много времени и может занять около 5 минут. Вкратце, вот что происходит:

1. Начинается создание агента — ADK CLI упаковывает ваш код, загружает его в контейнер облачного хранилища и запускает Vertex AI для создания нового экземпляра Agent Engine.
2. Вам предоставляется ссылка «Журналы», по которой вы можете просмотреть данные обозревателя облачных журналов для своего проекта. Щелкните по ней, чтобы увидеть подробную информацию о ходе выполнения, включая этапы настройки, установки зависимостей и инициализации модели. Если что-то пойдёт не так (например, отсутствующая зависимость или проблема с разрешениями), вы увидите сообщение об ошибке здесь.
3. Сообщение о завершении. После завершения развёртывания в терминале появится подтверждающее сообщение с вашим идентификатором Reasoning Engine. Пример сообщения показан ниже:

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

Шаг 3: Проверка агента в Cloud Console (Agent Engine)

После завершения развертывания перейдите в раздел Vertex AI → Agent Engine в консоли Google Cloud. Развёрнутый агент должен появиться в списке консоли, как показано ниже:

🎉 Вот и всё! Ваш агент теперь доступен на Vertex AI и готов к интеграции в Google Workspace или непосредственному тестированию.

Шаг 4: Тестирование вашего агента развертывания

Поздравляем! Ваш агент теперь доступен в Vertex AI Agent Engine! Следующий шаг — проверить, правильно ли он развёрнут и реагирует на запросы.

Есть несколько способов сделать это, в зависимости от того, как вы предпочитаете работать:

1. Через Google Cloud Console: визуальный интерфейс для непосредственного просмотра, управления и тестирования развернутых агентов.
2. Использование REST API (cURL): идеально подходит для разработчиков, которые хотят вручную отправлять запросы и проверять ответы.
3. С Vertex AI SDK для Python: более программный вариант интеграции тестирования в процесс разработки.

Каждый подход даёт представление о том, как ведёт себя ваш агент после развёртывания, то есть обрабатывает ли он запросы, управляет сеансами или возвращает ответы. Подробные инструкции, примеры и расширенные настройки для каждого метода см. в официальной документации здесь .

Ваш AI Auditor теперь представляет собой облачный агент, развёрнутый в Vertex AI Agent Engine и готовый к масштабной проверке фактов с помощью Google_search. Он превращается в надёжного цифрового помощника на базе API, генерирующего JSON-данные, например:

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

Мы непосредственно протестируем это в следующем разделе, где интегрируем агента в документ Google и проверим факты, изложенные в документе.

5. Интегрируйте Fact Checker Agent в Google Docs

В этом разделе мы соединим всё воедино — внедрим ваш развёрнутый агент в Google Docs. С помощью нескольких строк Apps Script вы превратите стандартный Google Docs в редактор с искусственным интеллектом, который сможет автоматически анализировать и проверять факты в контенте, используя ваш развёрнутый агент.

Шаг 1: Настройте среду Google Docs

Начните с открытия нового или существующего документа Google ( docs.new ).

Документ Google, который мы используем для этого руководства, содержит следующее содержимое (вы можете использовать его или свой собственный контент, который вы планируете проверить):

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.

Шаг 2: Настройте проект и файлы Apps Script

Для этой настройки вам понадобятся два файла в проекте Apps Script:

1. AIVertex.gs – обрабатывает все коммуникации с Vertex AI и агентом ADK.
2. Code.gs – управляет интерфейсом Google Docs, меню и действиями с документами.

В меню выберите Extensions -> Apps Script , чтобы открыть редактор. Мы будем использовать это поле для подключения к развёрнутому агенту ADK. Вы обнаружите уже созданный файл Code.gs , содержимое которого нужно заменить кодом Code.gs приведённым в следующем разделе.

Давайте рассмотрим каждый из них.

AIVertex.gs

Создайте новый файл с помощью знака + рядом с разделом «Файлы» слева, выберите его как Script и скопируйте в него следующее содержимое.

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

Не забудьте сохранить файл.

Этот файл делает следующее:

• Выполняет безопасную аутентификацию в Vertex AI с использованием ключа учётной записи сервиса. Вызывает развёрнутый вами агент ADK для анализа или проверки фактов в тексте документа.
• Использует Gemini для интеллектуального форматирования ответов, делая результаты удобочитаемыми.

Код.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;
}

Этот файл связывает ваш пользовательский интерфейс Docs с логикой ADK, описанной выше. Он позволяет запускать аудит непосредственно из настраиваемого меню Docs. На высоком уровне он выполняет следующие действия:

• Добавляет пользовательское меню в Google Docs под названием «Инструменты аудита ИИ».
• Извлекает текст вашего документа и отправляет его вашему агенту ADK для анализа.
• Отображает результаты аудита, созданные ИИ, обратно в документ.

Шаг 3: Создание учетной записи службы

При интеграции функции вызова агента в документ Google Doc необходимо предоставить документу Google Doc идентификатор, чтобы у него была правильная роль для вызова агента, развёрнутого в Agent Engine. Для этого мы будем использовать учётную запись службы с правильной ролью: roles/aiplatform.user .

В Cloud Shell выполните следующий скрипт шаг за шагом:

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"

Это позволит создать учетную запись службы с правильными разрешениями.

Мы сгенерируем JSON-ключ для учётной записи сервиса. Он будет использоваться вашим проектом Apps Script для аутентификации. Чтобы получить ключ, выполните следующие действия:

1. В консоли Google Cloud перейдите в раздел IAM и администрирование > Учетные записи служб .
2. Щелкните по конкретной учетной записи службы, которую вы только что создали.
3. Перейдите на вкладку «Ключи».
4. Нажмите Добавить ключ → Создать новый ключ.
5. Выберите JSON, затем нажмите Создать.
6. JSON-файл будет загружен автоматически. Сохраните его. Вы вставите его содержимое в свойства скрипта в следующем разделе.

Шаг 4: Добавьте свойства скрипта

Вернитесь в редактор Apps Script в Google Doc.

Чтобы подключить свой скрипт к развернутым ресурсам, перейдите в Project Settings → Script Properties → Add Script Property .

Добавьте следующее в свойства скрипта:

1. LOCATION : регион развёртывания Vertex AI. Например, us-central1
2. GEMINI_MODEL_ID : модель Gemini. Используйте значение: gemini-2.5-flash
3. REASONING_ENGINE_ID : идентификатор развёрнутого агента ADK. Его можно получить из параметра «Agent Engine» в консоли для конкретного развёрнутого агента. Вы увидите имя ресурса для развёрнутого агента. Идентификатор агента — это последнее числовое значение в имени ресурса (т.е. RESOURCE_ID ). Например, projects/SOME_ID/locations/REGION/reasoningEngines/ RESOURCE_ID
4. SERVICE_ACCOUNT_KEY : Скопируйте все содержимое ключа JSON, который вы загрузили для учетной записи службы, созданной на предыдущем шаге.

Нажмите Сохранить свойства скрипта.

Шаг 5: Добавьте библиотеку OAuth2

Нашему проекту Apps Script нужна библиотека OAuth2 для аутентификации вызовов API.

Чтобы добавить его:

1. Перейти в Services → Libraries
2. Нажмите Add a Library
3. Введите идентификатор скрипта: 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

Шаг 6: Тестирование агента проверки фактов в Google Docs

Мы находимся на последнем этапе тестирования агента в Google Docs. Для этого выполните следующие действия:

1. В редакторе Apps Script выполните функцию onOpen() один раз. Это добавит новое меню «Инструменты аудита ИИ» в Google Docs.
2. Вернитесь в документ. В главном меню вы увидите дополнительный пункт под названием AI Audit Tools . Нажмите на него, а затем Run AI Audit .

Вот пример запуска:

6. Уборка

Чтобы избежать постоянных списаний с вашего аккаунта Google Cloud, важно удалить ресурсы, которые мы создали во время этого семинара.

Если вам больше не нужно развертывание агента в Agent Engine, вы можете удалить его, выполнив указанные ниже действия:

1. Перейдите на страницу Vertex AI Agent Engine в Google Cloud Console.
2. Найдите агента, которого вы хотите удалить, из списка развернутых агентов.
3. Нажмите на меню из трех точек (дополнительные действия) рядом с именем агента.
4. В раскрывающемся меню выберите Удалить .
5. Подтвердите удаление, нажав «Удалить агента» в диалоговом окне подтверждения.

Рекомендуется также удалить учетную запись службы.

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

7. Поздравления

Вы развернули своего агента ИИ, подключили его к Google Docs и увидели его в действии: он анализирует, анализирует и резюмирует информацию прямо там, где находится ваш контент. То, что мы создали, — это не просто отдельная демонстрация. Это основа для интеллектуального взаимодействия с помощью агентов в Google Workspace.

Объединив возможности рассуждения ADK с генеративными моделями Gemini, мы фактически превратили Google Docs в живого, думающего помощника, который может читать, проверять и улучшать ваш текст с учетом контекста.

Тот же шаблон естественным образом распространяется на Таблицы, Презентации, Диск и Gmail. Представьте себе агентов, которые:

• Аудит финансовых данных и выявление несоответствий в таблицах
• Автоматически создавайте презентации и резюме в Slides
• Интеллектуальная маркировка и организация документов на Диске
• Или даже составляйте черновики и проверяйте факты писем прямо в Gmail.

Эта демонстрация закладывает основу для создания агентных рабочих процессов, которые легко интегрируются в ваши повседневные инструменты Workspace, превращая статические документы в динамических инструментов для совместной работы ИИ.

Справочные документы

• Комплект для разработки агентов
• Агент Движок