Halaman ini diterjemahkan oleh Cloud Translation API.

Buat sistem multi-agen dengan ADK, deploy di Agent Engine, dan mulai menggunakan protokol A2A

1. Tujuan lab ini

Dalam lab interaktif ini, Anda akan membuat aplikasi multi-agen yang menghasilkan gambar berdasarkan perintah Anda dan mengevaluasinya berdasarkan perintah Anda. Jika gambar tidak memenuhi persyaratan yang dijelaskan dalam perintah dengan memuaskan, agen akan terus membuat gambar hingga gambar yang memenuhi persyaratan Anda dibuat. Setiap agen dalam latihan ini memiliki satu tujuan, yaitu bekerja sama dengan agen lain untuk mencapai tujuan keseluruhan.

Yang akan Anda pelajari

Pahami dasar-dasar ADK dan pelajari cara membuat sistem multi-agen.
Pelajari cara men-deploy dan menggunakan agen dengan mudah di GCP.
Memahami dasar-dasar protokol A2A
Pelajari cara menggunakan protokol A2A dan ADK bersama-sama untuk membuat agen terbuka.

2. Sebelum memulai

Jika Anda belum memiliki project yang dapat digunakan, Anda harus membuat project baru di konsol GCP.
Dalam lab ini, kita akan menggunakan GCP Cloud Shell untuk menjalankan tugas. Buka Cloud Shell dan tetapkan project menggunakan Cloud Shell.
Buka GCP Cloud Shell Editor dengan menekan Tombol Cloud Shell Editor. Jika Anda melihat pop-up "Authorize Shell", klik untuk memberikan otorisasi pada Cloud Shell Editor.
Anda dapat memeriksa apakah project sudah diautentikasi menggunakan perintah berikut.

gcloud auth list

Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi project Anda

gcloud config list project

Jika project Anda belum ditetapkan, gunakan perintah berikut untuk menetapkannya

gcloud config set project <YOUR_PROJECT_ID>

Kita perlu mengaktifkan beberapa layanan untuk menjalankan lab ini. Jalankan perintah berikut di Cloud Shell.

gcloud services enable aiplatform.googleapis.com

3. Ringkasan: Manfaat Agent Development Kit

Agent Development Kit menawarkan beberapa keuntungan utama bagi developer yang membangun aplikasi agentic:

Sistem Multi-Agen: Bangun aplikasi modular dan skalabel dengan menyusun beberapa agen khusus dalam hierarki. Memungkinkan koordinasi dan pendelegasian yang kompleks.
Ekosistem Alat yang Kaya: Lengkapi agen dengan berbagai kemampuan: gunakan alat bawaan (Penelusuran, Eksekusi Kode, dll.), buat fungsi kustom, integrasikan alat dari framework agen pihak ketiga (LangChain, CrewAI), atau bahkan gunakan agen lain sebagai alat.
Orkestrasi Fleksibel: Tentukan alur kerja menggunakan agen alur kerja (SequentialAgent, ParallelAgent, dan LoopAgent) untuk pipeline yang dapat diprediksi, atau manfaatkan perutean dinamis yang didorong LLM (transfer LlmAgent) untuk perilaku adaptif.
Pengalaman Developer Terintegrasi: Kembangkan, uji, dan debug secara lokal dengan CLI yang canggih dan UI dev interaktif. Periksa peristiwa, status, dan langkah eksekusi agen langkah demi langkah.
Evaluasi Bawaan: Menilai performa agen secara sistematis dengan mengevaluasi kualitas respons akhir dan lintasan eksekusi langkah demi langkah terhadap kasus pengujian yang telah ditentukan sebelumnya.
Siap Di-deploy: Masukkan agen Anda ke dalam container dan deploy di mana saja – jalankan secara lokal, lakukan penskalaan dengan Vertex AI Agent Engine, atau lakukan integrasi ke dalam infrastruktur kustom menggunakan Cloud Run atau Docker.

Meskipun SDK atau framework agen AI Generatif lainnya juga memungkinkan Anda membuat kueri model dan bahkan melengkapinya dengan alat, koordinasi dinamis antara beberapa model memerlukan banyak pekerjaan di pihak Anda.

Agent Development Kit menawarkan framework tingkat yang lebih tinggi daripada alat ini, sehingga Anda dapat dengan mudah menghubungkan beberapa agen satu sama lain untuk alur kerja yang kompleks, tetapi mudah dikelola.

4. Pengantar A2A

Protokol Agent2Agent (A2A) adalah standar terbuka yang dirancang untuk memungkinkan komunikasi dan kolaborasi yang lancar dan aman antara agen AI otonom dari berbagai framework, vendor, dan domain.

