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

Уровень кодирования : продвинутый
Продолжительность : 45 минут
Тип проекта : дополнение Google Workspace, расширяющее возможности Chat , Gmail , Calendar , Drive , Docs, Sheets и Slides .

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

Обзор

В этом руководстве мы развернём пример Travel Concierge из Agent Development Kit (ADK) . Travel Concierge — это диалоговый многоагентный ИИ, использующий такие инструменты, как API Google Maps Platform Places, Google Search Grounding и сервер Model Context Protocol (MCP).

ADK по умолчанию предоставляет разработчикам интерфейсы чата и текстового взаимодействия. В этом руководстве вы добавите графический пользовательский интерфейс (GUI) в приложения Google Workspace, к которому ваши пользователи смогут получать прямой доступ из Chat, Gmail, Calendar, Drive, Docs, Sheets и Slides.

• 

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

• 

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

Цели

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

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

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

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

Функции

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

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

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

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

Приложение «Чат» имеет следующие дополнительные функции:

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

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

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

• Контекст профиля Google: пользователи могут отправлять сообщения, содержащие информацию из их профиля (в данном примере ограниченную днями рождения).

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

• Доступ к чат-пространству агента: пользователи могут открыть пространство для прямых сообщений (DM) приложения чата в новой вкладке одним нажатием кнопки.

Архитектура

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

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

HTTP

• 

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

• 

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

Скрипт приложений

• 

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

• 

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

Предпосылки

• Учетная запись Google Workspace Business или Enterprise с доступом к Google Chat .

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

• Предварительные требования, специфичные для агента Travel Concierge ADK AI

  • Python 3.10+: Для установки следуйте инструкциям на официальном сайте Python .
  • uv : Для установки следуйте инструкциям на официальном сайте uv .
  • Google Cloud CLI: для установки следуйте инструкциям на официальном сайте Google Cloud .

Подготовьте окружающую среду

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

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

Консоль Google Cloud

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

   Перейти к созданию проекта

2. В поле «Название проекта» введите описательное название вашего проекта.

   Необязательно: чтобы изменить идентификатор проекта , нажмите «Изменить» . Идентификатор проекта нельзя изменить после его создания, поэтому выберите идентификатор, который будет соответствовать вашим потребностям на протяжении всего жизненного цикла проекта.

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

gcloud CLI

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

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

  gcloud projects create PROJECT_ID

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

Включить выставление счетов для облачного проекта

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

Консоль Google Cloud

1. В консоли Google Cloud перейдите в раздел «Оплата» . Нажмите « » > «Оплата» > «Мои проекты» .

   Перейти к выставлению счетов за мои проекты

2. В разделе Выберите организацию выберите организацию, связанную с вашим проектом Google Cloud.
3. В строке проекта откройте меню Действия ( ), нажмите Изменить выставление счетов и выберите учетную запись Cloud Billing.
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 Cloud включите API дополнений Vertex AI, Places, People, Google Chat, Gmail, Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry, Cloud Run и Google Workspace.

   Включить API

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

3. Подтвердите, что вы включаете правильные API, затем нажмите Включить .

Скрипт приложений

1. В консоли Google Cloud включите API Vertex AI, Places, People, Google Chat.

   Включить API

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

3. Подтвердите, что вы включаете правильные API, затем нажмите Включить .

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

1. В консоли Google Cloud перейдите на страницу Платформа Google Карт > Ключи и учетные данные .

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

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

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

Создайте учетную запись службы в консоли Google Cloud

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

Консоль Google Cloud

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

   Перейти к учетным записям служб

2. Нажмите Создать учетную запись службы .
3. Заполните данные учетной записи службы, затем нажмите «Создать» и продолжите .
   Примечание: По умолчанию Google создаёт уникальный идентификатор учётной записи сервиса. Если вы хотите изменить идентификатор, укажите его в поле «Идентификатор учётной записи сервиса».
4. Необязательно: назначьте роли своему сервисному аккаунту, чтобы предоставить доступ к ресурсам вашего проекта Google Cloud. Подробнее см. в разделе Предоставление, изменение и отзыв доступа к ресурсам .
5. Нажмите «Продолжить» .
6. Необязательно: введите пользователей или группы, которые смогут управлять этой учётной записью службы и выполнять с ней действия. Подробнее см. в разделе Управление олицетворением учётной записи службы .
7. Нажмите «Готово» . Запишите адрес электронной почты для учётной записи сервиса.

