Эта страница переведена с помощью Cloud Translation API.

Создайте многоагентную систему с помощью ADK, разверните ее в Agent Engine и начните работу с протоколом A2A

1. Цель данной лабораторной работы

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

Чему вы научитесь

Изучите основы ADK и научитесь создавать многоагентную систему.
Узнайте, как легко развертывать и использовать агенты в GCP.
Понять основы протокола A2A
Узнайте, как использовать протокол A2A и ADK вместе для создания открытых агентов.

2. Прежде чем начать

Если у вас еще нет проекта , который вы можете использовать, вам необходимо создать новый проект в консоли GCP .
В этой лабораторной работе мы будем использовать GCP Cloud Shell для выполнения наших задач. Откройте Cloud Shell и настройте проект с помощью Cloud Shell.
Откройте редактор GCP Cloud Shell , нажав кнопку «Редактор Cloud Shell». Если вы видите всплывающее окно «Авторизовать Shell», нажмите кнопку, чтобы авторизовать редактор Cloud Shell.
Проверить, аутентифицирован ли проект, можно с помощью следующей команды.

gcloud auth list

Выполните следующую команду в Cloud Shell, чтобы подтвердить свой проект.

gcloud config list project

Если ваш проект не настроен, используйте следующую команду для его настройки

gcloud config set project <YOUR_PROJECT_ID>

Для запуска этой лаборатории необходимо включить некоторые службы. Выполните следующую команду в Cloud Shell.

gcloud services enable aiplatform.googleapis.com

3. Обзор: преимущества набора для разработки агентов

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

Многоагентные системы : создавайте модульные и масштабируемые приложения, объединяя несколько специализированных агентов в иерархию. Обеспечьте сложную координацию и делегирование полномочий.
Богатая экосистема инструментов : оснастите агентов разнообразными возможностями: используйте готовые инструменты (поиск, выполнение кода и т. д.), создавайте пользовательские функции, интегрируйте инструменты из сторонних фреймворков агентов (LangChain, CrewAI) или даже используйте других агентов в качестве инструментов.
Гибкая оркестровка : определение рабочих процессов с использованием агентов рабочих процессов ( SequentialAgent , ParallelAgent и LoopAgent ) для предсказуемых конвейеров или использование динамической маршрутизации на основе LLM (передача LlmAgent ) для адаптивного поведения.
Интегрированный интерфейс разработчика : разрабатывайте, тестируйте и отлаживайте локально с помощью мощного командного интерфейса и интерактивного пользовательского интерфейса. Пошаговый контроль событий, состояния и выполнения агентов.
Встроенная оценка : систематически оценивайте производительность агента, оценивая как качество окончательного ответа, так и пошаговую траекторию выполнения по заранее определенным тестовым случаям.
Готовность к развертыванию : контейнеризуйте и развертывайте свои агенты где угодно — запускайте локально, масштабируйте с помощью Vertex AI Agent Engine или интегрируйте в пользовательскую инфраструктуру с помощью Cloud Run или Docker.

Хотя другие пакеты SDK Gen AI или агентские фреймворки также позволяют вам запрашивать модели и даже снабжать их инструментами, динамическая координация между несколькими моделями требует значительного объема работы с вашей стороны.

Agent Development Kit предлагает более высокоуровневую структуру, чем эти инструменты, позволяя вам легко соединять несколько агентов друг с другом для сложных, но простых в обслуживании рабочих процессов.

4. Введение в A2A

Протокол Agent2Agent (A2A) — это открытый стандарт, разработанный для обеспечения бесперебойной и безопасной связи и сотрудничества между автономными агентами ИИ из разных фреймворков, поставщиков и доменов.

