Планируйте поездки с помощью ИИ-агента, доступного в Google Workspace

Уровень программирования: продвинутый
Продолжительность: 45 минут
Тип проекта: дополнение Google Workspace, расширяющее возможности Chat, Gmail, Календаря, Диска, Документов, Таблиц и Презентаций.

В этом руководстве показано, как опубликовать ИИ-агентов в Google Workspace в виде дополнений Google Workspace, используя Apps Script или конечные точки HTTP. После публикации дополнения пользователи смогут взаимодействовать с ИИ-агентами в своих рабочих процессах.

Обзор

В этом руководстве вы развернете образец Travel Concierge из Agent Development Kit (ADK). Travel Concierge – это многоагентный ИИ, который использует такие инструменты, как Places API платформы Google Карт, Google Search Grounding и сервер Model Context Protocol (MCP).

По умолчанию ADK предоставляет разработчикам интерфейсы чата и текстовые интерфейсы. В этом руководстве вы узнаете, как добавить графический интерфейс пользователя (GUI) в приложения Google Workspace, к которому ваши пользователи смогут получить доступ непосредственно в Chat, Gmail, Календаре, на Диске, в Документах, Таблицах и Презентациях.

• 

  Рисунок 1. ИИ-агент в Chat помогает придумать идеи для путешествия.

• 

  Рисунок 2. Использование ИИ-агента из Gmail для планирования поездки на основе контекста выбранного письма.

Цели

• Настройте среду.
• Разверните ИИ-агента.
• Настройте проект.
• Развертывание в Gmail, Календаре, на Диске, в Документах, Таблицах и Презентациях.
• Разверните приложение в Chat.
• Проверьте решение.

Об этом решении

Это решение основано на следующих ключевых технологиях: ADK, Google Cloud и API Google Workspace, Vertex AI Agent Engine и фреймворк карточек.

Интерфейсы Chat и других приложений (Gmail, Календаря, Диска, Документов, Таблиц, Презентаций) отличаются, поскольку в них реализованы разные функции и ограничения.

Функции

Следующие функции приложения "Консьерж по путешествиям" являются общими для всех приложений Google Workspace:

• Постоянные сеансы пользователей. Сеансы управляются Vertex AI для обеспечения постоянства. У каждого пользователя один сеанс для всех приложений Workspace. Пользователи могут вручную сбросить сеанс, чтобы начать новый разговор.

• Расширенные возможности обмена сообщениями. Пользователи отправляют текстовые сообщения и получают ответы с форматированным текстом и виджетами карточек.

• Обработка ошибок. Непредвиденные ошибки обрабатываются корректно с помощью настраиваемых повторных попыток и статусов в ответах.

В приложении Chat есть следующие дополнительные функции:

• Мультимодальные сообщения. Пользователи могут отправлять сообщения с прикрепленными файлами, в том числе аудио и видео, записанными прямо в чат-группе.

• Более наглядные ответы. Ответы могут содержать более сложные виджеты, например карусели с изображениями, благодаря функциям фреймворка Card, предназначенным только для чата, и большему пространству для отрисовки.

В других приложениях есть следующие дополнительные функции:

• Контекст профиля Google. Пользователи могут отправлять сообщения с информацией из профиля (в этом примере – только с датой рождения).

• Контекст Gmail. Пользователи могут отправлять письма с помощью электронной почты (в этом примере ограничено одной темой и текстом).

• Доступ к прямой переписке агента в Chat. Пользователи могут открыть прямую переписку в приложении Chat в новой вкладке одним нажатием кнопки.

Архитектура

Приложение Travel Concierge получает и обрабатывает события взаимодействия с дополнениями Google Workspace из приложений Google Workspace, использует Vertex AI для запросов к ИИ-агенту ADK и управления сеансами пользователей, а также полагается на API Google Cloud и Google Workspace для сбора контекста и отображения ответов.

На приведенных ниже диаграммах показан основной путь пользователя: отправка сообщения ИИ-агенту.

HTTP

• 

  Рисунок 3. Приложение Chat дополняет контекст прикрепленными файлами из сообщения пользователя и отправляет набор сообщений с историей взаимодействий с субагентом и окончательным ответом в хронологическом порядке.

