Асинхронный вызов приложения агентного ИИ с использованием событий

1. Введение

Обзор

В этой лабораторной работе демонстрируется, как безопасно реализовать вызов агента ADK, развернутого в Cloud Run, на основе событий, используя Eventarc и службы Pub/Sub. Чаще всего агент вызывается пользователем или другим агентом напрямую. Однако, когда агент интегрируется в существующие рабочие процессы, основанные на событиях, прямой вызов требует внесения изменений в существующее программное обеспечение. Запуск агента на основе события позволяет включить агента в существующие рабочие процессы без внесения в них изменений.

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

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

Иллюстрация смотрителя зоопарка

Вы развернете приложение ZooKeeper в качестве сервиса в Cloud Run — полностью управляемой бессерверной вычислительной платформе, которая запускает контейнеры без сохранения состояния на инфраструктуре Google. Затем вы настроите триггер Eventarc, который будет вызывать конечную точку сервиса для асинхронной обработки сообщений, опубликованных в тему Pub/Sub. Вы должны убедиться, что развертывание соответствует передовым практикам, включая использование выделенных учетных записей служб IAM, предоставление доступа с минимальными привилегиями и минимизацию потенциальной поверхности атаки путем предоставления доступа к конечной точке приложения ZooKeeper только через Eventarc. Вы сделаете это с помощью Cloud Shell и Cloud Console. Вы будете использовать библиотеки ADK и Cloud SDK для Python. Для проверки работы вы будете использовать CLI gcloud.

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

  • Разверните агент ADK в Google Cloud Run.
  • Интеграция триггера Eventarc с агентом ADK, работающим в Google Cloud Run.
  • Обеспечьте безопасность развертывания и интеграции с Eventarc, используя принцип минимальных привилегий доступа с помощью Google Cloud IAM.
  • Публикация и получение сообщений в систему Pub/Sub.
  • Сведите к минимуму публичную доступность вашего приложения, развернутого в Google Cloud Run.

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

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

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

‡ Использование корпоративного или школьного аккаунта может ограничивать выполнение некоторых операций, описанных в лабораторной работе.

2. Настройка среды

Для обеспечения полноценной среды разработки в лаборатории вы будете использовать Google Cloud Shell , в котором предварительно установлены все необходимые инструменты. Следуйте инструкциям по настройке среды.

Если у вас нет учетной записи Google, создайте ее .

Инструкции по установке

  1. Для входа в консоль Google Cloud используйте свою учетную запись Google.
  2. 👉 Откройте панель выбора проектов в верхней панели навигации (там может быть написано «Выберите проект» или отображаться название существующего проекта) или нажмите сочетание клавиш Ctrl + O и выберите существующий проект или создайте новый. Создание нового проекта займет несколько секунд. Подождите, пока он будет готов, и выберите его с помощью панели выбора проектов.
  1. 👉 Нажмите на значок Cloud Shell в верхней части консоли Google Cloud (отмечен красным прямоугольником): Кнопка «Облачная оболочка»
    Если появится запрос, нажмите кнопку **Авторизовать** во всплывающем диалоговом окне, чтобы разрешить Cloud Shell использовать учетные данные вашей учетной записи.
    Диалог авторизации
  2. 👉💻 Убедитесь, что gcloud CLI настроен на использование выбранного (или созданного) вами проекта. Выполните следующую команду, чтобы проверить настроенный идентификатор проекта:
    gcloud config get-value project
    Ожидается, что вы увидите результат, аналогичный следующему:
    Your active configuration is: [cloudshell-19597]
[PROJECT_ID]
    где [PROJECT_ID] будет идентификатором проекта, который вы выбрали или создали. 👉💻 Если вы видите другое значение, выполните следующую команду, чтобы настроить идентификатор вашего проекта в качестве идентификатора проекта по умолчанию для команд CLI gcloud:
    gcloud config set project [YOUR_PROJECT_ID]
    Например, если идентификатор вашего проекта — lab-project-id-example-123, то команда должна выглядеть так:
    gcloud config set project lab-project-id-example-123
    🤔💻 Если вы не помните идентификатор своего проекта, используйте следующую команду, чтобы вывести список всех доступных вам идентификаторов проектов, начиная с самого последнего: 
    gcloud projects list \
    --format='value(projectId)' \
    --sort-by='~createTime'
  1. 👉💻 Укажите местоположение для выделения ресурсов, а также идентификатор и номер вашего проекта в переменных среды: 
    export LOCATION="us-central1"