Универсальная совместимость: A2A позволяет агентам работать вместе независимо от используемых ими технологий, способствуя созданию по-настоящему многоагентной экосистемы. Это означает, что агенты, созданные разными компаниями на разных платформах, могут взаимодействовать и координировать свои действия.
Обнаружение возможностей: агенты могут рекламировать свои возможности, используя «карточки агентов» (документы JSON), в которых описываются их идентификационные данные, поддерживаемые функции A2A, навыки и требования к аутентификации. Это позволяет другим агентам находить и выбирать наиболее подходящего агента для конкретной задачи.
Безопасность по умолчанию: безопасность — это ключевой принцип. A2A включает в себя механизмы аутентификации и авторизации корпоративного уровня, использующие такие стандарты, как HTTPS/TLS, JWT, OIDC и ключи API, для обеспечения безопасного взаимодействия и защиты конфиденциальных данных.
Независимость от модальности: протокол поддерживает различные способы коммуникации, включая потоковое вещание текста, аудио и видео, а также интерактивные формы и встроенные фреймы. Эта гибкость позволяет агентам обмениваться информацией в наиболее подходящем формате для конкретной задачи и пользователя.
Структурированное управление задачами: A2A определяет чёткие протоколы для делегирования, мониторинга и выполнения задач. A2A поддерживает группировку связанных задач и управление ими между разными агентами с помощью уникальных идентификаторов задач. Задачи могут проходить через определённые жизненные циклы (например, «отправлено», «выполняется», «завершено»).
Непрозрачное исполнение: важной особенностью является то, что агентам не нужно раскрывать другим агентам свои внутренние процессы рассуждений, память или специальные инструменты. Они предоставляют доступ только к вызываемым сервисам, что обеспечивает модульность и конфиденциальность.
Создано на основе существующих стандартов: A2A использует устоявшиеся веб-технологии, такие как HTTP, Server-Sent Events (SSE) для потоковой передачи в реальном времени и JSON-RPC для структурированного обмена данными, что упрощает интеграцию с существующей ИТ-инфраструктурой.
Асинхронная связь: протокол разработан с упором на асинхронную связь, что обеспечивает гибкое выполнение задач и позволяет отправлять push-уведомления об обновлениях, даже если соединение не поддерживается постоянно.

5. Архитектура агента

В этой лабораторной работе вы создадите многоагентное приложение, которое генерирует изображение в соответствии с вашими требованиями и оценивает его перед представлением вам.

Система структурирована с основным агентом image_scoring , который координирует весь процесс. У основного агента есть подагент image_generation_scoring_agent , который, в свою очередь, имеет собственные подагенты для выполнения более специфических задач. Это создает иерархическую структуру, в которой основной агент делегирует задачи своим подагентам. Рисунок 2: Общий поток агентов.

Список всех агентов

image_scoring (Основной агент):
Назначение: это корневой агент, управляющий всем рабочим процессом. Он многократно запускает агенты image_generation_scoring_agent и checker_agent в цикле до тех пор, пока не будет выполнено условие завершения.
Субагенты:

агент_оценки_поколения_изображений
checker_agent_instance

image_generation_scoring_agent (субагент image_scoring):
Назначение: Этот агент отвечает за базовую логику генерации и оценки изображений. Для этого он выполняет последовательность из трёх подагентов.
Субагенты:

image_generation_prompt_agent
агент_поколения_изображений
scoring_images_prompt

checker_agent_instance (субагент image_scoring):
Назначение: Этот агент проверяет, следует ли продолжить или завершить процесс оценки изображения. Он использует инструмент check_tool_condition для оценки условия завершения.
image_generation_prompt_agent (субагент image_generation_scoring_agent):
Назначение: Этот агент — эксперт в создании подсказок для генерации изображений. Он принимает входящий текст и генерирует подробную подсказку, соответствующую модели генерации изображений.
i mage_generation_agent (субагент image_generation_scoring_agent):
Назначение: Этот агент является экспертом в создании изображений с помощью Imagen 3. Он принимает подсказку от image_generation_prompt_agent и генерирует изображение.
scoring_images_prompt (субагент image_generation_scoring_agent):
Назначение: Этот агент — эксперт по оценке и оценке изображений по различным критериям. Он берёт сгенерированное изображение и присваивает ему оценку.

Инструменты, используемые агентами

