Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

ADK ile birden fazla temsilci sistemi oluşturma, Agent Runtime'da dağıtma ve A2A protokolünü kullanmaya başlama

1. Bu laboratuvarın amacı

Bu uygulamalı laboratuvarda, isteminize göre görüntü oluşturan ve isteminize göre değerlendiren ADK (Agent Development Kit) kullanarak çoklu ajan uygulaması oluşturacaksınız. Görüntü, istemde açıklanan koşulları yeterince karşılamıyorsa temsilci, koşullarınızı karşılayan görüntü oluşturulana kadar sürekli olarak görüntü üretir. Bu uygulamalı etkinlikteki her aracının tek bir amacı vardır. Aracılar, genel hedefe ulaşmak için birbirleriyle işbirliği yapar. Uygulamayı yerel olarak test etmeyi ve Agent Runtime'da dağıtmayı öğreneceksiniz.

Neler öğreneceksiniz?

ADK (Agent Development Kit) 'nın temellerini öğrenin ve çoklu temsilci sistemi oluşturmayı öğrenin.
Aracıları Agent Runtime'da kolayca dağıtıp kullanmayı öğrenin.
A2A protokolünün temel bilgilerini öğrenin.
Açık temsilciler oluşturmak için A2A protokolünü ve ADK'yı (Agent Development Kit) birlikte kullanmayı öğrenin.

2. Proje Ayarları

GCP Console bağlantısını tıklayarak GCP Console'a gidin.
Kullanabileceğiniz bir projeniz yoksa GCP Console'da yeni bir proje oluşturmanız gerekir. Proje seçicide (Google Cloud Console'un sol üst kısmı) projeyi seçin. Henüz bir projeniz yoksa yeni proje oluşturmak için lütfen bu adımları uygulayın. Yeni bir proje oluşturduktan sonra lütfen projenizi seçin.

Şekil 2: Google Cloud logosunun hemen yanındaki kutuyu tıklayarak projenizi seçebilirsiniz. Projenizin seçili olduğundan emin olun.

Bu laboratuvarda görevlerimizi gerçekleştirmek için Cloud Shell Düzenleyici'yi kullanacağız. Cloud Shell'i açın ve Cloud Shell'i kullanarak projeyi ayarlayın.
Doğrudan Cloud Shell Düzenleyici'ye gitmek için bu bağlantıyı tıklayın.
Cloud Shell Düzenleyici'nin yan çubuğunda Open Folder (Klasör Aç) düğmesini tıklayın.
Ana klasörünüz zaten seçilmiş olmalıdır. Tamam'a basmanız yeterlidir. Ana klasörünüz bu görev için kök klasörünüz olur.
Henüz açık değilse menüden Terminal>Yeni Terminal'i tıklayarak Terminal'i açın. Bu eğitimdeki tüm komutları bu terminalde çalıştırabilirsiniz.
Cloud Shell terminalinde aşağıdaki komutu kullanarak projenin kimliğinin doğrulanıp doğrulanmadığını kontrol edebilirsiniz.

gcloud auth list

Proje kimliğinizi hatırlamıyorsanız aşağıdaki komutla tüm proje kimliklerinizi listeleyebilirsiniz:

gcloud projects list

Proje kimliğini kopyalayın ve ayarlamak için aşağıdaki komutu kullanın.

gcloud config set project <YOUR_PROJECT_ID>

Projenizi onaylamak için Cloud Shell'de aşağıdaki komutu çalıştırın:

gcloud config list project

3. API'leri etkinleştir

Bu laboratuvarı çalıştırmak için bazı API hizmetlerini etkinleştirmemiz gerekiyor. Cloud Shell'de aşağıdaki komutu çalıştırın.

gcloud services enable aiplatform.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com

API'lerle tanışın

Gemini Enterprise Agent Platform API (aiplatform.googleapis.com), Gemini Enterprise Agent Platform platformuna erişimi etkinleştirir. Böylece uygulamanız, metin oluşturma, sohbet oturumları ve işlev çağrısı için Gemini modelleriyle etkileşim kurabilir.
Cloud Resource Manager API (cloudresourcemanager.googleapis.com), Google Cloud projelerinizin meta verilerini (ör. proje kimliği ve adı) programatik olarak yönetmenize olanak tanır. Bu meta veriler, proje kimliğini ve izinlerini doğrulamak için genellikle diğer araçlar ve SDK'lar tarafından gereklidir.