export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
  2. 👉💻 Включите API Google, необходимые для этой лабораторной работы.
    gcloud services enable \
    aiplatform.googleapis.com \
    eventarc.googleapis.com \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    pubsub.googleapis.com
    Пожалуйста, наберитесь терпения, выполнение этой команды может занять несколько минут. После успешного выполнения команды вы должны увидеть сообщение, похожее на это: 
    Operation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.

3. Разверните демонстрационное приложение ZooKeeper.

Следующие шаги включают в себя подготовку и настройку ресурсов, в том числе развертывание приложения искусственного интеллекта.

Настройка ресурсов Pub/Sub

Вам нужно будет создать две темы Pub/Sub. Одна будет использоваться сторонним сервисом для отправки событий в ваше приложение с агентным ИИ. Другая — для публикации приложением результатов обработки событий.

  1. 👉💻 Создайте тему Pub/Sub, используемую для запуска приложения искусственного интеллекта: 
    gcloud pubsub topics create invoke_agent
export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)")
  2. 👉💻 Создайте тему Pub/Sub, куда приложение сможет публиковать свои ответы:
    gcloud pubsub topics create agent_responses
export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)")
gcloud pubsub subscriptions create agent_responses \
    --topic=agent_responses
    Эти команды также создают подписку на созданную тему Pub/Sub. Подписка будет использоваться при запуске демонстрации для просмотра результатов.

Настройка учетных записей служб и политик IAM на уровне проекта.

Вам потребуется создать две учетные записи служб, чтобы ограничить область доступа к службе Cloud Run и триггеру Eventarc до минимума, следуя принципу минимальных привилегий. Службе Cloud Run требуются разрешения на запись журналов и трассировок, вызов Gemini LLM в Google Vertex AI и отправку результатов в тему Pub/Sub. Минимальный доступ для триггера Eventarc требует разрешений на вызов службы Cloud Run ZooKeeper и доступ к Pub/Sub для чтения отправленных событий. Эти инструкции помогут вам предоставить учетной записи службы триггера необходимые разрешения для имитации системной службы Pub/Sub. После создания ресурса триггера Eventarc вы выполните команду, которая предоставит роль roles/run.invoker , чтобы разрешить учетной записи службы триггера вызывать службу Cloud Run.

  1. 👉💻 Создайте учетную запись службы для сервиса Cloud Run: 
    gcloud iam service-accounts create zookeeper-cloudrun-sa
export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com"
  2. 👉💻 Предоставьте учетной записи службы права на запись логов и трассировок, а также на использование моделей Gemini в Vertex AI: 
    gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
     --member="serviceAccount:${ZOOKEEPER_SA}" \
     --role="roles/logging.logWriter" \
     --condition=None
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:${ZOOKEEPER_SA}" \
    --role="roles/cloudtrace.agent" \
    --condition=None
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:${ZOOKEEPER_SA}" \
    --role="roles/aiplatform.user" \
    --condition=None
  3. 👉💻 Предоставьте учетной записи службы права на отправку сообщений в топик 'agent_responses': 
    gcloud pubsub topics add-iam-policy-binding agent_responses \
    --member="serviceAccount:${ZOOKEEPER_SA}" \
    --role="roles/pubsub.publisher"
  4. 👉💻 Создайте учетную запись службы для триггера Eventarc: 
    gcloud iam service-accounts create zookeeper-trigger-sa
export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com"
  5. 👉💻 Предоставьте учетной записи службы системы Pub/Sub разрешения на выполнение аутентифицированных push-запросов:
    gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \
       --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"
    Эта команда является необязательной, если проект создан после 8 апреля 2021 года.

Развертывание приложения ZooKeeper в Cloud Run

Вам нужно будет загрузить код демонстрационного приложения с GitHub и развернуть его в Cloud Run.

  1. 👉💻 Скачайте приложение Agentic AI:
    mkdir zoo-keeper-lab && cd zoo-keeper-lab