Interoperabilitas Universal: A2A memungkinkan agen bekerja sama terlepas dari teknologi yang mendasarinya, sehingga mendorong ekosistem multi-agen yang sesungguhnya. Artinya, agen yang dibuat oleh perusahaan yang berbeda di platform yang berbeda dapat berkomunikasi dan berkoordinasi.
Penemuan Kemampuan: Agen dapat mengiklankan kemampuannya menggunakan "Kartu Agen" (dokumen JSON), yang menjelaskan identitas, fitur A2A yang didukung, keterampilan, dan persyaratan autentikasinya. Hal ini memungkinkan agen lain menemukan dan memilih agen yang paling sesuai untuk tugas tertentu.
Aman secara Default: Keamanan adalah prinsip inti. A2A menggabungkan mekanisme autentikasi dan otorisasi tingkat perusahaan, yang memanfaatkan standar seperti HTTPS/TLS, JWT, OIDC, dan kunci API untuk memastikan interaksi yang aman dan melindungi data sensitif.
Agnostik Modalitas: Protokol ini mendukung berbagai modalitas komunikasi, termasuk streaming teks, audio, dan video, serta formulir interaktif dan iframe yang disematkan. Fleksibilitas ini memungkinkan agen bertukar informasi dalam format yang paling sesuai untuk tugas dan pengguna.
Pengelolaan Tugas Terstruktur: A2A menentukan protokol yang jelas untuk delegasi, pemantauan, dan penyelesaian tugas. Fitur ini mendukung pengelompokan tugas terkait dan pengelolaannya di berbagai agen menggunakan ID tugas unik. Tugas dapat bertransisi melalui siklus proses yang ditentukan (misalnya, dikirim, sedang dikerjakan, selesai).
Eksekusi Opaque: Fitur pentingnya adalah bahwa agen tidak perlu mengungkapkan proses penalaran internal, memori, atau alat tertentu kepada agen lain. Mereka hanya mengekspos layanan yang dapat dipanggil, sehingga meningkatkan modularitas dan privasi.
Dibuat Berdasarkan Standar yang Ada: A2A memanfaatkan teknologi web yang sudah mapan seperti HTTP, Peristiwa yang Dikirim Server (SSE) untuk streaming real-time, dan JSON-RPC untuk pertukaran data terstruktur, sehingga memudahkan integrasi dengan infrastruktur IT yang ada.
Komunikasi Asinkron: Protokol ini dirancang dengan komunikasi asinkron sebagai pertimbangan utama, yang memfasilitasi progres tugas yang fleksibel dan memungkinkan notifikasi push untuk pembaruan meskipun koneksi tidak dipertahankan secara terus-menerus.

5. Arsitektur Agen

Di lab ini, Anda akan membuat aplikasi multi-agen yang menghasilkan gambar sesuai dengan spesifikasi Anda dan mengevaluasi gambar tersebut sebelum menampilkannya kepada Anda.

Sistem ini disusun dengan agen utama bernama image_scoring yang mengatur seluruh proses. Agen utama ini memiliki sub-agen yang disebut image_generation_scoring_agent yang pada gilirannya memiliki sub-agennya sendiri untuk tugas yang lebih spesifik. Hal ini akan membuat hubungan hierarkis di mana agen utama mendelegasikan tugas ke sub-agennya. Gambar 2: Alur Agen secara keseluruhan.

Daftar Semua Agen

image_scoring (Agen Utama):
Tujuan: Ini adalah agen root yang mengelola alur kerja secara keseluruhan. Loop ini berulang kali menjalankan image_generation_scoring_agent dan checker_agent dalam loop hingga kondisi penghentian terpenuhi.
Sub-agen:

image_generation_scoring_agent
checker_agent_instance

image_generation_scoring_agent (Sub-agen image_scoring):
Tujuan: Agen ini bertanggung jawab atas logika inti untuk membuat dan memberi skor pada gambar. Untuk melakukannya, agen ini menjalankan urutan tiga sub-agen.
Sub-agen:

image_generation_prompt_agent
image_generation_agent
scoring_images_prompt