• 

  Рисунок 4. Приложение, не относящееся к Chat, дополняет контекст профилем Google пользователя и выбранным элементом и показывает разделы с историей взаимодействий с субагентом и окончательным ответом в обратном хронологическом порядке.

Apps Script

• 

  Рисунок 3. Приложение Chat дополняет контекст прикрепленными файлами из сообщения пользователя и отправляет набор сообщений с историей взаимодействий с субагентом и окончательным ответом в хронологическом порядке.

• 

  Рисунок 4. Приложение, не относящееся к Chat, дополняет контекст профилем Google пользователя и выбранным элементом и показывает разделы с историей взаимодействий с субагентом и окончательным ответом в обратном хронологическом порядке.

Требования

• Аккаунт Google Workspace версии Business или Enterprise с доступом к Google Chat.

• Веб-браузер с доступом к интернету.

• Предварительные условия для ИИ-агента Travel Concierge ADK

  • Python 3.10 или более поздней версии. Инструкции по установке можно найти на официальном сайте Python.
  • uv. Инструкции по установке можно найти на официальном uvсайте.
  • Google Cloud CLI. Инструкции по установке приведены на официальном сайте Google Cloud.

Подготовка среды

В этом разделе рассказывается, как создать и настроить проект Google Cloud.

Как создать проект Google Cloud

Google API Console

1. В Google API Console нажмите на значок меню > IAM & Admin (IAM и администрирование) > Create a Project (Создать проект).

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

2. В поле Project Name (Имя проекта) введите информативное название проекта.

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

3. В поле Местоположение нажмите Обзор, чтобы посмотреть возможные местоположения для проекта. Затем нажмите Выбрать.
   Внимание! Не можете найти организацию Google Workspace?
   Это означает, что вы не вошли в аккаунт Google Workspace. Некоторые функции, описанные в документации для разработчиков Google Workspace, доступны только в проектах, связанных с организацией.
4. Нажмите Создать. Google API Console перейдет на страницу "Панель управления", и ваш проект будет создан в течение нескольких минут.

gcloud CLI

В одной из следующих сред разработки получите доступ к Google Cloud CLI (gcloud):

• Cloud Shell: Чтобы использовать онлайн-терминал с уже настроенным gcloud CLI, активируйте Cloud Shell.
  Активировать Cloud Shell
• Локальная оболочка. Чтобы использовать локальную среду разработки, установите и инициализируйте gcloud CLI.
  Чтобы создать облачный проект, используйте команду gcloud projects create:

  gcloud projects create PROJECT_ID

  Замените PROJECT_ID, указав идентификатор проекта, который хотите создать.

Включите оплату для облачного проекта

Если вам не удается связать платежный аккаунт, у вас нет необходимых разрешений. Подробнее о разрешениях, необходимых для включения оплаты…

Google API Console

1. В Google API Console выберите Оплата. Нажмите Меню > Оплата > Мои проекты.

   Перейти к оплате проектов

2. В разделе Выберите организацию выберите организацию, связанную с вашим облачным проектом Google Cloud.
3. В строке проекта откройте меню Действия (), нажмите Изменить платежные данные и выберите платежный аккаунт Cloud.
4. Нажмите Выбрать аккаунт.

gcloud CLI

1. Чтобы получить список доступных платежных аккаунтов, выполните следующую команду:

   gcloud billing accounts list

2. Чтобы связать платежный аккаунт с проектом Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Замените следующее:

   • PROJECT_ID – это идентификатор проекта для облачного проекта, для которого вы хотите включить оплату.
   • BILLING_ACCOUNT_ID – это идентификатор платежного аккаунта, который нужно связать с проектом Google Cloud.

Как включить API Google Cloud

HTTP

1. В Google API Console включите API Vertex AI, Places, People, Google Chat, Gmail, Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry, Cloud Run, дополнений Google Workspace и Cloud Resource Manager.

   Как включить API

2. Убедитесь, что вы включаете API в нужном облачном проекте, и нажмите Далее.