git init
git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos
git config set core.sparseCheckout true
echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout
git pull origin main --depth 1
cd ai-ml/agent-labs/adk_invoke_with_pubsub/
    Эти команды используют разреженное извлечение папки с демонстрационным приложением из Git, чтобы сократить время загрузки.
  2. 👉💻 Разверните приложение Agentic AI в Cloud Run: 
    gcloud run deploy zookeeper-agent \
    --region="${LOCATION}" \
    --source="." \
    --no-allow-unauthenticated \
    --quiet \
    --service-account="${ZOOKEEPER_SA}" \
    --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"

Настройка триггера Eventarc

После подготовки всех ресурсов (тем Pub/Sub, учетных записей служб IAM и службы Cloud Run) настало время настроить ресурс триггера Eventarc. Вам нужно будет создать ресурс триггера Eventarc и предоставить учетной записи службы триггера разрешения на вызов службы Cloud Run.

  1. 👉💻 Создайте триггер Eventarc: 
    gcloud eventarc triggers create invoke-agent \
    --location="${LOCATION}" \
    --destination-run-service="zookeeper-agent" \
    --destination-run-path="/zookeeper" \
    --destination-run-region="${LOCATION}" \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --transport-topic="${INVOKE_TOPIC_ID}" \
    --service-account="${TRIGGER_SA}"
  2. 👉💻 Предоставьте учетной записи службы триггера права на вызов службы Cloud Run: 
    gcloud run services add-iam-policy-binding zookeeper-agent \
    --region="${LOCATION}" \
    --member="serviceAccount:${TRIGGER_SA}" \
    --role="roles/run.invoker"

4. Проанализируйте принцип работы решения.

Теперь просмотрите то, что вы только что развернули. На следующей диаграмме показаны все ресурсы и то, как они взаимодействуют друг с другом. Вы будете использовать CLI gcloud для публикации сообщения в топик 'invoke_agent'. Это имитирует событие, которое сторонний сервис регистрирует в службе обмена сообщениями для вызова агентного приложения искусственного интеллекта.

Схема решения