checker_agent_instance (Sub-agen image_scoring):
Tujuan: Agen ini memeriksa apakah proses pemberian skor gambar harus dilanjutkan atau dihentikan. Lingkungan ini menggunakan alat check_tool_condition untuk mengevaluasi kondisi penghentian.
image_generation_prompt_agent (Sub-agen image_generation_scoring_agent):
Tujuan: Agen ini adalah pakar dalam membuat perintah untuk pembuatan gambar. Fitur ini menerima teks input dan menghasilkan perintah terperinci yang sesuai untuk model pembuatan gambar.
image_generation_agent (Sub-agen image_generation_scoring_agent):
Tujuan: Agen ini adalah pakar dalam membuat gambar menggunakan Imagen 3. Agen ini mengambil perintah dari image_generation_prompt_agent dan membuat gambar.
scoring_images_prompt (Sub-agen image_generation_scoring_agent):
Tujuan: Agen ini adalah pakar dalam mengevaluasi dan memberi skor pada gambar berdasarkan berbagai kriteria. Fungsi ini mengambil gambar yang dihasilkan dan menetapkan skor padanya.

Alat yang Digunakan oleh Agen

check_tool_condition:
Deskripsi: Alat ini memeriksa apakah kondisi penghentian loop terpenuhi atau apakah jumlah maksimum iterasi telah tercapai. Jika salah satunya benar, loop akan berhenti.
Digunakan oleh: checker_agent_instance
generate_images:
Deskripsi: Alat ini menghasilkan gambar menggunakan model Imagen 3. Selain itu, aplikasi ini dapat menyimpan gambar yang dihasilkan ke bucket Google Cloud Storage.
Digunakan oleh: image_generation_agent
get_policy:
Deskripsi: Alat ini mengambil kebijakan dari file JSON. Kebijakan ini digunakan oleh image_generation_prompt_agent untuk membuat perintah pembuatan gambar dan oleh scoring_images_prompt untuk memberi skor pada gambar.
Digunakan oleh: image_generation_prompt_agent, scoring_images_prompt
get_image:
Deskripsi: Alat ini memuat artefak gambar yang dihasilkan sehingga dapat diberi skor.
Digunakan oleh: scoring_images_prompt
set_score:
Deskripsi: Alat ini menetapkan skor total gambar yang dihasilkan dalam status sesi.
Digunakan oleh: scoring_images_prompt

6. Tugas 1. Menginstal ADK dan menyiapkan lingkungan Anda

Dalam latihan ini, kita akan menggunakan Cloud Shell untuk melakukan tugas.

Mengaktifkan API yang direkomendasikan Vertex AI

Di Konsol Google Cloud, buka Vertex AI dengan menelusurinya di bagian atas konsol.
Klik Enable all recommended APIs.

Menyiapkan tab Cloud Shell Editor

Dengan jendela Konsol Google Cloud Anda dipilih, buka Cloud Shell dengan menekan tombol G, lalu tombol S di keyboard Anda. Atau, Anda dapat mengklik tombol Cloud Shell di pojok kanan atas Konsol Google Cloud.
Klik Lanjutkan.
Saat diminta untuk memberikan otorisasi pada Cloud Shell, klik Authorize.
Di pojok kanan atas panel Cloud Shell, klik tombol Open in new window .
Klik ikon pensil Open Editor ( ) di bagian atas panel untuk melihat file.
Di bagian atas menu navigasi sebelah kiri, klik ikon Explorer untuk membuka penjelajah file Anda.
Klik tombol Open Folder.
Selama sisa lab ini, Anda dapat bekerja di jendela ini sebagai IDE dengan Cloud Shell Editor dan Cloud Shell Terminal.

Download dan instal ADK serta contoh kode untuk lab ini

Jalankan perintah berikut untuk meng-clone sumber yang diperlukan dari github dan menginstal library yang diperlukan.

#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

Kita akan menggunakan poetry untuk menginstal persyaratan tambahan:

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

Jika Anda tidak memiliki bucket penyimpanan cloud, buat bucket baru di Google Cloud Storage. Anda juga dapat membuat bucket menggunakan perintah gsutil.

gsutil mb gs://YOUR-UNIQUE-BUCKETNAME

Di editor, buka View->Toggle hidden files. Di folder image_scoring, buat file .env dengan konten berikut. Tambahkan detail yang diperlukan seperti nama project dan bucket Cloud Storage Anda.

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.

Lihat struktur agen dalam kode sumber, mulai dari agent.py . Agen ini berisi agen root yang akan terhubung ke agen lainnya.
Kembali ke direktori teratas multiagenthandson di terminal dan jalankan perintah berikut untuk menjalankan agen secara lokal

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

Gambar 1

Ctrl+Klik (CMD+Klik untuk MacOS) pada URL http:// yang ditampilkan di terminal untuk membuka klien GUI berbasis browser ADK. Tampilannya akan terlihat seperti Gambar 2