проверка_инструмента_условия :
Описание: Этот инструмент проверяет, выполнено ли условие завершения цикла или достигнуто ли максимальное количество итераций. Если хотя бы одно из этих условий выполняется, цикл останавливается.
Используется: checker_agent_instance
generate_images:
Описание: Этот инструмент генерирует изображения с использованием модели Imagen 3. Он также может сохранять сгенерированные изображения в хранилище Google Cloud Storage.
Используется: image_generation_agent
получить_политику:
Описание: Этот инструмент извлекает политику из JSON-файла. Политика используется агентом image_generation_prompt_agent для создания запроса на генерацию изображений и scoring_images_prompt для оценки изображений.
Используется: image_generation_prompt_agent , scoring_images_prompt
получить_изображение:
Описание: Этот инструмент загружает сгенерированный артефакт изображения, чтобы его можно было оценить.
Используется: scoring_images_prompt
set_score:
Описание: Этот инструмент устанавливает общую оценку сгенерированного изображения в состоянии сеанса.
Используется: scoring_images_prompt

6. Задача 1. Установка ADK и настройка среды.

В этом практическом занятии мы будем использовать Cloud Shell для выполнения задач.

Включить рекомендуемые API Vertex AI

В консоли Google Cloud перейдите к Vertex AI , выполнив поиск в верхней части консоли.
Нажмите Включить все рекомендуемые API .

Подготовьте вкладку Cloud Shell Editor

Выбрав окно консоли Google Cloud, откройте Cloud Shell, нажав клавишу G , а затем клавишу S на клавиатуре. Также можно нажать кнопку Cloud Shell. в правом верхнем углу Google Cloud Console.
Нажмите «Продолжить» .
При появлении запроса на авторизацию Cloud Shell нажмите «Авторизовать» .
В правом верхнем углу панели Cloud Shell нажмите кнопку « Открыть в новом окне». .
Нажмите значок карандаша « Открыть редактор» ( ) в верхней части панели для просмотра файлов.
В верхней части левого навигационного меню нажмите значок «Проводник». чтобы открыть проводник.
Нажмите кнопку «Открыть папку» .
На протяжении всей оставшейся части этой лабораторной работы вы можете работать в этом окне как в IDE с редактором Cloud Shell Editor и терминалом Cloud Shell Terminal.

Загрузите и установите ADK и примеры кода для этой лабораторной работы.

Выполните следующие команды, чтобы клонировать необходимый исходный код из github и установить необходимые библиотеки.

#create the project directory
mkdir imagescoring
cd imagescoring
#clone the code in the local directory
git clone https://github.com/haren-bh/multiagenthandson.git

#Create the virtual environment
python3 -m venv pythonenv
source pythonenv/bin/activate

#install google-adk and a2a sdk
python3 -m pip install google-adk==1.8.0
python3 -m pip install a2a-sdk==0.2.16

Мы будем использовать поэзию для установки дополнительных требований:

cd multiagenthandson #go to the application directory
pip install poetry poetry-plugin-export
poetry install --with deployment

Если у вас нет контейнера облачного хранилища, создайте новый в Google Cloud Storage . Вы также можете создать контейнер с помощью команды gsutil.

gsutil mb gs://YOUR-UNIQUE-BUCKETNAME

В редакторе выберите «Вид» -> «Скрыть файлы». В папке image_scoring создайте файл .env со следующим содержимым. Добавьте необходимые данные, такие как название проекта и контейнер облачного хранилища.

GOOGLE_GENAI_USE_VERTEXAI=1 #1 if VERTEXAI has to be used. Can be 0 if API_KEY is specified
GOOGLE_CLOUD_PROJECT=YOUR CLOUD PROJECT NAME
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_CLOUD_STORAGE_BUCKET=YOUR BUCKET NAME  # Only required for deployment on Agent Engine
GCS_BUCKET_NAME=YOUR BUCKET NAME #Bucket for storing generated images.
SCORE_THRESHOLD=40 # Min threshold for image_score. Max Score is 50 , hence should be less than 50. 
#If the computed score is higher then loop will terminate
#MAX_ITERATIONS=5 #Max iterations for evaluating the image_score before terminating the loop.
IMAGEN_MODEL="imagen-3.0-generate-002" 
GENAI_MODEL="gemini-2.5-flash"
#AGENT_ENGINE_ID=<AGENT_ENGINE_ID> #The Agent Engine ID obtained after deploying to the agent engine.

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