Развертывание защищено с использованием принципа минимальных привилегий доступа. Сервис Cloud Run обеспечивает аутентификацию (см. аргумент --no-allow-unauthenticated в шаге #9 предыдущего раздела). Только пользователи с ролью roles/run.invoker или аналогичными правами могут вызывать сервис. Эта роль предоставляется только учетной записи сервиса триггера Eventarc. Аналогичным образом, доступ к топику 'invoke_agent' минимизирован, чтобы предотвратить несанкционированную публикацию событий. Тем не менее, по-прежнему можно вызывать агент ZooKeeper напрямую, минуя отправку данных в топик Pub/Sub. См. раздел 6, чтобы узнать, как скрыть конечную точку приложения от публичного доступа.

Запустите рабочий процесс

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

👉💻 Используйте следующую команду, чтобы отправить сообщение в тему Pub/Sub: 

gcloud pubsub topics publish invoke_agent \
    --message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'

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

Вы можете убедиться, что агент получил событие, обработал запрос и отправил ответ в топик 'agent_responses'. Для чтения ответа вы будете использовать подписку на 'agent_responses' (в практическом задании используется один и тот же идентификатор как для топика, так и для подписки на ответы).

👉💻 Используйте следующую команду, чтобы прочитать ответ агента из подписки Pub/Sub: 

gcloud pubsub subscriptions pull agent_responses --auto-ack

В результате будет выведена таблица с метаданными сообщения и полезной нагрузкой, содержащей ответ о том, что в зоопарке 33 вида животных. Флаг --auto-ack автоматически подтверждает получение сообщения после его отправки, поэтому оно не будет доставлено повторно.

Как это работает

Чтобы ознакомиться с исходным кодом приложения для искусственного интеллекта, откройте редактор Cloud Shell и просмотрите файлы в папке ~/zoo-keeper-lab . Вы также можете посмотреть исходный код на GitHub .

  • В файле main.py реализовано базовое веб-приложение FastAPI с единственным обработчиком событий Eventarc.
  • Скрипт processor.py анализирует сообщение события, чтобы получить идентификатор пользователя и запрос. Затем он создает новую сессию в ADK-раннере и вызывает агент Zookeeper для обработки запроса. Ответ от агента отправляется в топик Pub/Sub 'agent_responses'.
  • В подпапке zookeeper_agent находится исходный код агента ADK. Вы можете запустить команду adk run zookeeper_agent из корневой папки приложения, чтобы взаимодействовать с агентом с помощью adk CLI .

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

В случае сбоя какой-либо из предыдущих команд внимательно изучите сообщение об ошибке. Если развертывание в Cloud Run не удается, первым шагом будет определение этапа процесса, на котором произошел сбой.

  • Если в выводе команды "gcloud run deploy..." указано, что сборка завершилась неудачей, просмотрите URL-адрес журналов сборки в выводе и откройте его в отдельном окне.
  • Если в выводе отображается что-то вроде «служба не запустилась» или подобное, это означает, что служба развертывается, но затем ее выполнение завершается с ошибкой проверки работоспособности. В этом случае откройте Logs Explorer или обратитесь к следующему абзацу, где описана команда CLI gcloud. Прочитайте журналы, чтобы найти первопричину сбоя.

Что если вы отправили сообщение в Pub/Sub, но агент не отвечает или ответ выглядит странно?

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

gcloud logging read \
    'resource.type = "cloud_run_revision" AND \
     resource.labels.service_name = "zookeeper-agent" AND \
     resource.labels.location = "us-central1"'

Журналы отслеживают выполнение и сообщают об ошибках, таких как некорректная или не поддающаяся разбору полезная нагрузка сообщения, недопустимый ответ от модели Gemini, недопустимые настройки среды и другие возможные проблемы.

5. Усиление защиты при развертывании.

Развернутая вами служба Cloud Run предоставляет общедоступную конечную точку, к которой может обратиться любой пользователь интернета. Хотя конечная точка защищена от несанкционированного доступа и тщательно проверяет структуру запроса, она все же оставляет этот вектор атаки, позволяющий осуществлять атаки типа «отказ в обслуживании» и «отказ в доступе к кошельку». Поскольку в текущей конфигурации единственный путь вызова службы — через триггер Eventarc, службе не нужно предоставлять свою конечную точку в интернет.

👉💻 Устраните этот вектор атаки, ограничив обращения к сервису только определенным набором источников, включая триггеры Eventarc: 

gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal

Теперь, если вы попытаетесь обратиться к URL-адресу сервиса со своего локального компьютера, вы получите ошибку "404 Страница не найдена".

👉💻 Используйте curl для отправки запроса на конечную точку сервиса: 

URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"

Вы увидите результат, похожий на следующий: 

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>404 Page not found</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Page not found</h1>
<h2>The requested URL was not found on this server.</h2>
<h2></h2>
</body></html>

После этого изменения стало невозможно напрямую вызывать ZooKeeper через конечную точку службы Cloud Run, если только вы не сделаете вызов из VPC в том же проекте, из сети Shared VPC, в которую настроена отправка трафика для вашей ревизии, или с хоста, входящего в периметр управления службами VPC .

6. Резюме

Поздравляем! Вы успешно настроили среду для асинхронного запуска вашего приложения на основе агентного ИИ по входящим событиям.

Уборка

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

Существует два способа это сделать:

Метод 1 : Завершение проекта

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

gcloud projects delete $(gcloud config get-value project) --quiet

Метод 2 : Удаление ресурсов в проекте

Удаление службы Cloud Run защитит от дальнейших расходов на использование бессерверной платформы. Обратите внимание, что этот метод не полностью удаляет все данные, сгенерированные во время выполнения практического задания, такие как журналы Cloud Build и приложений, образы контейнеров и т. д. Для удаления службы выполните следующую команду: 

gcloud run services delete zookeeper-agent --region=${LOCATION}

Определение триггера Eventarc и темы Pub/Sub не влекут за собой затрат на управление (подробнее см. разделы «Цены на Eventarc» и «Цены на Pub/Sub» ).

Узнайте больше о закрытии проекта .

Что дальше?