Mari buat beberapa gambar. Coba perintah berikut atau perintah Anda sendiri.
Lanskap pegunungan yang tenang saat matahari terbenam
Kucing mengendarai sepeda

Gambar 2

7. Tugas 2. Men-deploy ke Agent Engine

Sekarang kita men-deploy agen ke Agent Engine. Agent Engine adalah layanan terkelola sepenuhnya untuk men-deploy agen di GCP. Agent Engine kompatibel dengan ADK sehingga agen yang dibuat dengan ADK dapat di-deploy di Agent Engine.

Tentukan beberapa variabel lingkungan

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

Buat file requirements.txt menggunakan poetry. Poetry akan menggunakan pyproject.toml untuk membuat file requirements.txt. Setelah menjalankan perintah, periksa apakah file requirements.txt telah dibuat.

# 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

Buat paket. Kita perlu memaketkan aplikasi ke dalam paket Python .whl. Kita akan menggunakan puisi untuk melakukannya. Setelah menjalankan perintah, pastikan folder dist dibuat dan berisi file .whl.

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

Sekarang kita akan menyiapkan skrip deployment. Skrip deployment akan men-deploy layanan image-scoring agent atau agent engine kami. Ubah konten deploy.py di dalam folder image_scoring seperti di bawah.

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

Sekarang kita dapat menjalankan skrip deployment.

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

Setelah men-deploy, Anda akan melihat sesuatu seperti di bawah,

Gambar 3

Sekarang, mari kita uji agen yang di-deploy. Untuk menguji mesin agen yang di-deploy dari jarak jauh, salin terlebih dahulu lokasi agen dari output deployment di terminal. Tampilannya akan terlihat seperti ini, projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680 .
Buka folder testclient, buka file remote_test.py, lalu edit baris berikut.

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. Tugas 3. Membuat agen A2A

Pada langkah ini, kita akan membuat agen A2A sederhana berdasarkan agen yang kita buat pada langkah sebelumnya. Agen ADK yang ada dapat dipublikasikan dengan protokol A2A. Berikut adalah hal-hal penting yang akan Anda pelajari di langkah ini.

Pelajari dasar-dasar protokol A2A.
Pelajari cara kerja protokol ADK dan A2A satu sama lain.
Pelajari cara berinteraksi dengan protokol A2A.

Dalam latihan ini, kita akan menggunakan kode di folder image_scoring_adk_a2a_server. Sebelum memulai tugas, ubah direktori Anda ke folder ini.

Membuat kartu agen A2A

Protokol A2A memerlukan kartu agen yang berisi semua informasi tentang agen seperti kemampuan agen, panduan penggunaan agen, dll. Setelah agen A2A di-deploy, kartu agen dapat dilihat menggunakan link ".well-known/agent-card.json". Klien dapat merujuk pada informasi ini untuk mengirim permintaan ke agen.

Di folder remote_a2a/image_scoring, pastikan ada agents.json dengan konten berikut.

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

Buat agen A2A

Dalam folder root image_scoring_adk_a2a_server, pastikan ada file a2a_agent.py, yang merupakan titik entri untuk agen a2a. Class harus memiliki konten berikut,

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
)

Menjalankan agen A2A

Sekarang kita siap menjalankan agen. Untuk menjalankan agen, jalankan perintah berikut dari dalam folder teratas 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

Menguji agen A2A

Setelah agen berjalan, kita dapat menguji agen. Pertama-tama, mari kita periksa kartu agen.

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

Menjalankan perintah di atas akan menampilkan kartu agen untuk agen A2A kita, yang sebagian besar merupakan konten agent.json yang kita buat di langkah sebelumnya.

Sekarang, kirim permintaan ke agen. Kita dapat menggunakan curl untuk mengirim permintaan ke agen,

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"
      }
    }
  }'

Dalam permintaan di atas, Anda dapat mengubah perintah dengan mengubah baris "Create an image of a cat". Setelah menjalankan perintah, Anda dapat memeriksa gambar output di Google Cloud Storage yang ditentukan.

9. Pembersihan

Sekarang, mari kita hapus apa yang baru saja kita buat.

Hapus server Agent Engine yang baru saja kita buat. Buka Vertex AI dengan mengetik Vertex AI di kotak penelusuran Konsol Google Cloud. Klik Agent Engine di sisi kiri.Anda dapat menghapus Agen dengan mengklik hapus.

Gambar 4

Hapus file di Cloud Shell

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

Hapus bucket. Anda dapat membuka konsol GCP -> Cloud Storage, memilih, lalu menghapus bucket Anda.