Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie systemu z wieloma agentami za pomocą ADK, wdrażanie w Agent Engine i rozpoczynanie pracy z protokołem A2A

1. Cel tego modułu

W tym praktycznym module utworzysz aplikację z wieloma agentami, która generuje obraz na podstawie prompta i ocenia go pod kątem zgodności z promptem. Jeśli obraz nie spełnia w zadowalający sposób wymagań opisanych w prompcie, agent będzie generować obrazy, dopóki nie powstanie obraz spełniający Twoje wymagania. Każdy z agentów w tym praktycznym przykładzie ma jeden cel, a agenci współpracują ze sobą, aby osiągnąć cel ogólny.

Czego się nauczysz

Poznaj podstawy ADK i dowiedz się, jak utworzyć system wieloagentowy.
Dowiedz się, jak łatwo wdrażać i używać agentów w GCP.
Podstawowe informacje o protokole A2A
Dowiedz się, jak używać protokołu A2A i ADK do tworzenia otwartych agentów.

2. Zanim zaczniesz

Jeśli nie masz jeszcze projektu, którego możesz użyć, musisz utworzyć nowy projekt w konsoli GCP.
W tym module do wykonania zadań użyjemy GCP Cloud Shell. Otwórz Cloud Shell i ustaw projekt za pomocą Cloud Shell.
Otwórz edytor Cloud Shell GCP, klikając przycisk edytora Cloud Shell. Jeśli pojawi się wyskakujące okienko „Autoryzuj Shell”, kliknij, aby autoryzować edytor Cloud Shell.
Aby sprawdzić, czy projekt jest już uwierzytelniony, użyj tego polecenia:

gcloud auth list

Aby potwierdzić projekt, uruchom w Cloud Shell to polecenie:

gcloud config list project

Jeśli projekt nie jest ustawiony, użyj tego polecenia, aby go ustawić:

gcloud config set project <YOUR_PROJECT_ID>

Aby przeprowadzić to ćwiczenie, musimy włączyć niektóre usługi. Uruchom to polecenie w Cloud Shell.

gcloud services enable aiplatform.googleapis.com

3. Omówienie: korzyści z pakietu Agent Development Kit

Pakiet Agent Development Kit oferuje deweloperom tworzącym aplikacje oparte na agentach kilka kluczowych zalet:

Systemy wieloagentowe: twórz modułowe i skalowalne aplikacje, łącząc w hierarchii wielu wyspecjalizowanych agentów. Umożliwia złożoną koordynację i delegowanie.
Bogaty ekosystem narzędzi: wyposaż agentów w różnorodne funkcje: korzystaj z gotowych narzędzi (wyszukiwanie, wykonywanie kodu itp.), twórz funkcje niestandardowe, integruj narzędzia z zewnętrznych platform agentów (LangChain, CrewAI) lub używaj innych agentów jako narzędzi.
Elastyczna orkiestracja: definiuj przepływy pracy za pomocą agentów przepływu pracy (SequentialAgent, ParallelAgent i LoopAgent) w przypadku przewidywalnych potoków lub korzystaj z dynamicznego routingu opartego na LLM (LlmAgent przekazywanie) w celu dostosowywania działania.
Zintegrowane środowisko programistyczne: lokalne tworzenie, testowanie i debugowanie za pomocą zaawansowanego interfejsu wiersza poleceń i interaktywnego interfejsu programistycznego. Sprawdzaj zdarzenia, stan i wykonywanie agenta krok po kroku.
Wbudowana ocena: systematycznie oceniaj skuteczność agenta, sprawdzając zarówno jakość ostatecznej odpowiedzi, jak i kolejne etapy realizacji w porównaniu z wcześniej zdefiniowanymi przypadkami testowymi.
Gotowość do wdrożenia: konteneryzuj i wdrażaj agentów w dowolnym miejscu – uruchamiaj lokalnie, skaluj za pomocą Vertex AI Agent Engine lub integruj z infrastrukturą niestandardową za pomocą Cloud Run lub Dockera.

Inne pakiety SDK generatywnej AI lub platformy agentów również umożliwiają wysyłanie zapytań do modeli, a nawet udostępnianie im narzędzi, ale dynamiczna koordynacja między wieloma modelami wymaga znacznego nakładu pracy z Twojej strony.

Zestaw Agent Development Kit oferuje bardziej zaawansowane ramy niż te narzędzia, co pozwala łatwo łączyć ze sobą wiele agentów w celu tworzenia złożonych, ale łatwych w utrzymaniu procesów.

4. Wprowadzenie do A2A