4. Agent Development Kit'e giriş

Agent Development Kit, yapay zeka destekli uygulamalar geliştiren geliştiriciler için çeşitli önemli avantajlar sunar:

Çoklu Ajan Sistemleri: Birden fazla uzmanlaşmış ajanı bir hiyerarşi içinde birleştirerek modüler ve ölçeklenebilir uygulamalar oluşturun. Karmaşık koordinasyon ve görevlendirmeyi etkinleştirin.
Zengin Araç Ekosistemi: Temsilcilere çeşitli özellikler kazandırın: Önceden oluşturulmuş araçları (Arama, Kod Yürütme vb.) kullanın, özel işlevler oluşturun, üçüncü taraf temsilci çerçevelerindeki (LangChain, CrewAI) araçları entegre edin veya hatta diğer temsilcileri araç olarak kullanın.
Esnek Düzenleme: Tahmin edilebilir ardışık düzenler için iş akışı aracılarını (SequentialAgent, ParallelAgent ve LoopAgent) kullanarak iş akışları tanımlayın veya uyarlanabilir davranış için LLM destekli dinamik yönlendirmeden (LlmAgent aktarımı) yararlanın.
Entegre geliştirici deneyimi: Güçlü bir CLI ve etkileşimli geliştirme kullanıcı arayüzü ile yerel olarak geliştirin, test edin ve hataları ayıklayın. Etkinlikleri, durumu ve aracı yürütme adımını adım adım inceleyin.
Yerleşik Değerlendirme: Hem nihai yanıt kalitesini hem de adım adım yürütme sürecini önceden tanımlanmış test senaryolarına göre değerlendirerek temsilci performansını sistematik olarak değerlendirin.
Dağıtıma Hazır: Aracılarınızı container'a dönüştürün ve istediğiniz yerde dağıtın. Yerel olarak çalıştırın, Agent Runtime ile ölçeklendirin veya Cloud Run ya da Docker kullanarak özel altyapıya entegre edin.

Diğer üretken yapay zeka SDK'ları veya aracı çerçeveleri de modelleri sorgulamanıza ve hatta araçlarla desteklemenize olanak tanır ancak birden fazla model arasında dinamik koordinasyon sağlamak için sizin tarafınızda önemli miktarda çalışma yapılması gerekir.

Temsilci Geliştirme Kiti, bu araçlardan daha üst düzey bir çerçeve sunar. Bu sayede, karmaşık ancak bakımı kolay iş akışları için birden fazla temsilciyi birbirine kolayca bağlayabilirsiniz.

Şekil 1: ADK (Agent Development Kit) konumlandırması

5. Agent Runtime'a giriş

Agent Runtime, Google Cloud'da aracı dağıtmak için kullanılan tümüyle yönetilen bir hizmettir. Agent Runtime ile geliştiriciler, Gemini Enterprise Agent Platform'da OSS yapay zeka ajanları( ADK (Agent Development Kit) , LangChain, LangGraph, CrewAI, AutoGen ve daha fazlası!) geliştirebilir, özelleştirebilir, dağıtabilir, sunabilir ve yönetebilir.

Agent Runtime, kullanıcı verilerini (aracı belleği olarak da bilinir) işlemek için de hizmetler sunar. Şu anda iki tür bellek hizmeti kullanılabilir.

Kısa süreli bellek: Agent Engine Oturumları ile devam eden ileti dizisi geçmişini (durum) tek bir oturumda kısa süreli bellek olarak saklayabilir, yönetebilir ve alabilirsiniz.
Uzun süreli hafıza: Agent Engine Memory Bank ile özellikle birden fazla oturumda anıları (durum) uzun süreli hafıza olarak saklayın, dönüştürün ve alın.

Aracıları Cloud Run veya GKE gibi diğer Google Cloud hizmetlerine de dağıtabilirsiniz. Aşağıdaki kullanım alanları için Agent Runtime'ı kullanmayı düşünebilirsiniz.

