Эта страница переведена с помощью Cloud Translation API.

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

1. Введение

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

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

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

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

Разработайте агента проверки фактов на основе ИИ, используя комплект разработки агентов (Agent Development Kit).
Разверните агент в Agent Engine — полностью управляемой среде для масштабируемого запуска агентов.
Интегрируйте этот агент в Google Docs для проверки фактов в тексте документа.

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

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

Что вы будете делать

Разработайте, создайте и разверните агента, который будет проверять факты внутри документа Google Docs.

Что вы узнаете

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

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

Веб-браузер Chrome
Аккаунт Gmail
Облачный проект с включенной функцией выставления счетов.

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

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

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

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

Изображение кнопки «Активировать Cloud Shell»

После подключения к Cloud Shell необходимо проверить, прошли ли вы аутентификацию и установлен ли идентификатор вашего проекта, используя следующую команду:

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

Включите необходимые 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 (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-интерфейс для бесперебойных вызовов к рабочим пространствам.

Почему именно Vertex AI Agent Engine?

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

Это предоставляет вашему агенту следующую информацию:

Устойчивое состояние и память
Интегрированное выполнение с помощью инструментов (например, поиск Google, модели искусственного интеллекта Vertex)
Защищенные API-интерфейсы для внешних вызовов
Ведение журналов и обеспечение наблюдаемости с помощью облачного логирования.
Встроенная поддержка оркестровки нескольких агентов.

Короче говоря, вы пишете код один раз с помощью 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 минут. В общих чертах, происходит следующее:

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

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

Шаг 3: Проверьте агента в облачной консоли (Agent Engine).

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

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

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

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

Существует несколько способов сделать это, в зависимости от того, как вам удобнее работать:

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

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

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

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

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

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

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

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

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

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

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:

AIVertex.gs – обеспечивает всю коммуникацию с Vertex AI и ADK Agent.
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 для интеллектуального форматирования ответов, делая результаты удобочитаемыми.

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

Этот файл связывает ваш пользовательский интерфейс документации с описанной выше логикой ADK. Он позволяет запускать аудит непосредственно из пользовательского меню документации. В общих чертах он делает следующее:

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

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

При интеграции функции вызова агента в документ Google Docs необходимо присвоить документу Google Docs учетную запись, обеспечивающую ему правильную роль для вызова агента, развернутого в 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 для аутентификации. Вот шаги для получения ключа:

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

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

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

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

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

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

Нажмите «Сохранить свойства сценария».

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

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

Чтобы добавить это:

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

Шаг 6: Проверьте работу агента проверки фактов в Google Docs.

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

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

Вот пример выполнения:

6. Уборка

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

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

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

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

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

7. Поздравляем!

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

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

Та же самая схема естественным образом применяется в Sheets, Slides, Drive и Gmail. Представьте себе агентов, которые:

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

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