# Run the following command to run agents locally
export GCS_BUCKET_NAME=your gcs bucket name
adk web

Рисунок 1

Нажмите Ctrl+клик (CMD+клик для MacOS) по URL-адресу http://, отображаемому в терминале, чтобы открыть браузерный графический клиент ADK. Должно выглядеть так, как показано на рисунке 2.

Давайте создадим несколько изображений. Попробуйте использовать следующие подсказки или придумать свои собственные.
Мирный горный пейзаж на закате
Кот едет на велосипеде

Рисунок 2

7. Задача 2. Развертывание в Agent Engine

Теперь мы разворачиваем агент в Agent Engine. Agent Engine — это полностью управляемый сервис для развёртывания агентов в GCP. Agent Engine совместим с ADK, поэтому агенты, созданные с помощью ADK, можно развёртывать в Agent Engine.

Определите некоторые переменные среды

export GOOGLE_CLOUD_LOCATION='us-central1'
export GOOGLE_CLOUD_PROJECT='your project id'

Создайте файл requirements.txt с помощью Poetry. Poetry будет использовать pyproject.toml для создания файла requirements.txt . После выполнения команды проверьте, создан ли файл requirements.txt .

# Go to the parent folder containing pyproject.toml file
# install poetry-plugin-export
pip install poetry-plugin-export

#Create requirements.txt file
poetry export -f requirements.txt --output requirements.txt --without-hashes

Создайте пакет. Нам нужно упаковать наше приложение в пакет Python .whl . Для этого мы будем использовать Poese. После выполнения команды убедитесь, что создана папка dist, содержащая файл .whl .

# Go to the parent folder containing pyproject.toml file
#Create python package, to create whl file
poetry build

Теперь подготовим скрипт развёртывания. Он развёрнет наш агент оценки изображений или службу агентского движка. Измените содержимое файла deploy.py в папке image_scoring, как показано ниже.

# Change the content of the following. Look for #change this comment
import vertexai
from .agent import root_agent
import os
import glob # To easily find the wheel file

PROJECT_ID = "YOUR PROJECT ID" #change this your project
LOCATION = "us-central1" #change this
STAGING_BUCKET = "gs://YOUR BUCKET " #change this to your bucket

from vertexai import agent_engines

vertexai.init(
   project=PROJECT_ID,
   location=LOCATION,
   staging_bucket=STAGING_BUCKET,
)

remote_app = agent_engines.create(
   agent_engine=root_agent,
   requirements=open(os.path.join(os.getcwd(), "requirements.txt")).readlines()+["./dist/image_scoring-0.1.0-py3-none-any.whl"],#change this to your local location
   extra_packages=[
       "./dist/image_scoring-0.1.0-py3-none-any.whl", # change this to your location
   ]
)

print(remote_app.resource_name)

Теперь мы можем запустить скрипт развертывания.

#run deploy script from the parent folder containing deploy.py
python3 -m image_scoring.deploy

После развертывания вы должны увидеть что-то вроде ниже:

Рисунок 3

Теперь протестируем развёрнутый агент. Чтобы протестировать удалённо развёрнутый агентский движок, сначала скопируйте местоположение агента из вывода развёртывания в терминале. Должно выглядеть примерно так: projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680 .
Перейдите в папку testclient, откройте файл remote_test.py и отредактируйте следующие строки.

PROJECT_ID = "" #change this
LOCATION = "" #change this
STAGING_BUCKET = "" #change this

#replace the id with your own.
reasoning_engine_id="your agent engine id"

#You can replace this with your own prompt
image_prompt="A cat riding a bicycle"

#execute remote_test.py
python3 remote_test.py