Durumlu yönetilen çalışma zamanı: Aracı dağıtımınız için durumlu ve tam olarak yönetilen bir çalışma zamanına ihtiyacınız varsa Agent Runtime, oturum yönetimi ve yapay zeka aracı kalıcılığı gibi yaygın görevleri soyutladığı için iyi bir seçimdir.
Kod Yürütme: Aracınızın, kullanıcı oturumu sırasında dinamik olarak oluşturulan kodu yürütmesi gerekiyorsa Agent Runtime, kodu yürütebileceğiniz güvenli bir Sandbox sağlar.
Esnek uzun süreli hafıza: Ajanlarınız için esnek uzun süreli hafızaya ihtiyacınız varsa Agent Runtime ile kullanılabilen Gemini Enterprise Agent Platform Memory Bank, kullanıcılarınızla ilgili bilgileri oturumlar arasında kullanılabilecek şekilde hatırlamak için esnek bir yöntem sunabilir.

Esnek bir uygulama mimarisi oluşturmak için Agent Runtime'ı Cloud Run gibi diğer çalışma zamanlarıyla da birleştirebilirsiniz. Aşağıda, bir aracı oluşturmak için çeşitli hizmetlerin kullanıldığı bir referans mimarisi örneği verilmiştir.

Şekil 2: Birden fazla hizmet kullanarak aracı oluşturmaya yönelik örnek bir referans mimarisi.

6. A2A'ya giriş

Agent2Agent (A2A) protokolü, farklı çerçeveler, tedarikçiler ve alanlardaki bağımsız yapay zeka ajanları arasında sorunsuz ve güvenli iletişim ile işbirliğini sağlamak için tasarlanmış açık bir standarttır.

Evrensel Birlikte Çalışabilirlik: A2A, temel teknolojilerinden bağımsız olarak temsilcilerin birlikte çalışmasına olanak tanıyarak gerçek anlamda çoklu temsilci ekosistemi oluşturur. Bu sayede, farklı platformlarda farklı şirketler tarafından oluşturulan temsilciler iletişim kurabilir ve koordineli çalışabilir.
Yetenek Keşfi: Ajanlar, kimliklerini, desteklenen A2A özelliklerini, becerilerini ve kimlik doğrulama gereksinimlerini açıklayan "Ajan Kartları" (JSON belgeleri) kullanarak yeteneklerini tanıtabilir. Bu sayede diğer temsilciler, belirli bir görev için en uygun temsilciyi bulup seçebilir.
Varsayılan olarak güvenli: Güvenlik, temel bir ilkedir. A2A, güvenli etkileşimler sağlamak ve hassas verileri korumak için HTTPS/TLS, JWT, OIDC ve API anahtarları gibi standartları kullanan kurumsal düzeyde kimlik doğrulama ve yetkilendirme mekanizmalarını içerir.
Biçimden Bağımsız: Protokol; metin, ses ve video akışı gibi çeşitli iletişim biçimlerinin yanı sıra etkileşimli formları ve yerleştirilmiş iFrame'leri destekler. Bu esneklik, temsilcilerin görev ve kullanıcı için en uygun biçimde bilgi alışverişinde bulunmasına olanak tanır.
Yapılandırılmış Görev Yönetimi: A2A, görev atama, izleme ve tamamlama için net protokoller tanımlar. İlgili görevlerin gruplandırılmasını ve benzersiz görev kimlikleri kullanılarak farklı aracılar arasında yönetilmesini destekler. Görevler, tanımlanmış yaşam döngülerinden (ör. gönderildi, üzerinde çalışılıyor, tamamlandı) geçebilir.
Opak Yürütme: Önemli bir özellik, aracıların diğer aracılara kendi içindeki muhakeme süreçlerini, hafızasını veya belirli araçlarını açıklamasına gerek olmamasıdır. Yalnızca çağrılabilir hizmetlerini kullanıma sunarak modülerliği ve gizliliği desteklerler.
Mevcut Standartlar Üzerine Kurulmuştur: A2A, HTTP, Server-Sent Events (SSE) (gerçek zamanlı akış için) ve JSON-RPC (yapılandırılmış veri değişimi için) gibi yerleşik web teknolojilerinden yararlanır. Bu sayede mevcut BT altyapısıyla entegrasyon kolaylaşır.
Asenkron İletişim: Protokol, asenkron iletişim öncelikli olacak şekilde tasarlanmıştır. Bu sayede görevlerin esnek bir şekilde ilerlemesi kolaylaşır ve bağlantı sürekli olarak korunmasa bile güncellemeler için anlık bildirimler etkinleştirilebilir.

