1. Bu laboratuvarın amacı
Bu uygulamalı laboratuvarda, isteminize göre resim üreten ve bu resmi isteminize göre değerlendiren çoklu aracı uygulaması oluşturacaksınız. Resim, istemde açıklanan koşulları yeterince karşılamıyorsa temsilci, koşullarınızı karşılayan bir resim oluşturulana kadar sürekli olarak resim ü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.
Neler öğreneceksiniz?
- ADK'nın temellerini öğrenin ve çoklu aracı sistemi oluşturmayı öğrenin.
- GCP'de aracıları kolayca dağıtıp kullanmayı öğrenin.
- A2A protokolünün temellerini anlama
- Açık aracı oluşturmak için A2A protokolünü ve ADK'yı birlikte kullanmayı öğrenin.
2. Başlamadan önce
- Kullanabileceğiniz bir projeniz yoksa GCP Console'da yeni bir proje oluşturmanız gerekir.
- Bu laboratuvarda görevlerimizi gerçekleştirmek için GCP Cloud Shell'i kullanacağız. Cloud Shell'i açın ve Cloud Shell'i kullanarak projeyi ayarlayın.
- Cloud Shell Düzenleyici düğmesine basarak GCP Cloud Shell Düzenleyici'yi açın. "Authorize Shell" (Shell'e Yetki Ver) pop-up'ı gösterilirse Cloud Shell Editor'a yetki vermek için tıklayın.
- Projenin kimliğinin doğrulanıp doğrulanmadığını aşağıdaki komutla kontrol edebilirsiniz.
gcloud auth list
- Projenizi onaylamak için Cloud Shell'de aşağıdaki komutu çalıştırın:
gcloud config list project
- Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın.
gcloud config set project <YOUR_PROJECT_ID>
- Bu laboratuvarı çalıştırmak için bazı hizmetleri etkinleştirmemiz gerekiyor. Cloud Shell'de aşağıdaki komutu çalıştırın.
gcloud services enable aiplatform.googleapis.com
3. Genel bakış: Agent Development Kit'in avantajları
Agent Development Kit, yapay zeka destekli uygulamalar geliştiren geliştiriciler için çeşitli önemli avantajlar sunar:
- Çoklu Temsilci Sistemleri: Hiyerarşik olarak birden fazla uzmanlaşmış temsilciyi bir araya getirerek 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
veLoopAgent
) 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 KSA 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ımlarını tek tek 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: Temsilcilerinizi container'a dönüştürün ve istediğiniz yerde dağıtın. Yerel olarak çalıştırın, Vertex AI Agent Engine 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 ölçüde çalışma yapılması gerekir.
Agent Development Kit, bu araçlara kıyasla daha üst düzey bir çerçeve sunar. Bu sayede, karmaşık ancak bakımı kolay iş akışları için birden fazla aracı birbirine kolayca bağlayabilirsiniz.
4. A2A'ya giriş
Agent2Agent (A2A) protokolü, farklı çerçeveler, tedarikçiler ve alanlardaki bağımsız yapay zeka temsilcileri 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.
- Özellik Keşfi: Aracılar, kimliklerini, desteklenen A2A özelliklerini, becerilerini ve kimlik doğrulama gereksinimlerini açıklayan "Aracı Kartları" (JSON belgeleri) kullanarak özelliklerinin reklamını yapabilir. 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ı temsilciler 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 olarak, aracıların diğer aracılara kendi içindeki muhakeme süreçlerini, hafızasını veya kullandığı araçları açıklaması gerekmez. 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 entegrasyonu kolaylaştırır.
- Asenkron İletişim: Protokol, asenkron iletişimi öncelikli olarak dikkate alarak tasarlanmıştır. Bu sayede görevlerin esnek bir şekilde ilerlemesi sağlanır ve bağlantı sürekli olarak korunmasa bile güncellemeler için anlık bildirimler etkinleştirilebilir.
5. Aracı Mimarisi
Bu laboratuvarda, belirttiğiniz özellikler doğrultusunda bir resim oluşturan ve resmi size sunmadan önce değerlendiren çok aracı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 temsilcinin image_generation_scoring_agent adlı bir alt temsilcisi vardır. Bu alt temsilcinin de daha spesifik görevler için kendi alt temsilcileri vardır. Bu, ana temsilcinin görevleri alt temsilcilerine devrettiği hiyerarşik bir ilişki oluşturur. Şekil 2: Genel aracı akışı.
Tüm temsilcilerin listesi
- image_scoring (Ana Temsilci):
- Amaç: Bu, genel iş akışını yöneten temel 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.
- Alt temsilciler:
- image_generation_scoring_agent
- checker_agent_instance
- image_generation_scoring_agent (image_scoring alt aracısı):
- Amaç: Bu aracı, resim oluşturma ve puanlama işlemlerinin temel mantığından sorumludur. Bunu yapmak için üç alt aracıdan oluşan bir sıra yürütür.
- Alt temsilciler:
- image_generation_prompt_agent
- image_generation_agent
- scoring_images_prompt
- checker_agent_instance (image_scoring alt aracısı):
- Amaç: Bu aracı, resim puanlama sürecinin devam edip etmeyeceğini veya sonlandırılıp sonlandırılmayacağını kontrol eder. Sonlandırma koşulunu değerlendirmek için check_tool_condition aracını kullanır.
- image_generation_prompt_agent (image_generation_scoring_agent'ın alt aracısı):
- Amaç: Bu aracı, görüntü üretme için istem oluşturma konusunda uzmandır. Giriş metnini alır ve görüntü oluşturma modeline uygun ayrıntılı bir istem oluşturur.
- image_generation_agent (image_generation_scoring_agent'ın alt aracısı):
- Amaç: Bu temsilci, Imagen 3'ü kullanarak resim oluşturma konusunda uzmandır. image_generation_prompt_agent'tan gelen istemi alıp bir resim oluşturur.
- scoring_images_prompt (image_generation_scoring_agent alt aracısı):
- Amaç: Bu aracı, resimleri çeşitli ölçütlere göre değerlendirme ve puanlama konusunda uzmandır. Üretilen resmi alıp puan verir.
Temsilciler Tarafından Kullanılan Araçlar
- check_tool_condition:
- Açıklama: 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.
- Kullanan: checker_agent_instance
- generate_images:
- Açıklama: 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 kaydedebilir.
- Kullanan: image_generation_agent
- get_policy:
- Açıklama: Bu araç, bir JSON dosyasından politika getirir. Politika, image_generation_prompt_agent tarafından görüntü oluşturma istemini oluşturmak ve scoring_images_prompt tarafından görüntüleri puanlamak için kullanılır.
- Kullanan: image_generation_prompt_agent, scoring_images_prompt
- get_image:
- Açıklama: Bu araç, oluşturulan resim yapıtını puanlanabilmesi için yükler.
- Kullanan: scoring_images_prompt
- set_score:
- Açıklama: Bu araç, oturum durumunda oluşturulan resmin toplam puanını ayarlar.
- Kullanan: scoring_images_prompt
6. 1. görev: ADK'yı yükleme ve ortamınızı ayarlama
Bu uygulamalı laboratuvarda görevleri gerçekleştirmek için Cloud Shell'i kullanacağız.
Vertex AI'ın önerdiği API'leri etkinleştirme
- Google Cloud Console'da, konsolun üst kısmındaki arama çubuğunu kullanarak Vertex AI'a gidin.
- Enable all recommended APIs'i (Önerilen tüm API'leri etkinleştir) tıklayın.
Cloud Shell Düzenleyici sekmesi hazırlama
- Google Cloud Console pencereniz seçiliyken klavyenizde G tuşuna, ardından S tuşuna basarak Cloud Shell'i açın. Alternatif olarak, Google Cloud Console'un sağ üst köşesindeki Cloud Shell düğmesini
tıklayabilirsiniz.
- Devam'ı tıklayın.
- Cloud Shell'i yetkilendirmeniz istendiğinde Yetkilendir'i tıklayın.
- Cloud Shell bölmesinin sağ üst köşesinde Yeni pencerede aç düğmesini
tıklayın.
- Dosyaları görüntülemek için bölmenin üst kısmındaki Open Editor kalem simgesini (
) tıklayın.
- Dosya Gezgini'ni açmak için sol gezinme menüsünün üst kısmındaki Gezgin simgesini
tıklayın.
- Klasörü Aç düğmesini tıklayın.
- Bu laboratuvarın geri kalanında, Cloud Shell Düzenleyici ve Cloud Shell Terminal ile IDE'niz olarak bu pencerede çalışabilirsiniz.
Bu laboratuvar için ADK'yı ve kod örneklerini indirip yükleme
- Gerekli kaynağı GitHub'dan klonlamak ve gerekli kitaplıkları yüklemek için aşağıdaki komutları yürütü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 #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
- Ek gereksinimleri yüklemek için Poetry'yi kullanacağız:
cd multiagenthandson #go to the application directory pip install poetry poetry-plugin-export poetry install --with deployment
- Bulut depolama alanı paketiniz yoksa Google Cloud Storage'da yeni bir paket oluşturun. Paketi gsutil komutunu kullanarak da oluşturabilirsiniz.
gsutil mb gs://YOUR-UNIQUE-BUCKETNAME
- 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 bulut depolama paketi gibi gerekli ayrıntıları ekleyin.
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.
- Kaynak kodundaki aracı yapısına bakın. agent.py ile başlayın. Bu temsilci, diğer temsilcilere bağlanacak olan kök temsilciyi içerir.
- Terminalde en üstteki multiagenthandson dizinine geri dönün ve aracıyı yerel olarak çalıştırmak için aşağıdaki komutu yürütün.
# Run the following command to run agents locally export GCS_BUCKET_NAME=your gcs bucket name adk web
Şekil 1
ADK'nın tarayıcı tabanlı GUI istemcisini açmak için terminalde gösterilen http:// URL'sini Ctrl+Tıklayın (MacOS için CMD+Tıklayın). 2. Şekil'deki gibi görünmelidir.
- Gelin, birkaç resim oluşturalım. Aşağıdaki istemleri veya kendi istemlerinizi deneyin.
- Gün batımında huzurlu bir dağ manzarası
- Bisiklet süren bir kedi
Şekil 2
7. 2. görev: Agent Engine'e dağıtma
Şimdi temsilciyi 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 ile uyumludur. Bu nedenle, ADK ile oluşturulan aracıları Agent Engine'de dağıtabilirsiniz.
- Bazı ortam değişkenlerini tanımlama
export GOOGLE_CLOUD_LOCATION='us-central1' export GOOGLE_CLOUD_PROJECT='your project id'
- 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.
# 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
- 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.
# Go to the parent folder containing pyproject.toml file #Create python package, to create whl file poetry build
- Şimdi dağıtım komut dosyasını hazırlayacağız. Dağıtım komut dosyası, resim puanlama aracımızı veya aracı motoru hizmetimizi dağıtır. Lütfen image_scoring klasöründeki deploy.py dosyasının içeriğini aşağıdaki gibi değiştirin.
# 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)
- Artık dağıtım komut dosyasını çalıştırabiliriz.
#run deploy script from the parent folder containing deploy.py python3 -m image_scoring.deploy
Dağıtım işleminden sonra aşağıdakine benzer bir ekran görürsünüz:
Şekil 3
- Şimdi dağıtılan temsilciyi test edelim. Uzaktan dağıtılan aracı motorunu test etmek için önce terminaldeki dağıtım çıktısından aracı konumunu kopyalayın. Şuna benzer bir şey olmalıdır: projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680 .
testclient klasörüne gidin,remote_test.py dosyasını açın ve aşağıdaki satırları düzenleyin.
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. görev: A2A temsilcisi oluşturma
Bu adımda, önceki adımlarda oluşturduğumuz aracı temel alan basit bir A2A aracısı oluşturacağız. Mevcut ADK aracıları, A2A protokolü altında yayınlanabilir. Bu adımda öğreneceğiniz temel bilgiler şunlardır.
- A2A protokolüyle ilgili temel bilgileri öğrenin.
- 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. Göreve başlamadan önce lütfen dizininizi bu klasör olarak değiştirin.
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. 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 klasöründe aşağıdaki içeriğe sahip agents.json dosyasının bulunduğunu 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"
]
}
]
}
A2A temsilcisi oluşturma
Kök klasör image_scoring_adk_a2a_server içinde, a2a aracısının giriş noktası olan a2a_agent.py dosyasının bulunduğunu doğrulayın. Aşağıdaki içerikler bulunmalıdır:
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 aracısını çalıştırma
Artık temsilciyi çalıştırmaya hazırız. Aracıyı çalıştırmak için üst klasör image_scoring_adk_a2a_server içinden aşağıdaki komutu yürütün.
#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 aracısını test etme
Temsilci çalıştıktan sonra artık gidip test edebiliriz. Öncelikle temsilci kartını kontrol edelim.
#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 temsilciye bir istek gönderelim. Aracıya istek göndermek için curl'ü kullanabiliriz.
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.
9. Temizleme
Şimdi de oluşturduğumuz öğeleri temizleyelim.
- Yeni oluşturduğumuz Agent Engine sunucusunu silin. Google Cloud Console'un arama çubuğuna Vertex AI yazarak Vertex AI'a gidin. Sol taraftaki Agent Engine'i tıklayın.Sil'i tıklayarak temsilciyi silebilirsiniz.
Şekil 4
- Cloud Shell'deki dosyaları silme
#Execute the following to delete the files rm -R imagescoring
- Paketi silin. GCP Console -> Cloud Storage'a gidip paketinizi seçip silebilirsiniz.