Protokół Agent2Agent (A2A) to otwarty standard zaprojektowany z myślą o umożliwieniu płynnej i bezpiecznej komunikacji oraz współpracy między autonomicznymi agentami AI z różnych platform, od różnych dostawców i z różnych domen.

Uniwersalna interoperacyjność: A2A umożliwia agentom współpracę niezależnie od ich technologii bazowych, tworząc prawdziwy ekosystem wielu agentów. Oznacza to, że agenci stworzeni przez różne firmy na różnych platformach mogą się komunikować i koordynować działania.
Odkrywanie możliwości: agenci mogą reklamować swoje możliwości za pomocą „kart agenta” (dokumentów JSON), które opisują ich tożsamość, obsługiwane funkcje A2A, umiejętności i wymagania dotyczące uwierzytelniania. Dzięki temu inne agenty mogą znaleźć i wybrać najbardziej odpowiedniego agenta do danego zadania.
Bezpieczeństwo w standardzie: bezpieczeństwo to podstawowa zasada. A2A wykorzystuje mechanizmy uwierzytelniania i autoryzacji klasy korporacyjnej, które są zgodne ze standardami takimi jak HTTPS/TLS, JWT, OIDC i klucze API. Zapewnia to bezpieczne interakcje i chroni dane wrażliwe.
Niezależność od modalności: protokół obsługuje różne modalności komunikacji, w tym tekst, dźwięk i streaming wideo, a także interaktywne formularze i osadzone ramki iframe. Dzięki temu agenci mogą wymieniać informacje w formacie najbardziej odpowiednim dla danego zadania i użytkownika.
Ustrukturyzowane zarządzanie zadaniami: A2A określa jasne protokoły delegowania, monitorowania i wykonywania zadań. Umożliwia grupowanie powiązanych zadań i zarządzanie nimi na różnych platformach za pomocą unikalnych identyfikatorów zadań. Zadania mogą przechodzić przez określone cykle życia (np. przesłane, w trakcie realizacji, ukończone).
Nieprzejrzyste wykonywanie: ważną cechą jest to, że agenci nie muszą ujawniać innym agentom swoich wewnętrznych procesów rozumowania, pamięci ani konkretnych narzędzi. Udostępniają tylko usługi, które można wywołać, co zwiększa modułowość i prywatność.
Oparte na istniejących standardach: A2A wykorzystuje sprawdzone technologie internetowe, takie jak HTTP, Server-Sent Events (SSE) do przesyłania strumieniowego w czasie rzeczywistym i JSON-RPC do wymiany danych strukturalnych, co ułatwia integrację z istniejącą infrastrukturą IT.
Komunikacja asynchroniczna: protokół został zaprojektowany z myślą o komunikacji asynchronicznej, co ułatwia elastyczne wykonywanie zadań i umożliwia wysyłanie powiadomień push o aktualizacjach nawet wtedy, gdy połączenie nie jest utrzymywane w sposób ciągły.

5. Architektura agenta

W tym module utworzysz aplikację z wieloma agentami, która wygeneruje obraz zgodnie z Twoimi specyfikacjami i oceni go, zanim go wyświetli.

System ma strukturę z głównym agentem o nazwie image_scoring, który koordynuje cały proces. Ten główny agent ma podrzędnego agenta o nazwie image_generation_scoring_agent, który z kolei ma własnych podrzędnych agentów do bardziej szczegółowych zadań. Tworzy to relację hierarchiczną, w której główny agent deleguje zadania do swoich podagentów. Rysunek 2. Ogólny przepływ pracy agenta.

Lista wszystkich agentów

image_scoring (Main Agent):
Cel: jest to agent główny, który zarządza całym przepływem pracy. W pętli wielokrotnie uruchamia image_generation_scoring_agent i checker_agent, aż zostanie spełniony warunek zakończenia.
Sub-agenci:

image_generation_scoring_agent
checker_agent_instance

image_generation_scoring_agent (subagent usługi image_scoring):
Cel: ten agent odpowiada za podstawową logikę generowania i oceniania obrazów. W tym celu wykonuje sekwencję 3 podagentów.
Sub-agenci:

image_generation_prompt_agent
image_generation_agent
scoring_images_prompt