gcloud CLI

1. Создайте учетную запись службы:

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

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

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

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

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

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

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

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

   Перейти к учетным записям служб

2. Выберите свою учетную запись службы.
3. Нажмите Ключи > Добавить ключ > Создать новый ключ .
4. Выберите JSON , затем нажмите Создать .

   Ваша новая пара открытого и закрытого ключей будет сгенерирована и загружена на ваш компьютер в виде нового файла. Сохраните загруженный JSON-файл как credentials.json в вашем рабочем каталоге. Этот файл — единственная копия данного ключа. Сведения о безопасном хранении ключа см. в разделе Управление ключами учётной записи службы .

5. Нажмите «Закрыть» .

Дополнительную информацию об учетных записях служб см. в разделе «Учетные записи служб» в документации Google Cloud IAM .

Настройте экран согласия OAuth

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

1. В консоли Google Cloud перейдите в >Google Auth platform > Брендинг .

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

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

Развертывание агента Travel Concierge ADK AI

1. Если вы еще этого не сделали, выполните аутентификацию с помощью своей учетной записи Google Cloud и настройте Google Cloud CLI для использования вашего проекта 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. Создайте новый контейнер облачного хранилища, выделенный для агента ADK AI.

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

   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.

Питон

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

Скрипт приложений

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

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

Питон

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 Cloud перейдите в Cloud Run :

   Перейти к Cloud Run

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

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

   1. В поле «Название сервиса» введите travel-concierge-app .
   2. В списке Регион выберите местоположение созданного вами облачного проекта PROJECT_LOCATION .
   3. В разделе URL конечной точки нажмите .
   4. В списке Runtime выберите самую последнюю версию Python.
   5. В разделе Аутентификация выберите Разрешить публичный доступ .
   6. В разделе «Контейнеры», «Тома», «Сеть», «Безопасность» , в разделе «Ресурсы» :
      1. В поле Память выберите 1 GiB .
      2. В поле ЦП выберите 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 AI Agent, развернутого на предыдущих этапах.
   4. ENGINE_ID с идентификатором движка Travel Concierge ADK AI Agent, развернутого на предыдущих этапах.
   5. BASE_URL на URL конечной точки , который вы ранее скопировали.

Скрипт приложений

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

1. Нажмите следующую кнопку, чтобы открыть проект скрипта приложений Travel Concierge ADK AI Agent Apps.
   Открыть проект

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

3. Назовите свою копию проекта Apps Script:

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

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

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

6. ENGINE_ID с идентификатором движка Travel Concierge ADK AI Agent, развернутого на предыдущих этапах, ENGINE_ID .

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

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

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

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

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

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

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

14. Нажмите «Установить проект» . Теперь проекты Cloud и Apps Script связаны.

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

Питон

Используйте развертывание надстройки 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 во все приложения Google Workspace (кроме Google Chat), чтобы включить тестирование.

1. В проекте Apps Script нажмите Deploy > Test deploys , затем Install .

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

Развернуть в чате

Питон

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

1. В консоли найдите Google Chat API , нажмите Google Chat API , затем Управление и Конфигурация .

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

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

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

Скрипт приложений

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

1. В проекте Apps Script нажмите «Развернуть» > «Тестовые развертывания» , затем Скопируйте в заголовок Идентификатор развертывания .

2. В консоли найдите Google Chat API , нажмите Google Chat API , затем Управление и Конфигурация .

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

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

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

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

1. Откройте Google Чат.

   Перейти в Google Чат

2. Создайте пространство чата DM:

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

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

Протестируйте агента

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

   Перейти в Gmail

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

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

3. Откройте дополнение Travel ADK AI Agent на боковой панели.

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

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

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

   Боковая панель обновляется в соответствии с ответом агента.

   

6. Нажмите «Открыть чат» , чтобы перейти в раздел DM-чата.

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 AI Agent также можно открыть из боковой панели в Календаре, Диске, Документах, Таблицах и Презентациях, аналогично тому, как это делается в Gmail.

Ограничения

HTTP

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

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

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

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

Скрипт приложений

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

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

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

Настройка

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

Питон

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

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

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

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

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

Скрипт приложений

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

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

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

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

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

Уборка

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

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

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

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

1. В консоли Google Cloud перейдите на страницу «Управление ресурсами» . Выберите « » > «IAM и администрирование» > «Управление ресурсами» .

   Перейти к диспетчеру ресурсов

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

Похожие темы

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