8. Задание 3. Создание агента A2A

На этом этапе мы создадим простой агент A2A на основе агента, созданного на предыдущих этапах. Существующие агенты ADK можно публиковать по протоколу A2A. Вот основные моменты, которые вы изучите на этом этапе.

Изучите основы протокола A2A.
Узнайте, как протоколы ADK и A2A работают друг с другом.
Узнайте, как взаимодействовать с протоколом A2A.

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

Создать карточку агента A2A

Для протокола A2A требуется карточка агента , содержащая всю информацию об агенте, такую как его возможности, руководство по использованию и т. д. После развёртывания агента A2A карточка агента доступна по ссылке « .well-known/agent-card.json ». Клиенты могут ссылаться на эту информацию для отправки запроса агентам.

Убедитесь, что в папке remote_a2a/image_scoring есть файл agents.json со следующим содержимым.

{
 "name": "image_scoring",
 "description": "Agent that generates images based on user prompts and scores their adherence to the prompt.",
 "url": "http://localhost:8001/a2a/image_scoring",
 "version": "1.0.0",
 "defaultInputModes": ["text/plain"],
 "defaultOutputModes": ["image/png", "text/plain"],
 "capabilities": {
   "streaming": true,
   "functions": true
 },
 "skills": [
   {
     "id": "generate_and_score_image",
     "name": "Generate and Score Image",
     "description": "Generates an image from a given text prompt and then evaluates how well the generated image adheres to the original prompt, providing a score.",
     "tags": ["image generation", "image scoring", "evaluation", "AI art"],
     "examples": [
       "Generate an image of a futuristic city at sunset",
       "Create an image of a cat playing a piano",
       "Show me an image of a serene forest with a hidden waterfall"
     ]
   }
 ]
}

Создать агента A2A

Убедитесь, что в корневой папке image_scoring_adk_a2a_server находится файл a2a_agent.py , который является точкой входа для агента a2a. Он должен иметь следующее содержимое:

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

root_agent = RemoteA2aAgent(
   name="image_scoring",
   description="Agent to give interesting facts.",
   agent_card="http://localhost:8001/a2a/image_scoring/.well-known/agent.json",
  
   # Optional configurations
   timeout=300.0,          # HTTP timeout (seconds)
   httpx_client=None,      # Custom HTTP client
)

Запустить агент A2A

Теперь мы готовы запустить агент! Для запуска агента выполните следующую команду из папки image_scoring_adk_a2a_server.

#set some environmental variables
export GOOGLE_CLOUD_PROJECT=datapipeline-372305
export GOOGLE_CLOUD_LOCATION=us-central1
export GCS_BUCKET_NAME=haren-genai-bucket

#following command runs the ADK agent as a2a agent
adk api_server --a2a --port 8001 remote_a2a

Тестовый агент A2A

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

#Execute the following 
curl http://localhost:8001/a2a/image_scoring/.well-known/agent.json

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

Давайте теперь отправим запрос агенту. Для этого можно использовать curl.

curl -X POST   http://localhost:8001/a2a/image_scoring   -H 'Content-Type: application/json'   -d '{
    "id": "uuid-123",
    "params": {
      "message": {
        "messageId": "msg-456",
        "parts": [{"text": "Create an image of a cat"}],
        "role": "user"
      }
    }
  }'

В приведённом выше запросе вы можете изменить строку « Создать изображение кошки ». После выполнения команды вы можете проверить наличие полученного изображения в указанном облачном хранилище Google.

9. Уборка

Теперь давайте приведем в порядок то, что мы только что создали.

Удалите только что созданный сервер Agent Engine. Перейдите в Vertex AI, введя Vertex AI в строку поиска Google Cloud Console. Нажмите на Agent Engine слева. Вы можете удалить Agent, нажав «Удалить».

Рисунок 4

Удалить файлы в Cloud Shell

#Execute the following to delete the files
rm -R imagescoring

Удалить контейнер. Вы можете перейти в консоль GCP -> Cloud Storage, выбрать и удалить контейнер.