checker_agent_instance (podrzędny klient usługi image_scoring):
Cel: ten agent sprawdza, czy proces oceniania obrazu powinien być kontynuowany, czy zakończony. Do oceny warunku zakończenia używa narzędzia check_tool_condition.
image_generation_prompt_agent (podrzędny agent agenta image_generation_scoring_agent):
Cel: ten agent jest ekspertem w tworzeniu promptów do generowania obrazów. Otrzymuje on tekst wejściowy i generuje szczegółowy prompt odpowiedni dla modelu generowania obrazów.
image_generation_agent (subagent agenta image_generation_scoring_agent):
Cel: ten agent jest ekspertem w tworzeniu obrazów za pomocą modelu Imagen 3. Pobiera prompt z narzędzia image_generation_prompt_agent i generuje obraz.
scoring_images_prompt (podagent agenta image_generation_scoring_agent):
Cel: ten agent jest ekspertem w ocenianiu i punktowaniu obrazów na podstawie różnych kryteriów. Otrzymuje wygenerowany obraz i przypisuje mu ocenę.

Narzędzia używane przez agentów

check_tool_condition:
Opis: to narzędzie sprawdza, czy warunek zakończenia pętli został spełniony lub czy osiągnięto maksymalną liczbę iteracji. Jeśli któryś z tych warunków jest spełniony, pętla zostaje przerwana.
Używane przez: checker_agent_instance
generate_images:
Opis: to narzędzie generuje obrazy przy użyciu modelu Imagen 3. Może też zapisywać wygenerowane obrazy w zasobniku Google Cloud Storage.
Używane przez: image_generation_agent
get_policy:
Opis: to narzędzie pobiera zasady z pliku JSON. Zasady są używane przez image_generation_prompt_agent do tworzenia promptu generowania obrazów i przez scoring_images_prompt do oceniania obrazów.
Używane przez: image_generation_prompt_agent, scoring_images_prompt
get_image:
Opis: to narzędzie wczytuje wygenerowany artefakt obrazu, aby można było go ocenić.
Używane przez: scoring_images_prompt
set_score:
Opis: to narzędzie ustawia całkowity wynik wygenerowanego obrazu w stanie sesji.
Używane przez: scoring_images_prompt

6. Zadanie 1. Instalowanie ADK i konfigurowanie środowiska

W tym praktycznym module użyjemy Cloud Shell do wykonania zadań.

Włączanie zalecanych interfejsów API Vertex AI

W konsoli Google Cloud otwórz Vertex AI, wyszukując tę usługę u góry konsoli.
Kliknij Włącz wszystkie zalecane interfejsy API.

Przygotowywanie karty edytora Cloud Shell

W oknie konsoli Google Cloud otwórz Cloud Shell, naciskając klawisz G, a potem klawisz S na klawiaturze. Możesz też kliknąć przycisk Cloud Shell w prawym górnym rogu konsoli Google Cloud.
Kliknij Dalej.
Jeśli pojawi się pytanie o autoryzację Cloud Shell, kliknij Autoryzuj.
W prawym górnym rogu panelu Cloud Shell kliknij przycisk Otwórz w nowym oknie .
Aby wyświetlić pliki, u góry panelu kliknij ikonę ołówka Otwórz edytor ( ).
W górnej części menu nawigacyjnego po lewej stronie kliknij ikonę Eksploratora , aby otworzyć eksplorator plików.
Kliknij przycisk Otwórz folder.
W dalszej części tego modułu możesz pracować w tym oknie jako środowisku IDE z edytorem Cloud Shell i terminalem Cloud Shell.

Pobieranie i instalowanie ADK oraz przykładowego kodu na potrzeby tego modułu

Wykonaj te polecenia, aby sklonować potrzebne źródło z GitHub i zainstalować niezbędne biblioteki.

#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

Do zainstalowania dodatkowych wymagań użyjemy narzędzia Poetry:

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

Jeśli nie masz zasobnika Cloud Storage, utwórz nowy w Google Cloud Storage. Zasobnik możesz też utworzyć za pomocą polecenia gsutil.

gsutil mb gs://YOUR-UNIQUE-BUCKETNAME

W edytorze kliknij kolejno View (Widok) –> Toggle hidden files (Przełącz ukryte pliki). W folderze image_scoring utwórz plik .env o tej treści: Dodaj wymagane informacje, takie jak nazwa projektu i zasobnik Cloud Storage.

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.

Przyjrzyj się strukturze agenta w kodzie źródłowym, zaczynając od pliku agent.py . Ten agent zawiera agenta głównego, który będzie łączyć się z innymi agentami.
Wróć do katalogu głównego multiagenthandson w terminalu i wykonaj to polecenie, aby uruchomić agenta lokalnie:

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

Rysunek 1

Kliknij z naciśniętym klawiszem Ctrl (CMD w systemie MacOS) adres URL http:// wyświetlany w terminalu, aby otworzyć klienta GUI ADK w przeglądarce. Powinien wyglądać jak na rysunku 2.

Wygenerujmy kilka obrazów. Wypróbuj te prompty lub własne.
Spokojny górski krajobraz o zachodzie słońca
Kot na rowerze