3. Убедитесь, что вы включаете нужные API, и нажмите Включить.

Apps Script

1. В Google API Console включите Vertex AI, Places, People, Google Chat и Cloud Resource Manager API.

   Как включить API

2. Убедитесь, что вы включаете API в нужном облачном проекте, и нажмите Далее.

3. Убедитесь, что вы включаете нужные API, и нажмите Включить.

Как получить ключ API мест платформы Google Карт

1. В Google API Console откройте страницу Google Maps Platform > Keys & Credentials (Платформа Google Карт > Ключи и учетные данные).

   Перейти к настройкам ключей и учетных данных

2. В диалоговом окне Начало работы с платформой Google Карт появится созданный вами ключ API – буквенно-цифровая строка. Эта строка понадобится вам в следующих разделах.

Примечание. Если у вас уже есть подходящий ключ API, то вместо диалогового окна Начало работы с платформой Google Карт будет показан список ключей API. Нажмите Показать ключ, чтобы увидеть ключ.

Как создать сервисный аккаунт в консоли Google Cloud

Создайте сервисный аккаунт с ролью Vertex AI User, выполнив следующие действия:

Google Cloud Console

1. В консоли Google Cloud нажмите на значок меню > IAM и администрирование > Сервисные аккаунты.

   Перейти на страницу сервисных аккаунтов

   Остальные действия выполняются в консоли Google Cloud.

2. Выберите проект Google Cloud.
3. Нажмите Создать сервисный аккаунт.
4. Введите название сервисного аккаунта, которое будет показываться в консоли Google Cloud.
   Примечание. По умолчанию Google создает уникальный идентификатор сервисного аккаунта на основе его названия. Вы можете изменить идентификатор в поле идентификатора сервисного аккаунта. Его нельзя будет изменить в дальнейшем.
5. Если вы не хотите настраивать контроль доступа сейчас, нажмите Готово, чтобы завершить создание сервисного аккаунта. Чтобы настроить контроль доступа сейчас, нажмите Создать и продолжить и перейдите к следующему шагу.
   Примечание. Предоставление контроля доступа здесь влияет только на ресурсы Google Cloud. Ресурсы Google Workspace (например, Google Таблицы и Google Диск) настраиваются и предоставляются отдельно.
6. Необязательно: назначьте сервисному аккаунту роли, чтобы предоставить доступ к ресурсам проекта Google Cloud в дополнение к ресурсам Google Workspace. Подробнее об управлении доступом к проектам, папкам и организациям…
7. Нажмите Продолжить.
8. Необязательно: укажите пользователей или группы, которые могут управлять этим сервисным аккаунтом и выполнять с ним действия. Подробнее о представлении сервисного аккаунта…
9. Нажмите Готово, чтобы завершить создание сервисного аккаунта.

   Запишите адрес электронной почты сервисного аккаунта.

gcloud CLI

1. Создайте сервисный аккаунт:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Необязательно: назначьте сервисному аккаунту роли, чтобы предоставить доступ к ресурсам проекта Google Cloud в дополнение к ресурсам Google Workspace. Подробнее об управлении доступом к проектам, папкам и организациям…

Сервисный аккаунт появится на странице сервисных аккаунтов. Затем создайте закрытый ключ для сервисного аккаунта.

Как создать закрытый ключ

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

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

Чтобы создать и скачать закрытый ключ для сервисного аккаунта, выполните следующие действия:

1. В консоли Google Cloud перейдите в меню > IAM и администрирование > Сервисные аккаунты.

   Перейти на страницу сервисных аккаунтов

   Остальные действия выполняются в консоли Google Cloud.

2. Выберите проект Google Cloud.
3. Нажмите на адрес электронной почты сервисного аккаунта, для которого вы хотите создать ключ.
4. Откройте вкладку Ключи.
5. Нажмите на раскрывающееся меню Добавить ключ и выберите Создать ключ.
6. В качестве типа ключа выберите JSON и нажмите Создать.

   Будет сгенерирована новая пара открытого и закрытого ключей, которая будет скачана на ваш компьютер в виде файла ключа сервисного аккаунта. Сохраните скачанный JSON-файл как credentials.json в рабочем каталоге. Этот файл – единственная копия ключа. После того как вы скачаете файл ключа, повторно скачать его будет нельзя. Информацию о том, как безопасно хранить ключ, можно найти в статье Рекомендации по управлению ключами сервисных аккаунтов.

