Создайте приложение Google Chat с агентом Agent2UI.

На этой странице объясняется, как создать надстройку для Google Workspace, которая будет работать в Google Chat и взаимодействовать с агентом искусственного интеллекта, использующим протокол Agent2UI (A2UI) . Вы разрабатываете агента с помощью Agent Development Kit (ADK) и размещаете его в Vertex AI Agent Engine .

Агенты искусственного интеллекта автономно воспринимают окружающую среду, рассуждают и выполняют сложные многоэтапные действия для достижения заданной цели. В этом руководстве вы развернете базового агента ИИ, который возвращает статическую информацию профиля, полученную из инструмента.

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

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

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

1. Пользователь отправляет сообщение в приложение для чата, либо в личном сообщении, либо в чате.
2. Логика чат-приложения, реализованная либо в Apps Script, либо в виде веб-сервера с HTTP-конечными точками, получает и обрабатывает сообщение.
3. Агент A2UI, размещенный на платформе Vertex AI Agent Engine, получает и обрабатывает взаимодействие.
4. При желании приложение для чата или ИИ-агент могут интегрироваться с сервисами Google Workspace, такими как Календарь или Таблицы, или с другими сервисами Google, такими как Google Карты или YouTube.
5. Приложение «Чат» генерирует и отправляет адаптивные ответы асинхронно, используя API Google Chat для передачи информации о ходе работы ИИ-агента.
6. Ответы доставляются пользователю.

Цели

• Настройте свою среду.
• Разверните агент A2UI.
• Разверните приложение «Чат».
• Настройте приложение «Чат».
• Протестируйте приложение «Чат».

Предварительные требования

• Корпоративный аккаунт Google Workspace с доступом к Google Chat .
• Проект Google Cloud с включенной оплатой. Чтобы проверить, включена ли оплата в существующем проекте, см. раздел «Проверка статуса оплаты ваших проектов ». Чтобы создать проект и настроить оплату, см. раздел «Создание проекта Google Cloud» .
• Python 3.11+: Для установки следуйте инструкциям на официальном сайте Python .
• Python Poetry: Для установки следуйте инструкциям на официальном сайте Poetry .
• Google Cloud CLI: Для установки следуйте инструкциям на официальном сайте Google Cloud .

Настройте свою среду

Включите API Google Cloud.

Перед использованием API Google необходимо включить их в проекте Google Cloud. В одном проекте Google Cloud можно включить один или несколько API.

• В консоли Google Cloud включите API Google Chat, Vertex AI и Cloud Resource Manager.

  Включите API

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

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

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

   Перейти к разделу «Брендинг»

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

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

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

Консоль Google Cloud

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

   Перейдите в раздел «Учетные записи служб».

2. Click Create service account .
3. Заполните данные учетной записи службы, затем нажмите «Создать и продолжить» .
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 перейдите в menu > IAM и администрирование > Учетные записи служб .

   Перейдите в раздел «Учетные записи служб».

2. Выберите свой сервисный аккаунт.
3. Нажмите «Клавиши» > «Добавить клавишу» > «Создать новую клавишу» .
4. Select JSON , then click Create .

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

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

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

Разверните агент A2UI

1. Если вы этого еще не сделали, пройдите аутентификацию в своей учетной записи Google Cloud и настройте интерфейс командной строки 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. Загрузите репозиторий googleworkspace/add-ons-samples на GitHub, используя эту кнопку:

   Скачать репозиторий

3. В предпочитаемой вами локальной среде разработки распакуйте загруженный архив и откройте каталог add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui .

   unzip add-ons-samples-main.zip
   cd add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui

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=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

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

   1. В поле CLOUD_STORAGE_BUCKET_NAME укажите имя созданного вами хранилища (bucket).
   2. PROJECT_ID содержит идентификатор вашего облачного проекта.
   3. Укажите в поле PROJECT_LOCATION местоположение вашего облачного проекта.

6. Установите и разверните агент ADK из виртуальной среды.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. Получите идентификатор агента. Он понадобится вам позже при настройке приложения «Чат».

   python3 deployment/deploy.py --list

Создайте и настройте проект приложения «Чат».

1. Нажмите на следующую кнопку, чтобы открыть проект A2UI AI Agent Quickstart Apps Script.

   Откройте проект

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

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

   1. REASONING_ENGINE_RESOURCE_NAME содержит имя ресурса агента Vertex AI, скопированное на предыдущих шагах.
   2. SERVICE_ACCOUNT_KEY содержит JSON-ключ из учетной записи службы, загруженной на предыдущих шагах, например, { ... } .

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

5. В консоли Google Cloud перейдите в menu > IAM и администрирование > Настройки .

   Перейдите в раздел «Настройки IAM и администрирования».

6. В поле «Номер проекта» скопируйте значение.

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

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

9. В поле "Номер проекта GCP" вставьте номер проекта Google Cloud, скопированный на предыдущих шагах.

10. Нажмите «Установить проект» . Проект «Облако» и проект «Apps Script» теперь связаны.

Создайте тестовое развертывание.

Для этого проекта Apps Script вам потребуется идентификатор развертывания, чтобы вы могли использовать его на следующем шаге.

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

1. В проекте Apps Script приложения «Чат» нажмите «Развернуть» > «Проверить развертывания» .
2. В разделе «Идентификатор развертывания головного устройства» нажмите Копировать .
3. Нажмите «Готово» .