7. Aracı Mimarisi

Bu laboratuvarda, belirttiğiniz özelliklere göre görüntü oluşturan ve görüntüyü size sunmadan önce değerlendiren çok agent'lı bir uygulama oluşturacaksınız.

Sistem, tüm süreci yöneten image_scoring adlı ana bir aracıyla yapılandırılmıştır. Bu ana ajanın image_generation_scoring_agent adlı bir alt ajanı vardır. Bu alt ajanın da daha spesifik görevler için kendi alt ajanları bulunur. Bu durumda, ana ajan görevleri alt ajanlarına devreder.

Şekil 3: Genel Ajan akışı.

Tüm Ajanların Listesi

Ajan	Purpose	Alt aracılar
image_scoring (Main Agent)	Bu, genel iş akışını yöneten kök aracıdır. Sonlandırma koşulu karşılanana kadar image_generation_scoring_agent ve checker_agent'ı döngü içinde tekrar tekrar çalıştırır.	image_generation_scoring_agent checker_agent_instance
image_generation_scoring_agent (image_scoring alt aracısı)	Bu aracı, resim oluşturma ve puanlama işlemlerinin temel mantığından sorumludur. Bunu yapmak için üç alt aracının sırasını yürütür.	image_generation_prompt_agent image_generation_agent scoring_images_prompt
checker_agent_instance (image_scoring alt aracısı)	Bu ajan, resim puanlama sürecinin devam etmesi veya sonlandırılması gerektiğini kontrol eder. Sonlandırma koşulunu değerlendirmek için check_tool_condition aracını kullanır.	-
checker_agent_instance (image_scoring alt aracısı)	Bu ajan, görüntü üretme için istem oluşturma konusunda uzmandır. Giriş metnini alır ve görüntü üretme modeline uygun ayrıntılı bir istem oluşturur.	-
image_generation_prompt_agent (image_generation_scoring_agent'ın alt aracısı)	Bu ajan, görüntü üretme için istem oluşturma konusunda uzmandır. Giriş metnini alır ve görüntü üretme modeline uygun ayrıntılı bir istem oluşturur.	-
scoring_images_prompt (image_generation_scoring_agent alt ajanı):	Bu aracı, çeşitli ölçütlere göre görüntüleri değerlendirme ve puanlama konusunda uzmandır. Üretilen görüntüyü alıp puanlandırır.	-

Kullanılan Tüm Araçların Listesi

Araç	Açıklama	Kullanıcı aracısı
check_tool_condition	Bu araç, döngü sonlandırma koşulunun karşılanıp karşılanmadığını veya maksimum yineleme sayısına ulaşılıp ulaşılmadığını kontrol eder. Bu koşullardan biri doğruysa döngü durdurulur.	checker_agent_instance
generate_images	Bu araç, Imagen 3 modelini kullanarak görüntüler oluşturur. Ayrıca, oluşturulan görüntüleri bir Google Cloud Storage paketine de kaydedebilir.	image_generation_agent
get_policy	Bu araç, bir JSON dosyasından politika getirir. Politika, image_generation_prompt_agent tarafından görüntü oluşturma istemini oluşturmak, scoring_images_prompt tarafından ise görüntüleri puanlamak için kullanılır.	image_generation_agent
get_image	Bu araç, oluşturulan görüntü yapısını puanlanabilmesi için yükler.	scoring_images_prompt
set_score	Bu araç, oturum durumunda oluşturulan resmin toplam puanını ayarlar.	scoring_images_prompt

8. ADK'yı yükleme ve ortamınızı ayarlama

Bu uygulamalı laboratuvarda görevleri gerçekleştirmek için Cloud Shell'i kullanacağız.

Cloud Shell Düzenleyici sekmesi hazırlama (Cloud Shell Düzenleyici zaten açıksa bu adımı atlayın)

GCP Console bağlantısını tıklayarak GCP Console'a gidin.
Kullanabileceğiniz bir projeniz yoksa GCP Console'da yeni bir proje oluşturmanız gerekir. Proje seçicide (Google Cloud Console'un sol üst kısmı) projeyi seçin. Henüz bir projeniz yoksa yeni proje oluşturmak için lütfen bu adımları uygulayın. Yeni bir proje oluşturduktan sonra lütfen projenizi seçin.