Подробнее о сервисных аккаунтах в документации по Google Cloud IAM…

Как настроить окно запроса доступа OAuth

Для дополнений Google Workspace требуется настроить окно запроса доступа. Настройка окна запроса доступа OAuth для дополнения определяет, что Google показывает пользователям.

1. В консоли API Google нажмите на значок меню > Платформа аутентификации Google > Брендинг.

   Перейти к брендингу

2. Если вы уже настроили платформу аутентификации Google, вы можете задать следующие настройки окна запроса доступа OAuth в разделах Брендинг, Аудитория и Доступ к данным. Если вы видите сообщение Google Auth platform not configured yet (Платформа Google Auth ещё не настроена), нажмите Get Started (Начать):
1. В разделе Информация о приложении в поле Название приложения введите название приложения.
2. В поле Электронный адрес службы поддержки укажите адрес, по которому пользователи смогут обращаться с вопросами о согласии.
3. Нажмите Далее.
4. В разделе Аудитория выберите Внутренние.
5. Нажмите Далее.
6. В разделе Контактная информация укажите адрес электронной почты, на который вы хотите получать уведомления об изменениях в проекте.
7. Нажмите Далее.
8. В разделе Завершение ознакомьтесь с Правилами в отношении пользовательских данных сервисов API Google и, если вы согласны с ними, выберите Я принимаю Правила в отношении пользовательских данных сервисов API Google.
9. Нажмите Продолжить.
10. Нажмите Создать.
3. Пока вы можете пропустить добавление областей действия. В будущем, когда вы будете создавать приложение для использования за пределами организации Google Workspace, вам нужно будет изменить Тип пользователя на Внешний. Затем добавьте области авторизации, необходимые вашему приложению. Подробнее о том, как настроить согласие OAuth…

Как развернуть ИИ-агента ADK Travel Concierge

1. Если вы ещё не сделали этого, выполните аутентификацию в аккаунте Google Cloud и настройте интерфейс командной строки Google Cloud так, чтобы он использовал ваш облачный проект.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   Замените PROJECT_ID идентификатором созданного вами облачного проекта.

2. Скачать этот репозиторий GitHub

   Скачать

3. В предпочитаемой локальной среде разработки извлеките скачанный архив и откройте каталог adk-samples/python/agents/travel-concierge.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/travel-concierge

4. Создайте новый сегмент Cloud Storage, предназначенный для ИИ-агента ADK.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   Замените следующее:

   1. CLOUD_STORAGE_BUCKET_NAME с уникальным названием сегмента, который вы хотите использовать.
   2. PROJECT_ID, указав идентификатор созданного вами облачного проекта.
   3. PROJECT_LOCATION с местоположением созданного вами облачного проекта.

5. Задайте следующие переменные среды:

   export GOOGLE_GENAI_USE_VERTEXAI=1
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_PLACES_API_KEY=PLACES_API_KEY
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
   export TRAVEL_CONCIERGE_SCENARIO=travel_concierge/profiles/itinerary_empty_default.json

   Замените следующее:

   1. PROJECT_ID, указав идентификатор созданного вами облачного проекта.
   2. PROJECT_LOCATION с местоположением созданного вами облачного проекта.
   3. PLACES_API_KEY строкой созданного вами ключа API.
   4. CLOUD_STORAGE_BUCKET_NAME с названием созданного вами сегмента.

6. Установите и разверните ИИ-агента ADK.

   uv sync --group deployment
   uv run python deployment/deploy.py --create

7. Из последнего напечатанного журнала извлеките номер проекта и идентификатор движка (PROJECT_NUMBER и ENGINE_ID соответственно). Они понадобятся вам позже для настройки проекта.

   Created remote agent: projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENGINE_ID

Проверьте образец кода

Перед настройкой проекта вы можете ознакомиться с образцами кода на GitHub.