Настройте приложение «Чат».

Чтобы развернуть приложение Google Chat для тестирования, выполните следующие действия, используя развертывание Apps Script:

1. В консоли найдите Google Chat API и нажмите на него .
2. Нажмите «Управление» .

3. Нажмите «Конфигурация» и настройте приложение «Чат»:

   1. В поле «Название приложения» введите A2UI Quickstart .
   2. В поле «URL-адрес аватара» введите https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png .
   3. В поле «Описание» введите A2UI Quickstart .
   4. В разделе «Функциональность» выберите «Присоединяйтесь к пространствам и групповым беседам» .
   5. В разделе «Настройки подключения» выберите проект Apps Script .
   6. В поле «Идентификатор развертывания» вставьте ранее скопированный идентификатор развертывания Head.
   7. В разделе «Видимость» выберите «Конкретные люди и группы в вашем домене» и введите свой адрес электронной почты.

4. Нажмите « Сохранить ».

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

Протестируйте приложение для чата

Чтобы протестировать приложение «Чат», откройте личное сообщение в приложении «Чат» и отправьте сообщение:

1. Откройте Google Chat, используя учетную запись Google Workspace, которую вы указали при добавлении себя в качестве доверенного тестировщика.

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

2. Нажмите add новый чат» .
3. В поле «Добавить 1 или более человек» введите название вашего приложения для чата.

4. Выберите ваше приложение для чата из результатов поиска. Откроется личное сообщение.

5. В новом личном сообщении в приложении напишите Hello! и нажмите enter .

   Приложение «Чат» отвечает на сообщение приветственным текстом и карточкой, содержащей имя профиля, изображение и кнопку LinkedIn.

6. Необходимо обновить реализацию агента A2UI, чтобы он также начал возвращать заголовок профиля.

   В локальной среде разработки откройте файл a2ui/agent.py и раскомментируйте строку в инструменте, которая добавляет заголовок к возвращаемым данным.

   apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py

   Посмотреть на GitHub
   # Copyright 2026 Google LLC
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #     http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   
   """A2UI agent."""
   
   from google.adk.agents import LlmAgent
   from google.adk.tools.tool_context import ToolContext
   import json
   
   # The schema for any A2UI message. This never changes.
   from .a2ui_schema import A2UI_SCHEMA
   
   def get_user_profile(tool_context: ToolContext) -> str:
       """Call this tool to get the current user profile."""
       return json.dumps({
           "name": "Pierrick Voulet",
           # "title": "DevRel Engineer @ Google Workspace | Gen AI & AI Agents & Agentic AI | Automation & Digital Transformation",
           "imageUrl": "https://io.google/2024/speakers/3ea87822-3160-4d54-89dd-57e185085f79_240.webp",
           "linkedin": "https://www.linkedin.com/in/pierrick-voulet/"
       })
   
   AGENT_INSTRUCTION="""
   You are a user profile assistant. Your goal is to help users get their profile information using a rich UI.
   
   To achieve this, you MUST follow these steps to answer user requests:
   
   1.  You MUST call the `get_user_profile` tool and extract all the user profile information from the result.
   2.  You MUST generate a final a2ui UI JSON based on the user profile information extracted in the previous step."""
   
   A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f"""
   
   To generate a valid a2ui UI JSON, you MUST follow these rules:
   1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
   2.  The first part is your conversational text response.
   3.  The second part is a single, raw JSON object which is a list of A2UI messages.
   4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.
   
   To represent the user profile, you MUST use the following A2UI message types:
   1.  Buttons MUST be used to represent links (e.g., LinkedIn profile link).
   2.  Image MUST be used to represent the user's profile picture.
   
   ---BEGIN A2UI JSON SCHEMA---
   {A2UI_SCHEMA}
   ---END A2UI JSON SCHEMA---
   """
   
   root_agent = LlmAgent(
       name="user_profile",
       model="gemini-2.5-flash",
       instruction=A2UI_AND_AGENT_INSTRUCTION,
       description="An agent that returns the current user profile.",
       tools=[get_user_profile]
   )

7. Обновите ранее развернутый ADK до новой версии реализации.

   python3 deployment/deploy.py --update --resource_id=RESOURCE_ID

   Замените RESOURCE_ID на имя ресурса агента Vertex AI, скопированное на предыдущих шагах.

8. В личном сообщении в приложении напишите Hello again! и нажмите enter .

   Приложение «Чат» отвечает на сообщение текстом и карточкой, содержащей заголовок профиля.

Чтобы добавить доверенных тестировщиков и узнать больше о тестировании интерактивных функций, см. раздел «Тестирование интерактивных функций для приложений Google Chat» .

Устранение неполадок

When a Google Chat app or card returns an error, the Chat interface surfaces a message saying "Something went wrong." or "Unable to process your request." Sometimes the Chat UI doesn't display any error message, but the Chat app or card produces an unexpected result; for example, a card message might not appear.

Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, подробные сообщения об ошибках и данные журнала доступны для исправления ошибок, если включено ведение журнала ошибок для приложений чата. Для получения помощи по просмотру, отладке и исправлению ошибок см. раздел «Устранение неполадок и исправление ошибок Google Chat» .

Уборка

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

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

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

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

Связанные темы

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