Şekil 2: Google Cloud logosunun hemen yanındaki kutuyu tıklayarak projenizi seçebilirsiniz. Projenizin seçili olduğundan emin olun.

Bu laboratuvarda görevlerimizi gerçekleştirmek için Cloud Shell Düzenleyici'yi kullanacağız. Cloud Shell'i açın ve Cloud Shell'i kullanarak projeyi ayarlayın.
Doğrudan Cloud Shell Düzenleyici'ye gitmek için bu bağlantıyı tıklayın.
Cloud Shell Düzenleyici'nin yan çubuğunda Open Folder (Klasör Aç) düğmesini tıklayın.
Ana klasörünüz zaten seçilmiş olmalıdır. Tamam'a basmanız yeterlidir. Ana klasörünüz bu görev için kök klasörünüz olur.
Henüz açık değilse menüden Terminal>Yeni Terminal'i tıklayarak Terminal'i açın. Bu eğitimdeki tüm komutları bu terminalde çalıştırabilirsiniz.
Cloud Shell terminalinde aşağıdaki komutu kullanarak projenin kimliğinin doğrulanıp doğrulanmadığını kontrol edebilirsiniz.

gcloud auth list

Proje kimliğinizi hatırlamıyorsanız aşağıdaki komutla tüm proje kimliklerinizi listeleyebilirsiniz:

gcloud projects list

Proje kimliğini kopyalayın ve ayarlamak için aşağıdaki komutu kullanın.

gcloud config set project <YOUR_PROJECT_ID>

Projenizi onaylamak için Cloud Shell'de aşağıdaki komutu çalıştırın:

gcloud config list project

Bu laboratuvar için ADK'yı ve kod örneklerini indirip yükleyin.

Gerekli kaynağı GitHub'dan klonlamak ve gerekli kitaplıkları yüklemek için aşağıdaki komutları yürütün. Komutları Cloud Shell Düzenleyici'de açılan terminalde çalıştırın.

#create the project directory
mkdir ~/imagescoring
cd ~/imagescoring

#clone the code in the local directory
git clone https://github.com/haren-bh/multiagenthandson.git

Python ortamı oluşturmak için uv'yi kullanacağız (Cloud Shell Düzenleyici Terminali'nde çalıştırın):

#Install uv if you do not have installed yet
pip install uv

#Create the virtual environment
uv venv .adkvenv

source .adkvenv/bin/activate

#go to the project directory
cd ~/imagescoring/multiagenthandson

#install dependencies
uv pip install -r pyproject.toml

Bulut depolama alanı paketiniz yoksa Google Cloud Storage'da yeni bir paket oluşturun. Bucket'ı gcloud komutunu kullanarak da oluşturabilirsiniz. Agent Runtime'a Google Cloud Storage erişimi verin (Cloud Shell Düzenleyici Terminali'nde çalıştırın).

# First, make sure your PROJECT_ID variable is set
PROJECT_ID=$(gcloud config get-value project)

# Now, create the bucket with a unique name
# We'll use the project ID to help ensure uniqueness
gcloud storage buckets create gs://${PROJECT_ID}-imagescoring-bucket

#Now lets give Agent Runtime the permission to access Cloud Storage
# 1. Get the current Project ID (text) and Project Number (numeric)
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# 2. Construct the Reasoning Engine Service Account email
SA_EMAIL="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
# 3. Create Agent Runtime Service account if not already created
gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_NUMBER}

# 3. Grant GCS Access
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/storage.objectUser" --condition=None

Düzenleyicide Görünüm > Gizli dosyaları aç/kapat'a gidin. Ayrıca image_scoring klasöründe aşağıdaki içerikle bir .env dosyası oluşturun. Proje adınız ve Cloud Storage paketi gibi gerekli ayrıntıları ekleyin (Cloud Shell Editor Terminal'de çalıştırın).