Python

Посмотреть на GitHub

Apps Script

Посмотреть на GitHub

Как создать и настроить проект

Python

1. Скачать этот репозиторий GitHub

   Скачать

2. В предпочитаемой локальной среде разработки извлеките скачанный архив и откройте каталог add-ons-samples/python/travel-adk-ai-agent.

   unzip add-ons-samples-main.zip
   cd add-ons-samples-main/python/travel-adk-ai-agent

3. Переместите JSON-файл ключа credentials.json из сервисного аккаунта, скачанного на предыдущих этапах, в каталог проекта.

4. В Google API Console перейдите в раздел Cloud Run:

   Перейти в Cloud Run

5. Нажмите Написать функцию.

6. На странице Создать сервис настройте функцию:

   1. В поле Название сервиса введите travel-concierge-app.
   2. В списке Регион выберите местоположение созданного вами облачного проекта PROJECT_LOCATION.
   3. В разделе URL конечной точки нажмите .
   4. В списке Среда выполнения выберите последнюю версию Python.
   5. В разделе Аутентификация выберите Разрешить публичный доступ.
   6. В разделе Containers, Volumes, Networking, Security (Контейнеры, тома, сети, безопасность) в подразделе Resources (Ресурсы):
      1. В поле Память выберите 1 ГБ.
      2. В поле CPU выберите 2.
   7. Нажмите Создать и подождите, пока Cloud Run создаст сервис. Консоль перенаправит вас на вкладку Источник.

7. В предпочитаемой локальной среде разработки разверните источник проекта:

   gcloud run deploy travel-concierge-app --quiet --source . \
       --region PROJECT_LOCATION  \
       --function adk_ai_agent  \
       --set-env-vars LOCATION=LOCATION,PROJECT_NUMBER=PROJECT_NUMBER,ENGINE_ID=ENGINE_ID,BASE_URL=BASE_URL

   Замените следующее:

   1. PROJECT_LOCATION с местоположением созданной ранее функции Cloud Run.
   2. LOCATION с местоположением облачного проекта Google Cloud, созданного на предыдущих шагах, PROJECT_LOCATION.
   3. PROJECT_NUMBER – номер проекта ИИ-агента Travel Concierge ADK, развернутого на предыдущих шагах.
   4. ENGINE_ID с идентификатором системы ИИ-агента из Travel Concierge ADK, развернутого на предыдущих шагах.
   5. BASE_URL с URL конечной точки, который вы скопировали ранее.

Apps Script

Чтобы создать проект Apps Script и настроить его для использования развернутого ИИ-агента Travel Concierge ADK:

1. Нажмите кнопку ниже, чтобы открыть проект Travel Concierge ADK ИИ-агент в Apps Script.
   Открыть проект

2. Нажмите на значок меню Обзор, а затем Создать копию.

3. Укажите название копии проекта Apps Script:

   1. Нажмите Копия ИИ-агента Travel Concierge ADK.
   2. В поле Название проекта введите Travel Concierge ADK AI Agent.
   3. Нажмите Переименовать.

4. В проекте Apps Script нажмите Редактор и переместите файл VertexAi.gs вверх, чтобы он оказался над файлом AgentHandler.gs, с помощью действия Переместить файл вверх.

5. В проекте Apps Script нажмите Настройки проекта, выберите Изменить свойства скрипта и нажмите Добавить свойство скрипта, чтобы добавить следующие свойства скрипта:

6. ENGINE_ID с идентификатором поисковой системы ИИ-агента Travel Concierge ADK, развернутого на предыдущих шагах, ENGINE_ID.

7. LOCATION с местоположением облачного проекта Google Cloud, созданного на предыдущих шагах, PROJECT_LOCATION.

8. PROJECT_NUMBER с номером проекта ИИ-агента Travel Concierge ADK, развернутого на предыдущих этапах, PROJECT_NUMBER.

9. SERVICE_ACCOUNT_KEY с ключом JSON из сервисного аккаунта, скачанным на предыдущих этапах, например { ... }.

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

11. В проекте Apps Script нажмите Настройки проекта.