Rysunek 2

7. Zadanie 2. Wdrażanie w silniku agenta

Teraz wdrażamy agenta w silniku agenta. Agent Engine to w pełni zarządzana usługa do wdrażania agentów w GCP. Agent Engine jest zgodny z pakietem ADK, więc agenty utworzone za pomocą tego pakietu można wdrażać w Agent Engine.

Zdefiniuj zmienne środowiskowe.

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

Utwórz plik requirements.txt za pomocą narzędzia Poetry. Poetry użyje pliku pyproject.toml do utworzenia pliku requirements.txt. Po uruchomieniu polecenia sprawdź, czy utworzono plik 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

Utwórz pakiet. Musimy spakować aplikację w pakiet Pythona .whl. Wykorzystamy do tego poezję. Po wykonaniu polecenia sprawdź, czy utworzono folder dist i czy zawiera on plik .whl.

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

Teraz przygotujemy skrypt wdrażania. Skrypt wdrażania wdroży agenta oceny obrazów lub usługę silnika agenta. Zmień zawartość pliku deploy.py w folderze image_scoring w sposób podany poniżej.

# 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)

Możemy teraz uruchomić skrypt wdrażania.

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

Po wdrożeniu powinien pojawić się ekran podobny do tego poniżej:

Ilustracja 3

Teraz przetestujmy wdrożonego agenta. Aby przetestować zdalnie wdrożony silnik agenta, najpierw skopiuj lokalizację agenta z danych wyjściowych wdrożenia w terminalu. Powinna ona wyglądać mniej więcej tak: projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680 .
Przejdź do folderu testclient,otwórz plik remote_test.py i edytuj te wiersze:

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. Zadanie 3. Tworzenie agenta A2A

W tym kroku utworzymy prostego agenta A2A na podstawie agenta utworzonego w poprzednich krokach. Obecnych agentów ADK można publikować w ramach protokołu A2A. Oto najważniejsze informacje, które poznasz w tym kroku.

Poznaj podstawy protokołu A2A.
Dowiedz się, jak protokoły ADK i A2A współpracują ze sobą.
Dowiedz się, jak korzystać z protokołu A2A.

W tym ćwiczeniu praktycznym użyjemy kodu z folderu image_scoring_adk_a2a_server. Zanim rozpoczniesz zadanie, zmień katalog na ten folder.

Tworzenie karty agenta A2A

Protokół A2A wymaga karty agenta, która zawiera wszystkie informacje o agencie, takie jak jego możliwości czy przewodnik po korzystaniu z niego. Po wdrożeniu agenta A2A kartę agenta można wyświetlić za pomocą linku „.well-known/agent-card.json”. Klienci mogą korzystać z tych informacji, aby wysyłać prośby do pracowników obsługi klienta.

W folderze remote_a2a/image_scoring sprawdź, czy znajduje się w nim plik agents.json o tej zawartości:

{
 "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"
     ]
   }
 ]
}

Tworzenie agenta A2A

W folderze głównym image_scoring_adk_a2a_server sprawdź, czy znajduje się plik a2a_agent.py, który jest punktem wejścia agenta A2A. Powinien zawierać te informacje:

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
)

Uruchamianie agenta A2A

Możemy teraz uruchomić agenta. Aby uruchomić agenta, wykonaj to polecenie w głównym folderze 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

Testowanie agenta A2A

Gdy agent będzie działać, możemy go przetestować. Najpierw sprawdźmy kartę agenta.

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

Wykonanie powyższego polecenia powinno spowodować wyświetlenie karty agenta A2A, która zawiera głównie treść pliku agent.json utworzonego w poprzednim kroku.

Wyślijmy teraz prośbę do agenta. Aby wysłać żądanie do agenta, możemy użyć polecenia 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"
      }
    }
  }'

W powyższym żądaniu możesz zmienić prompt, modyfikując wiersz „Utwórz obraz kota”. Po uruchomieniu polecenia możesz sprawdzić obraz wyjściowy w określonym Google Cloud Storage.

9. Czyszczenie danych

Teraz posprzątajmy to, co właśnie utworzyliśmy.

Usuń utworzony przed chwilą serwer Agent Engine. Otwórz Vertex AI, wpisując „Vertex AI” na pasku wyszukiwania w konsoli Google Cloud. Po lewej stronie kliknij Agent Engine.Aby usunąć agenta, kliknij Usuń.

Ilustracja 4

Usuwanie plików w Cloud Shell

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

Usuń zasobnik. W konsoli GCP wybierz Cloud Storage , a następnie wybierz i usuń zasobnik.