#go to image_scoring folder
cd ~/imagescoring/multiagenthandson/image_scoring

cat <<EOF>> .env
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
GOOGLE_CLOUD_LOCATION=global
AGENT_ENGINE_LOCATION=us-central1
GOOGLE_CLOUD_STORAGE_BUCKET=$(gcloud config get-value project)-imagescoring-bucket
GCS_BUCKET_NAME=$(gcloud config get-value project)-imagescoring-bucket
SCORE_THRESHOLD=40
IMAGEN_MODEL="gemini-3.1-flash-lite-image"
GENAI_MODEL="gemini-3.5-flash"
EOF

Gezgin yan bölmesinde imagescoring/multiagenthandson/image_scoring klasörüne gidin. agent.py dosyasını tıklayarak açın ve buradaki aracı yapısına göz atın. Bu aracı, diğer alt aracılara bağlanacak kök aracı içerir.

Şekil 4: Gezgin yan bölmesinden görülebilen klasör yapısı. Dosyanın içeriğini görmek için dosyayı tıklamanız yeterlidir.

Terminalde en üstteki multiagenthandson dizinine geri dönün ve aracı yerel olarak çalıştırmak için aşağıdaki komutu yürütün (Cloud Shell Düzenleyici Terminali'nde çalıştırın).

#go to the directory multiagenthandson
cd ~/imagescoring/multiagenthandson
# Run the following command to run agents locally
adk web --host 0.0.0.0 --port 8080 --allow_origins "regex:https://.*8080-.*\.cloudshell\.dev"

Şekil 5: ADK uygulamasının başlatılması

ADK'nın tarayıcı tabanlı GUI istemcisini açmak için terminalde gösterilen http:// URL'sini Ctrl+Tıkla (MacOS için CMD+Tıkla) ile tıklayın. Şekil 5'teki gibi görünmelidir.
Sol üst taraftaki açılır menüden image_scoring'i seçin (Şekil 5'e bakın). Şimdi de birkaç resim oluşturalım. Resimleri Google Cloud Storage paketinde de bulabilirsiniz. Kaydedilen resimlerinizi yerel olarak görmek için "Öğeler" bölümünü tıklayabilirsiniz. Aşağıdaki istemleri veya kendi istemlerinizi deneyin.

Gün batımında huzurlu bir dağ manzarası
Bisiklet süren bir kedi

Şekil 6: Örnek çıktı

9. Agent Runtime'a dağıtma

Şimdi de aracıyı Agent Engine'e dağıtıyoruz. Agent Engine, GCP'de aracı dağıtmak için tümüyle yönetilen bir hizmettir. Agent Engine, ADK (Agent Development Kit) ile uyumludur. Bu nedenle, ADK (Agent Development Kit) ile oluşturulan temsilciler Agent Engine'de dağıtılabilir.

Cloud Shell Düzenleyici terminalinde aşağıdaki adımlara geçmeden önce Ctrl+C ile ADK sunucusunu kapatın.
Poetry'yi kullanarak requirements.txt dosyasını oluşturun. Poetry, requirements.txt dosyasını oluşturmak için pyproject.toml dosyasını kullanır. Komutu çalıştırdıktan sonra requirements.txt dosyasının oluşturulup oluşturulmadığını kontrol edin (Cloud Shell Düzenleyici Terminali'nde çalıştırın).

# Go to the parent folder containing pyproject.toml file
cd ~/imagescoring/multiagenthandson

# install poetry-plugin-export
uv pip install poetry-plugin-export

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