12. В разделе Проект Google Cloud Platform (GCP) нажмите Изменить проект.

13. В поле Номер проекта GCP вставьте номер проекта ИИ-агента Travel Concierge ADK, развернутого на предыдущих шагах, PROJECT_NUMBER.

14. Нажмите Настроить проект. Облачный проект и проект Apps Script теперь связаны.

Развертывание в Gmail, Календаре, на Диске, в Документах, Таблицах и Презентациях

Python

Используйте развертывание дополнения Google Workspace, чтобы установить образец проекта во все приложения Google Workspace (кроме Google Chat) и включить тестирование.

1. В предпочитаемой локальной среде разработки откройте файл deployment.json из исходного кода проекта и замените все вхождения $BASE_URL значением BASE_URL, URL конечной точки, которое вы скопировали на предыдущих шагах.

2. Создайте развертывание дополнения Google Workspace с именем travel-concierge-addon:

   gcloud workspace-add-ons deployments create travel-concierge-addon \
       --deployment-file=deployment.json

3. Установите дополнение Google Workspace:

   gcloud workspace-add-ons deployments install travel-concierge-addon

Apps Script

Установите проект Apps Script во все приложения Google Workspace (кроме Google Chat), чтобы включить тестирование.

1. В проекте Apps Script нажмите Развернуть > Тестовые развертывания, а затем Установить.

Дополнение теперь доступно на боковых панелях приложений Google Workspace.

Как развернуть приложение в Chat

Python

Установите образец проекта в Chat, используя URL конечной точки, чтобы включить тестирование.

1. В API Console выполните поиск по запросу Google Chat API, нажмите Google Chat API, затем Manage (Управление) и Configuration (Настройки).

   Перейти на страницу конфигурации Google Chat API

2. Настройте приложение Chat:

   1. В поле Название приложения введите Travel ADK AI Agent.
   2. В поле Avatar URL (URL аватара) введите https://goo.gle/3SfMkjb.
   3. В поле Description (Описание) введите Travel ADK AI Agent.
   4. В разделе Настройки подключения выберите URL конечной точки HTTP.
   5. В разделе Триггеры выберите Использовать общий URL конечной точки HTTP для всех триггеров.
   6. В поле URL конечной точки HTTP вставьте URL конечной точки, который вы скопировали ранее, BASE_URL.
   7. Зарегистрируйте быструю команду, которую использует полностью реализованное приложение Chat:
      1. В разделе Команды нажмите Добавить команду.
      2. В поле Идентификатор команды введите 1.
      3. В поле Описание введите Reset session.
      4. В разделе Тип команды выберите Быстрая команда.
      5. В поле Название введите Reset session.
      6. Нажмите Готово. Быстрая команда зарегистрирована и указана в списке.
   8. В разделе Видимость выберите Сделать это приложение Chat доступным для определенных пользователей и групп в домене Workspace и введите свой адрес электронной почты.
   9. В разделе Журналы выберите Регистрировать ошибки в Logging.
   10. Нажмите Сохранить.

Apps Script

Установите проект Apps Script в Chat, используя идентификатор развертывания HEAD, чтобы включить тестирование.

1. В проекте Apps Script нажмите Deploy (Развернуть) > Test deployments (Тестовые развертывания), а затем Copy (Копировать) в разделе Head Deployment ID (Идентификатор развертывания HEAD).

2. В API Console выполните поиск по запросу Google Chat API, нажмите Google Chat API, затем Manage (Управление) и Configuration (Настройки).

   Перейти на страницу конфигурации Google Chat API

