Как создать приложение Google Chat с агентом Agent2UI

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

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

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

  • Агент A2UI отвечает пользователю сообщением с текстом и карточкой, на которой указаны название профиля, изображение и кнопка LinkedIn.
    Рисунок 1. Агент A2UI отвечает пользователю текстом и карточкой с именем, изображением и кнопкой LinkedIn.
  • Агент A2UI также обновлен, чтобы возвращать название профиля.
    Рисунок 2. Агент A2UI теперь также возвращает название профиля.
  • Агент A2UI отвечает пользователю сообщением, в котором на карточке указано название профиля.
    Рисунок 3. Агент A2UI отвечает пользователю сообщением, в котором на карточке указано название профиля.

На диаграмме ниже показана архитектура и шаблон обмена сообщениями.

Архитектура приложения для Chat, реализованного с помощью ИИ-агента A2UI.

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

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

Цели

  • Настройте среду.
  • Разверните агента A2UI.
  • Разверните приложение Chat.
  • Настройте приложение Chat.
  • Проверьте приложение Chat.

Требования

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

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

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

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

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

  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…

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

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

Google Cloud Console

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

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

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

  2. Выберите проект Google Cloud.
  3. Нажмите Создать сервисный аккаунт.
  4. Введите название сервисного аккаунта, которое будет показываться в консоли Google Cloud.
  5. Если вы не хотите настраивать контроль доступа сейчас, нажмите Готово, чтобы завершить создание сервисного аккаунта. Чтобы настроить контроль доступа сейчас, нажмите Создать и продолжить и перейдите к следующему шагу.
  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…

Как развернуть агента A2UI

  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. Скачайте репозиторий 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 с названием созданного вами сегмента.
    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. Получите идентификатор агента. Он понадобится вам позже, при настройке приложения Chat.

    python3 deployment/deploy.py --list

Как создать и настроить проект приложения Chat

  1. Нажмите кнопку ниже, чтобы открыть проект Apps Script A2UI ИИ-агент Quickstart.

    Как открыть проект

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

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

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

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

  5. В Google API Console нажмите на значок меню > IAM и администрирование > Настройки.

    Перейти к настройкам IAM и администрирования

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

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

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

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

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

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

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

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

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

Как настроить приложение Chat

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

  1. В API Console выполните поиск по запросу Google Chat API и нажмите Google Chat API.
  2. Нажмите Настроить.

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

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

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

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

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

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

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

    Перейти в Google Chat

  2. Нажмите Новый чат.
  3. В поле Добавьте одного или нескольких пользователей введите название приложения Chat.

  4. Выберите приложение Chat в результатах поиска. Откроется прямая переписка.

  5. В новой прямой переписке с приложением введите Hello! и нажмите enter.

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

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

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

    apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py
    # 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.

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

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

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

Если приложение Google Chat или карточка возвращает ошибку, в интерфейсе Chat появляется сообщение "Что-то пошло не так". или "Не удалось обработать запрос". Иногда в интерфейсе Chat не показывается сообщение об ошибке, но приложение Chat или карточка выдает неожиданный результат, например не появляется сообщение на карточке.

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

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

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

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

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

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