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. Resim, istemde açıklanan koşulları yeterince karşılamıyorsa temsilci, koşullarınızı karşılayan resim üretilene kadar sürekli olarak resim üretir. Bu uygulamalı etkinlikteki her aracının tek bir amacı vardır. Ajanlar, 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 birden fazla temsilci içeren bir sistemin nasıl oluşturulacağını keşfedin.
Agent Runtime'da aracıları kolayca dağıtma ve kullanma hakkında bilgi edinin.
A2A protokolünün temel bilgilerini öğrenme
Açık temsilciler oluşturmak için A2A protokolünü ve ADK'yı (Agent Development Kit) birlikte nasıl kullanacağınızı öğrenin.

Ön koşullar

Python ve komut satırı arayüzleri hakkında bilgi sahibi olmanız gerekir.
Faturalandırmanın etkin olduğu bir Google Cloud projesine erişim.
Yüklü CLI araçları: gcloud, uv.

2. Proje Ayarları

Aşağıdaki bağlantıyı tıklayarak GCP konsoluna gidin: GCP konsolu.
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 tüm proje kimliklerinizi şu komutla 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'si (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 istenir.

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: Hiyerarşide birden fazla uzmanlaşmış ajan oluşturarak modüler ve ölçeklenebilir uygulamalar geliştirin. Karmaşık koordinasyon ve temsil işlemlerini etkinleştirin.
Zengin Araç Ekosistemi: Acentelere ç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 acente çerçevelerindeki (LangChain, CrewAI) araçları entegre edin veya hatta diğer acenteleri 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 bir geliştirme kullanıcı arayüzü ile yerel olarak geliştirme, test etme ve hata ayıklama. 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 alı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)'nin konumlandırılması

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 aracıları( 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.

Ajanları 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 iyi bir seçimdir. Çünkü oturum yönetimi ve yapay zeka aracı için kalıcılık gibi yaygın görevleri soyutlar.
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, oturumlar arasında kullanılabilen, kullanıcılarınızla ilgili bilgileri hatırlamanın esnek bir yolunu 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 Ajan 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ği sağlamak için tasarlanmış açık bir standarttır.

Evrensel Birlikte Çalışabilirlik: A2A, temel teknolojilerinden bağımsız olarak ajanların birlikte çalışmasına olanak tanıyarak gerçek anlamda çoklu ajan ekosistemi oluşturur. Bu sayede, farklı platformlarda farklı şirketler tarafından oluşturulan temsilciler iletişim kurabilir ve koordineli çalışabilir.
Yetenek Keşfi: Aracılar, kimliklerini, desteklenen A2A özelliklerini, becerilerini ve kimlik doğrulama şartlarını açıklayan "Aracı Kartları" (JSON belgeleri) kullanarak yeteneklerini tanıtabilir. Bu sayede diğer temsilciler, belirli bir görev için en uygun temsilciyi bulup seçebilir.
Tasarımdan başlayan güvenlik: 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, aracıların görev ve kullanıcı için en uygun biçimde bilgi alışverişi yapmasına olanak tanır.
Yapılandırılmış Görev Yönetimi: A2A, görevleri devretme, 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 kendi içindeki muhakeme süreçlerini, hafızalarını veya belirli araçlarını diğer aracılara açıklamalarının gerekmemesidir. Yalnızca çağrılabilir hizmetlerini kullanıma sunarak modülerliği ve gizliliği teşvik ederler.
Mevcut Standartlar Üzerine Kurulmuştur: A2A, HTTP, Server-Sent Events (SSE) (anlık 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 sağlanır ve bağlantı sürekli olarak korunmasa bile güncellemeler için anlık bildirimler etkinleştirilir.

7. Ajan Mimarisi

Bu laboratuvarda, spesifikasyonunuza göre görüntü oluşturan ve size sunmadan önce görüntüyü değerlendiren çok agentlı 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 temsilci akışı.

Tüm Ajanların Listesi

Ajan	Purpose	Alt acenteler
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 ajanı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, görüntü 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.	-
checker_agent_instance (image_scoring alt aracısı)	Bu aracı, görüntü üretme istemleri 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 alt aracısı)	Bu aracı, görüntü üretme istemleri 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 (Sub-agent of image_generation_scoring_agent):	Bu temsilci, resimleri çeşitli ölçütlere göre değerlendirme ve puanlama konusunda uzmandır. Üretilen görüntüyü alıp puan verir.	-

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 resimleri bir Google Cloud Storage paketine kaydedebilir.	image_generation_agent
get_policy	Bu araç, bir JSON dosyasından politika getirir. Politika, image_generation_prompt_agent tarafından görüntü üretme 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 resim 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)

Aşağıdaki bağlantıyı tıklayarak GCP konsoluna gidin: GCP konsolu.
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 tüm proje kimliklerinizi şu komutla 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. Cloud Shell Düzenleyici'de açılan Terminal'de komutları ç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. Ayrıca, gcloud komutunu kullanarak da bucket 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çeriğe sahip bir .env dosyası oluşturun. Proje adınız ve bulut depolama paketi gibi gerekli ayrıntıları ekleyin (Run in Cloud Shell Editor Terminal).

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

cat <<EOF>> .env
GOOGLE_GENAI_USE_ENTERPRISE=true
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ını inceleyin. Bu ajan, diğer alt ajanlara bağlanacak kök ajanı 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 multiagenthandson üst dizinine geri dönün ve aracıyı 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ıklayın (MacOS için CMD+tıklayın). Şekil 5'teki gibi görünmelidir.
Sol üstteki açılır menüden image_scoring'i seçin (Şekil 5'e bakın). Şimdi de birkaç resim oluşturalım. Görüntüleri Google Cloud Storage paketinde de bulabilirsiniz. Kaydedilen resimlerinizi yerel olarak görmek için "Artifacts" (Yapımlar) 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 ajanı Agent Engine'e dağıtıyoruz. Agent Engine, GCP'de aracı dağıtmak için kullanılan, tamamen yönetilen bir hizmettir. Agent Engine, ADK (Agent Development Kit) ile uyumludur. Bu nedenle, ADK (Agent Development Kit) ile oluşturulan ajanlar 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 gerekiyor. 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 açmak için tıklayı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 yaptıktan sonra aşağıdaki gibi bir şey 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

Akıl yürütme motoru kimliğinizi girin. Kimliğiniz "projects/xxx/locations/us-central1/reasoningEngines/xxx"" gibi görünmelidir. Ardından, resminizi oluşturmak için isteminizi girin. Resim çıktınızı Cloud Storage klasöründe onaylayabilirsiniz.

Şekil 8: Örnek çıkış

10. A2A aracısı oluşturma

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

A2A protokolü ile 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örevi başlatmadan önce lütfen dizininizi bu klasörle değiştirin (Cloud Shell Düzenleyici Terminali'nde çalıştırın).

#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 aracısı 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 ".well-known/agent-card.json" bağlantısı kullanılarak aracı kartı görüntülenebilir. Müşteriler, isteği aracılara 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 aracısı 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 aracısını çalıştırma

Artık aracı çalıştırmaya hazırız. Aracı çalıştırmak için üst klasör image_scoring_adk_a2a_server'ın 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 aracısını test etme

Ajan çalıştıktan sonra test edebiliriz. Öncelikle aracı kartını kontrol edelim. Terminal>New Terminal'i (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, temel olarak önceki adımda oluşturduğumuz agent.json dosyasının içeriğidir.

Ş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 ajan 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.
İlerleme durumunuzu #ProductionReadyAI hashtag'iyle paylaşın.