3. Настройте приложение Chat:

   1. В поле Название приложения введите Travel ADK AI Agent.
   2. В поле Avatar URL (URL аватара) введите https://goo.gle/3SfMkjb.
   3. В поле Description (Описание) введите Travel ADK AI Agent.
   4. В разделе Настройки подключения выберите Скрипт приложений.
   5. В поле Deployment ID (Идентификатор развертывания) вставьте идентификатор развертывания головного устройства, скопированный ранее.
   6. Зарегистрируйте быструю команду, которую использует полностью реализованное приложение Chat:
      1. В разделе Команды нажмите Добавить команду.
      2. В поле Идентификатор команды введите 1.
      3. В поле Описание введите Reset session.
      4. В разделе Тип команды выберите Быстрая команда.
      5. В поле Название введите Reset session.
      6. Нажмите Готово. Быстрая команда зарегистрирована и указана в списке.
   7. В разделе Видимость выберите Сделать это приложение Chat доступным для определенных пользователей и групп в домене Workspace и введите свой адрес электронной почты.
   8. В разделе Журналы выберите Регистрировать ошибки в Logging.
   9. Нажмите Сохранить.

Теперь приложение доступно в Google Chat.

1. Откройте Google Chat.

   Перейти в Google Chat

2. Создайте чат-группу в Chat:

   1. Нажмите Новый чат.
   2. Введите название приложения и выберите его в результатах поиска Travel ADK AI Agent.
   3. В диалоговом окне Install app нажмите Установить приложение.
   4. Диалоговое окно Install app закроется, и будет выбрана созданная чат-группа.

Приложение Chat готово отвечать на сообщения.

Как протестировать агента

1. Откройте Gmail.

   Перейти в Gmail

2. Отправьте себе следующее письмо:

   • Тема: You need to travel to Paris
   • Текст письма: Please be there between 11/25/2025 and 11/30/2025!

3. На боковой панели откройте дополнение Travel ADK ИИ-агент.

4. Нажмите Предоставить разрешения, чтобы завершить настройку дополнения.

5. Нажмите Отправить, после того как настроите следующий запрос к агенту:

   • Сообщение: Please help me plan this travel!
   • Контекст: выберите Текущий адрес электронной почты.

   На боковой панели появится ответ агента.

   

6. Нажмите Открыть Chat, чтобы перейти в чат с прямыми сообщениями.

7. Нажмите + > Сбросить сеанс.

   Вы получите новое сообщение с подтверждением: OK, let's start from the beginning, what can I help you with?

8. Отправьте сообщение Give me ideas.

   Вы получаете новые сообщения с ответом агента.

   

9. Отправьте сообщение I want to go there! после загрузки фотографии любого места, например Эйфелевой башни.

   Вы получаете новые сообщения с ответом агента.

   

Примечание. Дополнение ИИ-агент Travel ADK также можно открыть на боковой панели в Календаре, на Диске, в Документах, Таблицах и Презентациях, как и в Gmail.

Ограничения

HTTP

В приложениях Google Workspace, кроме Chat, у ИИ-агента есть следующие ограничения:

• Синхронность. Боковые панели можно обновлять только в ответ на действия пользователя, поэтому ответы ИИ-агента отображаются только после полного завершения (без потоковой передачи).

• Время ожидания истекает. Если обновление боковой панели занимает больше нескольких минут, время ожидания истекает.

В Chat таких ограничений нет.

Apps Script

Во всех приложениях Google Workspace агент ИИ вызывает Vertex AI REST API с помощью UrlFetchApp, что приводит к следующим ограничениям:

• Синхронный режим. Ответы ИИ-агента возвращаются только после полного завершения (без потоковой передачи).

• Время ожидания может истечь. Если ИИ-агенту требуется больше минуты на выполнение запроса, время ожидания истекает.

Настройка

Это решение поддерживает ИИ-агентов ADK, размещенных в Vertex AI Agent Engine, подмножество интерфейсов приложений Google Workspace и отрисовку ответов, характерную для образца Travel Concierge. Решение использует расширяемую структуру, поэтому вы можете настроить его, изменив следующие файлы:

Python

• main.py: – определяет основные интерфейсы и логику взаимодействия с пользователем (обработчики событий Google Workspace). Типичным примером расширения является включение документов на Диске в качестве контекстной функции для приложения "Диск", аналогично тому, как это сделано с письмами Gmail для приложения Gmail.

• vertex_ai.py: управляет сеансами, ответами и ошибками ИИ-агента, а также определяет интерфейсы, которые нужно реализовать для поддержки взаимодействия с агентом и отрисовки ответов. Обычно расширения добавляют поддержку нескольких сеансов для отдельных разговоров с пользователями и других платформ управления ИИ-агентами.