Paketi oluşturun. Uygulamamızı .whl Python paketine paketlememiz gerekir. Bunu yapmak için şiir kullanacağız. Komutu yürüttükten sonra bir dist klasörünün oluşturulduğundan ve bu klasörün .whl dosyasını içerdiğinden emin olun (Cloud Shell Düzenleyici Terminali'nde çalıştırın).

# Go to the parent folder containing pyproject.toml file
cd ~/imagescoring/multiagenthandson

#Create python package, to create whl file
python3 -m poetry build

Şimdi, görüntü puanlama aracımızı Agent Engine hizmetine dağıtan komut dosyasını hazırlayacağız. deploy dizininde, Cloud Shell Düzenleyici yan bölmesinde deploy.py dosyasını bulun ve tıklayarak açın. İçeriğini aşağıdaki şekilde doğrulayın

import vertexai
from image_scoring.agent import root_agent
import os
import glob # To easily find the wheel file
from dotenv import load_dotenv

# Load environment variables from image_scoring/.env
env_path = os.path.join(os.path.dirname(__file__), "..", "image_scoring", ".env")
load_dotenv(env_path)

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1")
STAGING_BUCKET = f"gs://{os.getenv('GOOGLE_CLOUD_STORAGE_BUCKET')}"

from vertexai import agent_engines

client=vertexai.Client(
    project=PROJECT_ID,
    location=LOCATION,
)
remote_app = client.agent_engines.create(
    agent=root_agent,
    config={
        "display_name": "image-scoring",
        "staging_bucket": STAGING_BUCKET,
        "requirements": open(os.path.join(os.getcwd(), "requirements.txt")).readlines() + ["./dist/image_scoring-0.1.0-py3-none-any.whl"],
        "extra_packages": [
            "./dist/image_scoring-0.1.0-py3-none-any.whl",
        ],     "env_vars":{"GCS_BUCKET_NAME":os.getenv('GOOGLE_CLOUD_STORAGE_BUCKET')}
    }
)
print(f"DEBUG: AgentEngine attributes: {dir(remote_app)}")
try:
    print(remote_app.api_resource.name)
except AttributeError:
    print("Could not find resource_name, check DEBUG output above.")

Artık dağıtım komut dosyasını çalıştırabiliriz. Öncelikle multiagenthandson (Run in Cloud Shell Editor Terminal) adlı üst klasöre gidin.

#go to multiagenthandson folder
cd ~/imagescoring/multiagenthandson

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

Dağıtım işleminden sonra aşağıdakine benzer bir ekran görmeniz gerekir:

Şekil 7: Örnek çıkış

Şimdi dağıtılan ajanı test edelim. Uzakta dağıtılan aracı motorunu test etmek için önce terminaldeki dağıtım çıktısından aracı konumunu kopyalayın. Şu şekilde görünmelidir: projects/xxx/locations/us-central1/reasoningEngines/xxx .
multiagenthandson kök dizininden Cloud Shell Düzenleyici Terminali'nde aşağıdaki komutu çalıştırın.

#go to multiagenthandson folder
cd ~/imagescoring/multiagenthandson

#execute remote_test.py
python3 -m testclient.remote_test

Muhakeme motoru kimliğinizi girin (projects/xxx/locations/us-central1/reasoningEngines/xxx" gibi görünmelidir) ve resminizi oluşturmak için isteminizi girin. Resim çıktınızı Cloud Storage klasöründe onaylayabilirsiniz.

Şekil 8: Örnek çıktı

10. A2A temsilcisi oluşturma

Bu adımda, önceki adımlarda oluşturduğumuz ajana dayalı basit bir A2A ajanı oluşturacağız. Mevcut ADK (Agent Development Kit) ajanları, A2A protokolü altında yayınlanabilir. Bu adımda öğreneceğiniz temel konular şunlardır.

A2A protokolü hakkında temel bilgileri edinin.
ADK ve A2A protokollerinin birlikte nasıl çalıştığını öğrenin.
A2A protokolüyle nasıl etkileşim kuracağınızı öğrenin.

Bu uygulamalı laboratuvarda, image_scoring_adk_a2a_server klasöründeki kodu kullanacağız. İşleme başlamadan önce lütfen dizininizi bu klasör olarak değiştirin (Run in Cloud Shell Editor Terminal).

#change directory to image_scoring_adk_a2a_server
cd ~/imagescoring/multiagenthandson/image_scoring_adk_a2a_server

#copy the env file
cp ~/imagescoring/multiagenthandson/image_scoring/.env remote_a2a/image_scoring

1. A2A temsilci kartı oluşturma

A2A protokolü, aracıyla ilgili tüm bilgileri (ör. aracının yetenekleri, kullanım kılavuzu) içeren bir aracı kartı gerektirir. Bir A2A aracısı dağıtıldıktan sonra aracı kartı, ".well-known/agent-card.json" bağlantısı kullanılarak görüntülenebilir. Müşteriler, isteği temsilcilere göndermek için bu bilgileri kullanabilir.

remote_a2a/image_scoring dizinine gidin ve Cloud Shell Düzenleyici yan bölmesinde agents.json dosyasını bulun. Dosyayı açmak için tıklayın ve içeriğin aşağıdakilerle eşleştiğini doğrulayın:

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

2. A2A temsilcisi oluşturma image_scoring_adk_a2a_server kök dizininde a2a_agent.py dosyasının bulunduğunu doğrulayın. Cloud Shell Düzenleyici yan bölmesinde dosya adını tıklayarak açabilirsiniz. Bu dosya, A2A aracısının giriş noktası olarak işlev görür ve aşağıdaki içeriğe sahip olmalıdır:

#change directory to image_scoring_adk_a2a_server
cd ~/imagescoring/multiagenthandson/image_scoring_adk_a2a_server

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
)

3. A2A temsilcisini çalıştırma

Artık temsilciyi çalıştırmaya hazırız. Aracı çalıştırmak için üst klasör image_scoring_adk_a2a_server içinden aşağıdaki komutu yürütün (Cloud Shell Düzenleyici Terminali'nde çalıştırın).

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

4. A2A temsilcisini test etme

Ajan çalıştıktan sonra test edebiliriz. Öncelikle temsilci kartını kontrol edelim. Terminal > New Terminal'ı (Yeni Terminal) kullanarak yeni bir terminal açın ve aşağıdaki komutu çalıştırın (Run in the newly opened Cloud Shell Editor Terminal).

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

Yukarıdaki komutun yürütülmesi, A2A aracımızın aracı kartını göstermelidir. Bu kart, önceki adımda oluşturduğumuz agent.json dosyasının içeriğinden oluşur.

Şimdi ajana bir istek gönderelim. Aracıya istek göndermek için curl'ü kullanabiliriz (yeni açılan Cloud Shell Düzenleyici Terminali'nde çalıştırın).

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

Yukarıdaki istekte, "Bir kedi resmi oluştur" satırını değiştirerek istemi değiştirebilirsiniz. Komutu çalıştırdıktan sonra belirtilen Google Cloud Storage'da çıkış resmini kontrol edebilirsiniz.

11. Temizleme

Şimdi de oluşturduğumuz öğeleri temizleyelim.

Yeni oluşturduğumuz Agent Runtime sunucusunu silin. Google Cloud Console'un arama çubuğuna Gemini Enterprise Agent Platform yazarak Gemini Enterprise Agent Platform'a gidin. Sol taraftaki Agent Engine'i tıklayın.Sil'i tıklayarak temsilciyi silebilirsiniz.

Şekil 9: Aracı çalışma zamanı örneklerini Google Cloud Console'dan silebilirsiniz.

Cloud Shell'deki dosyaları silme

#Execute the following to delete the files
cd ~
rm -R ~/imagescoring

Paketi silin. GCP Console -> Cloud Storage'a gidip paketinizi seçip silebilirsiniz.

Şekil 10: Paketi silme

12. Sonuç

Tebrikler! ADK (Agent Development Kit) çoklu aracı uygulamasını Agent Runtime'a başarıyla dağıttınız. Bu önemli başarı, modern bir bulut tabanlı uygulamanın temel yaşam döngüsünü kapsar ve kendi karmaşık aracı sistemlerinizi dağıtmak için sağlam bir temel sunar.

Özet

Bu laboratuvarda şunları öğrendiniz:

ADK (Agent Development Kit) kullanarak çoklu aracı uygulaması oluşturma
Uygulamayı Agent Runtime'a dağıtın.
A2A protokolünü kullanarak iletişim kurabilen bir temsilci oluşturun.

Faydalı kaynaklar

Prototipten Üretime

Bu laboratuvar, Google Cloud ile Üretime Hazır Yapay Zeka Öğrenme Rotası'nın bir parçasıdır.

Prototip aşamasından üretim aşamasına geçiş yapmak için tüm müfredatı inceleyin.
#ProductionReadyAI hashtag'ini kullanarak ilerleme durumunuzu paylaşın.