• agent_handler.py реализует интерфейсы, относящиеся к Vertex AI, которые определены в файле vertex_ai.py, для приложений Chat и других приложений. Например, можно добавить кнопки, чтобы пользователи могли отправлять отзывы об ответах ИИ-агента.

• google_workspace.py: реализует взаимодействие с платформой управления агентами, не относящимися к ИИ, с помощью вызовов API. В этом примере для сбора контекстной информации и выполнения действий используются только Google Workspace API. Типичный пример расширения – добавление функций для получения коммерческих данных из Google Календаря или системы управления взаимоотношениями с клиентами (CRM).

• travel_agent_ui_render.gs: реализует отрисовку ответов для суб-агентов и приложений Workspace, относящихся к Travel Concierge. Типичные расширения могут включать поддержку новых вариантов отображения ответов для графического представления вариантов перелетов и других ИИ-агентов.

Apps Script

• Code.gs: – определяет основные интерфейсы и логику взаимодействия с пользователем (обработчики событий Google Workspace). Типичным примером расширения является включение документов на Диске в качестве контекстной функции для приложения "Диск", аналогично тому, как это сделано с письмами Gmail для приложения Gmail.

• VertexAi.gs: управляет сеансами, ответами и ошибками ИИ-агента, а также определяет интерфейсы, которые необходимо реализовать для поддержки взаимодействия с агентом и отрисовки ответов. Обычно расширения добавляют поддержку нескольких сеансов для отдельных разговоров с пользователями и других платформ управления ИИ-агентами.

• AgentHandler.gs: реализует интерфейсы, относящиеся к Vertex AI, которые определены в файле VertexAi.gs, в конкретных случаях приложений Chat и не относящихся к Chat. Например, можно добавить кнопки, чтобы пользователи могли отправлять отзывы об ответах ИИ-агента.

• GoogleWorkspace.gs: реализует взаимодействие платформы управления агентами, не использующими ИИ, с помощью вызовов API. В этом примере для сбора контекстной информации и выполнения действий используются только Google Workspace API. Типичный пример расширения – добавление функций для получения коммерческих данных из Google Календаря или системы управления взаимоотношениями с клиентами (CRM).

• TravelAgentUiRender.gs: – реализует отрисовку ответов для субагентов и приложений Workspace, относящихся к Travel Concierge. Типичные расширения могут включать поддержку новых вариантов отображения ответов для графического представления вариантов перелетов и других ИИ-агентов.

Организовать

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

Внимание! Удаление проекта приведет к следующим последствиям:

• Все данные в проекте будут удалены. Если вы использовали существующий проект, то при его удалении также будут удалены все другие данные, которые вы добавили в этот проект.
• Пользовательские идентификаторы проектов будут утеряны. При создании этого проекта вы могли задать собственный идентификатор проекта, который хотите использовать в дальнейшем. Чтобы сохранить URL, в которых используется идентификатор проекта, например URL на сайте appspot.com, удалите выбранные ресурсы внутри проекта, а не весь проект.

Если вы планируете изучить несколько руководств и кратких руководств, повторное использование проектов поможет вам не превысить лимиты на количество проектов.

1. В Google API Console перейдите на страницу Управление ресурсами. Нажмите Меню > IAM и администрирование > Управление ресурсами.

   Перейти в Менеджер ресурсов

2. В списке проектов выберите проект, который хотите удалить, и нажмите Удалить .
3. В диалоговом окне введите идентификатор проекта и нажмите Закрыть, чтобы удалить проект.

Статьи по теме

• Как проверить факты с помощью ИИ-агента ADK и модели Gemini
• Интеграция основных концепций ИИ в приложения Chat
• Ответы на вопросы на основе чатов с ИИ-приложением Gemini
• Как реагировать на инциденты с помощью Google Chat, Vertex AI, Apps Script и аутентификации пользователей
• Управляйте проектами с помощью Google Chat, Vertex AI и Firestore
• Как создать приложение для Chat в виде дополнения Google Workspace с помощью Apps Script