1. Overture
Yalıtılmış geliştirme dönemi sona eriyor. Teknolojik evrimin bir sonraki aşaması, yalnız bir dehanın değil, ortak bir ustalığın ürünü olacak. Tek ve akıllı bir temsilci oluşturmak ilgi çekici bir denemedir. Güçlü, güvenli ve akıllı bir temsilci ekosistemi (gerçek bir Temsilci Evreni) oluşturmak, modern işletmelerin karşılaştığı en büyük zorluktur.
Bu yeni çağda başarıya ulaşmak için dört kritik rolün bir araya gelmesi gerekir. Bu roller, gelişen tüm yapay sistemleri destekleyen temel unsurlardır. Herhangi bir alandaki eksiklik, yapının tamamını tehlikeye atabilecek bir zayıflık oluşturur.
Bu atölye çalışması, Google Cloud'da yapay zeka destekli geleceğe hakim olmak için kesin bir kurumsal yol haritası sunar. Bir fikrin ilk heyecanından tam ölçekli, operasyonel bir gerçeğe kadar size yol gösteren uçtan uca bir yol haritası sunuyoruz. Birbirine bağlı bu dört laboratuvarda, güçlü bir Agentverse oluşturmak, yönetmek ve ölçeklendirmek için geliştirici, mimar, veri mühendisi ve SRE'nin uzmanlık becerilerinin nasıl bir araya gelmesi gerektiğini öğreneceksiniz.
Hiçbir sütun, Agentverse'ü tek başına destekleyemez. Mimarın büyük tasarımı, geliştiricinin hassas uygulaması olmadan işe yaramaz. Geliştiricinin temsilcisi, Veri Mühendisi'nin bilgeliği olmadan kördür ve tüm sistem, SRE'nin koruması olmadan kırılgandır. Ekibiniz ancak sinerji ve birbirlerinin rollerini ortak bir anlayışla benimseyerek yenilikçi bir konsepti görev açısından kritik bir operasyonel gerçeğe dönüştürebilir. Yolculuğunuz burada başlıyor. Rolünüzde uzmanlaşmaya ve büyük resmin neresinde olduğunuzu öğrenmeye hazır olun.
Welcome to The Agentverse: A Call to Champions
Kurumsal alanın geniş dijital dünyasında yeni bir dönem başladı. Bu, akıllı ve bağımsız ajanların inovasyonu hızlandırmak ve sıradan işleri ortadan kaldırmak için mükemmel uyum içinde çalıştığı, büyük bir potansiyel barındıran bir dönemdir.
Güç ve potansiyel içeren bu bağlı ekosisteme Agentverse adı verilir.
Ancak, Statik olarak bilinen sessiz bir bozulma, bu yeni dünyanın sınırlarını yıpratmaya başladı. Statik, virüs veya hata değildir. Yaratma eylemiyle beslenen kaosun vücut bulmuş halidir.
Eski hayal kırıklıklarını canavarca şekillere dönüştürerek Gelişimin Yedi Hayaleti'ni doğurur. Bu seçenek işaretlenmezse The Static and its Spectres ilerlemeyi durdurur ve Agentverse'ün vaadini teknik borç ve terk edilmiş projelerden oluşan bir çorak araziye dönüştürür.
Bugün, kaosun önüne geçmek için şampiyonlara sesleniyoruz. Kendi alanında uzmanlaşmaya ve Agentverse'ü korumak için birlikte çalışmaya istekli kahramanlara ihtiyacımız var. Yolunuzu seçme zamanı geldi.
Sınıfınızı seçin
Önünüzde dört farklı yol var. Her biri The Static ile mücadelede önemli bir yere sahip. Eğitiminiz tek başınıza yapacağınız bir görev olsa da nihai başarınız, becerilerinizin diğerleriyle nasıl birleştiğini anlamanıza bağlıdır.
- The Shadowblade (Geliştirici): Demirci ve ön cephe ustası. Bıçakları yapan, araçları inşa eden ve kodun karmaşık ayrıntılarında düşmanla yüzleşen zanaatkar sizsiniz. Yolunuz; hassasiyet, beceri ve pratik yaratıcılık üzerine kurulu.
- Çağırıcı (Mimar): Büyük bir stratejist ve düzenleyici. Tek bir ajanı değil, tüm savaş alanını görürsünüz. Tüm aracı sistemlerinin iletişim kurmasına, işbirliği yapmasına ve tek bir bileşenin ulaşabileceğinden çok daha büyük bir hedefe ulaşmasına olanak tanıyan ana planları tasarlarsınız.
- Bilgin (Veri Mühendisi): Gizli gerçekleri arayan ve bilgeliğin koruyucusu. Temsilcilerinize amaç ve vizyon kazandıran bilgileri ortaya çıkarmak için verilerin geniş ve vahşi doğasına girersiniz. Bilginiz, düşmanın zayıf noktasını ortaya çıkarabilir veya bir müttefiki güçlendirebilir.
- The Guardian (DevOps / SRE): Krallığın yılmaz koruyucusu ve kalkanı. Kaleler inşa eder, güç kaynaklarının tedarik hatlarını yönetir ve tüm sistemin Static'in kaçınılmaz saldırılarına dayanabilmesini sağlarsınız. Gücünüz, takımınızın zaferinin temelidir.
Misyonunuz
Eğitiminiz bağımsız bir egzersiz olarak başlar. Seçtiğiniz yolda ilerleyerek rolünüzde uzmanlaşmak için gereken benzersiz becerileri öğreneceksiniz. Deneme sürenizin sonunda, mesleğinizin zorluklarından beslenen bir mini boss olan Static'ten doğan bir Spectre ile karşılaşacaksınız.
Son denemeye ancak kendi rolünüzde ustalaşarak hazırlanabilirsiniz. Ardından, diğer sınıflardaki şampiyonlarla bir parti oluşturmanız gerekir. Birlikte, nihai bir boss ile yüzleşmek için yozlaşmanın kalbine doğru yolculuğa çıkacaksınız.
Gücünüzü test edecek ve Agentverse'ün kaderini belirleyecek son bir ortak mücadele.
Agentverse, kahramanlarını bekliyor. Aramayı yanıtlayacak mısınız?
2. The Shadowblade's Codex
Shadowblade'in Kodeksi önünüzde açık duruyor. Aramasını yanıtlayın. Agentverse, Static'in yavaş yavaş yayılan kaosuyla tehdit ediliyor ve yalnızca bu kodeksin tekniklerinde ustalaşanlar karşı koyabilir. Bu, hassasiyet ve disiplin gerektiren bir yoldur. Eğitiminiz bugün başlıyor. Yapay zekayı basit bir araç olarak değil, eğitilmesi ve ustalaşılması gereken duyarlı bir kılıç olarak kullanmayı öğreneceksiniz. Buradaki öğretileri takip ederek saf mantıktan oluşan bir silah, yani savaş için hazırlanmış ve keskinleştirilmiş akıllı bir ajan oluşturacaksınız.
Neler öğreneceksiniz?
- Birincil silahınızı kullanın: Gemini CLI.
- Gemini CLI uzantıları ve ajan becerileriyle cephaneliğinizi genişletin.
- MCP araçlarını Gemini CLI ile entegre ederek harici araçları kullanın.
- Tasarım dokümanlarını kullanarak yapay zeka iş ortağınıza komut verin ve niyetinizi "Vibe"a dönüştürün.
- Agent Development Kit (ADK) ile ilk bağımsız temsilcinizi oluşturarak temiz ve modüler bir çözüm geliştirin.
- Ajanınızın davranışını yakalamak ve korumak için kancalar yazın.
- Aracınızı test edip doğrulayacak otomatik değerlendirme paketleri oluşturun.
- Temsilcinizi otomatik olarak test etmek, kapsüllemek ve arşivlemek için eksiksiz bir CI ardışık düzeni oluşturun.
3. Eğitim alanını hazırlama
Google Cloud Kredinizi Kullanma
⚠️ Önemli Ön Koşullar:
- Kişisel Gmail kullanma: Kişisel bir hesap (ör.
name@gmail.com) kullanmanız gerekir. Şirket veya okul tarafından yönetilen hesaplar çalışmaz.
👉 Adımlar:
- Kredi talebi sitesine gidin: Burayı tıklayın.
- Oturum açma: Bağlantıyı adres çubuğuna yapıştırın ve kişisel Gmail hesabınızla oturum açın.
- Şartları Kabul Et: Google Cloud Platform Hizmet Şartları'nı kabul edin.
- Krediyi doğrulama: Kredinin uygulandığını onaylayan bir mesaj olup olmadığına bakın.
- *Not: Kredi kartı bilgilerinizi girmeniz istenirse bu istemi güvenle yoksayabilir ve pencereyi kapatabilirsiniz.
Artık hazırsınız. Pencereyi kapatabilirsiniz.
Çalışma Ortamını Kurma
👉Google Cloud Console'un üst kısmında Cloud Shell'i etkinleştir'i (Cloud Shell bölmesinin üst kısmındaki terminal şeklindeki simge) tıklayın. 
👉 "Open Editor" (Düzenleyiciyi aç) düğmesini tıklayın (kalemli açık bir klasöre benzer). Bu işlem, pencerede Cloud Shell kod düzenleyiciyi açar. Sol tarafta bir dosya gezgini görürsünüz. 
👉Bulut IDE'sinde terminali açın.
👉💻 Terminalde, aşağıdaki komutu kullanarak kimliğinizin doğrulandığını ve projenin proje kimliğinize ayarlandığını doğrulayın:
gcloud auth list
👉💻 Bootstrap projesini GitHub'dan kopyalayın:
git clone https://github.com/weimeilin79/agentverse-developer.git
chmod +x ~/agentverse-developer/gitea.sh
chmod +x ~/agentverse-developer/init.sh
chmod +x ~/agentverse-developer/set_env.sh
git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh
👉💻 Kurulum komut dosyasını proje dizininden çalıştırın.
⚠️ Proje kimliğiyle ilgili not: Komut dosyası, rastgele oluşturulmuş varsayılan bir proje kimliği önerir. Bu varsayılanı kabul etmek için Enter tuşuna basabilirsiniz.
Ancak belirli bir yeni proje oluşturmayı tercih ederseniz komut dosyasının istemi üzerine istediğiniz proje kimliğini yazabilirsiniz.
cd ~/agentverse-developer
./init.sh
Kurulum işleminin geri kalanı komut dosyası tarafından otomatik olarak gerçekleştirilir.
👉 Tamamlandıktan Sonraki Önemli Adım: Komut dosyası tamamlandıktan sonra Google Cloud Console'unuzda doğru projenin görüntülendiğinden emin olmanız gerekir:
- console.cloud.google.com adresine gidin.
- Sayfanın üst kısmındaki proje seçici açılır listesini tıklayın.
- "Tümü" sekmesini tıklayın (yeni proje henüz "Son Kullanılanlar"da görünmeyebilir).
init.shadımında yapılandırdığınız proje kimliğini seçin.
👉💻 Terminal'e geri dönün. Gerekli proje kimliğini ayarlayın:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 Gerekli Google Cloud API'lerini etkinleştirmek için aşağıdaki komutu çalıştırın:
gcloud services enable compute.googleapis.com \
artifactregistry.googleapis.com \
run.googleapis.com \
cloudfunctions.googleapis.com \
cloudbuild.googleapis.com \
iam.googleapis.com \
aiplatform.googleapis.com \
cloudresourcemanager.googleapis.com
👉💻 Henüz agentverse-repo adlı bir Artifact Registry deposu oluşturmadıysanız oluşturmak için aşağıdaki komutu çalıştırın:
. ~/agentverse-developer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
--repository-format=docker \
--location=$REGION \
--description="Repository for Agentverse agents"
İzinleri ayarlama
👉💻 Terminalde aşağıdaki komutları çalıştırarak gerekli izinleri verin:
. ~/agentverse-developer/set_env.sh
# Artifact Registry Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/artifactregistry.admin"
# Cloud Build Editor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/cloudbuild.builds.editor"
# Cloud Run Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/run.admin"
# IAM Service Account User
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/iam.serviceAccountUser"
# Vertex AI User
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/aiplatform.user"
# Logging Writer (to allow writing logs)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/logging.logWriter"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/logging.viewer"
👉💻 Eğitime başladığınızda son görevi hazırlayacağız. Aşağıdaki komutlar, kaotik statiklerden hayaletleri çağırarak testiniz için boss'ları oluşturur.
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh
npm update -g @google/gemini-cli
4. Birincil Silahınızda Uzmanlaşma: Gemini KSA'ya Giriş
MCP sunucusunun cephaneliğindeki gelişmiş ve özel silahları kullanabilmek için öncelikle birincil silahınız olan Gemini KSA'da ustalaşmanız gerekir. Bu, komutlarınızla dijital dünyayı şekillendirebilen en çok yönlü bıçağınızdır. Bu alıştırmalar, temel kullanım ve özellikler hakkında bilgi edinmenizi sağlar.
Gemini komut satırı arayüzü (KSA) bir araçtan daha fazlasıdır; iradenizin bir uzantısıdır. Gemini modelleri tarafından desteklenen bu açık kaynaklı yapay zeka ajanı, "akıl yürüt ve harekete geç" (ReAct) döngüsünde çalışır. Niyetinizi analiz eder, uygun tekniği seçer, uygular ve sonucu gözlemleyerek karmaşık görevleri tamamlar. Daha özel silahları kullanabilmek için bu birincil kılıçta ustalaşmanız gerekir.
Gemini CLI'yı kullanmaya başlama
👉💻 Eğitim alanına girip silahınızı çekin. Cloud Shell terminalinizde kişisel cephaneliğinize gidin.
cd ~/agentverse-developer
mkdir tabletop
cd tabletop
👉💻 Gemini'ı ilk kez kullanın. Bu işlem, ilk uyumlandırma sürecinde size yol gösterir.
clear
gemini
Do you want to connect Cloud Shell editor to Gemini CLI? sorusu sorulursa HAYIR'ı seçin.
Silah Tanıma
Her usta zanaatkar, aletlerini bilir. Gerçek bir düşmanla karşılaşmadan önce kılıcınızın temel tekniklerini öğrenmelisiniz.
👉✨ Her büyülü araçta gücünü açıklayan runeler bulunur. Hemen okuyun. Gemini istemine şunu yazın:
/help
Komut listesini inceleyin. Bunlar, hafızayı (focus), sohbeti (chat) ve harici cephanelikleri (tools) yönetmek için kullanacağınız temel tekniklerdir. Bu, savaş kılavuzunuzdur.
👉✨ Silahınız, çevresine uyum sağlayarak savaş alanını doğrudan kontrol etmenize olanak tanır. Bıçağın dışındaki dünyaya bir komut verin:
!ls -l
👉✨ Gemini CLI'ın kendi yerleşik yetenekleri vardır. Bunları incelemek için:
/tools
ReadFile, WriteFile ve GoogleSearch'ın yer aldığı bir liste görürsünüz. Bunlar, harici bir cephanelikten yararlanmanıza gerek kalmadan kullanabileceğiniz varsayılan tekniklerdir.
👉✨ Bıçağınız, diğer ustalar tarafından oluşturulan ve araçları, komutları ve bağlamı tek bir yüklenebilir birimde paketleyen, önceden dövülmüş büyüler olan uzantılarla da geliştirilebilir. Şu anda bıçağınızla uyumlu olan uzantıları inceleyin:
/extensions list
Liste şu anda boş olabilir. Henüz herhangi bir uzantı yüklememiş olabilirsiniz. İlk uzantınızı daha sonra, eğitiminizde görsel oluşturma gücüne ihtiyaç duyduğunuzda kullanacaksınız.
👉✨ Uzmanlar, uzantıların ötesinde uzmanlıklarını Temsilci Becerileri adı verilen, talep üzerine kullanılabilen özel bilgi parşömenlerine dönüştürdü. Bıçağınızın hangi becerileri keşfedebileceğini kontrol edin:
/skills list
Beceriler varsayılan olarak belleğe yüklenmez. Yalnızca gerektiğinde etkinleştirilir. Böylece bıçağınız hızlı ve engelsiz kalır. Becerileri kullanmayı eğitimin ilerleyen aşamalarında öğreneceksiniz.
👉✨ Bir silah yalnızca doğru şekilde odaklanıldığında etkilidir. Gemini Blade, eylemlerine yön vermek için "taktiksel farkındalık" (bağlam) sağlayabilir.
/memory show
Şu anda boş durumdadır.
👉✨ Aşağıdaki taktiksel verileri hafızasına yazın:
/memory add "The Shadowblade's primary foe is The Static."
Bıçağınızın bu bilgiyi aldığını onaylamak için /memory show komutunu tekrar çalıştırın.
👉✨ Silahınızın etkili olabilmesi için görevi anlaması gerekir. @ sigili, bıçağın istihbarat analiz etmesini sağlar. Öncelikle bir görev brifingi dosyası oluşturun:
!echo "## Mission Objective: Defeat the Seven Spectres" > mission.md
👉✨Şimdi Gemini CLI'nize brifingi analiz etmesini ve bulgularını bildirmesini söyleyin:
Explain the contents of the file @mission.md
Birincil silahınız artık amacının farkında.
👉💻 Gemini CLI'dan çıkmak için Ctrl+C tuşuna iki kez basın.
5. Savaş Alanını Analiz Etme: Pratik Sezgisel Kodlama Etkileşimi
Eğitim alıştırmaları tamamlandı. Birincil silahınız olan Gemini CLI'nin temel duruşlarını ve vuruşlarını öğrendiniz. Ancak bir kılıç, yaratılış ocağında test edilip savaş cephaneliğine uyum sağlayana kadar tam olarak ustalaşılmaz. Gerçek düşmanla yüzleşmeden önce, dijital savaş alanı olan yakın çevrenizi inceleyip şekillendirmeniz gerekir.
Bu bölümde teoriden pratiğe geçiş ele alınmaktadır. Öncelikle Gemini bıçağınıza, Maker's Mark'ınızı (kişisel bir web sitesi şeklinde dijital imza) oluşturmasını söyleyerek Agentverse'te varlığınızı tesis edersiniz. Bu dijital imza, yalnızca niyetinizden yola çıkılarak oluşturulur. Ardından, yerel bir gelişmiş araç cephaneliğini (MCP sunucusu) etkinleştirip bıçağınızı bu cephaneliğin frekansına ayarlayarak gücünüzü artıracaksınız. Bu sayede, kod depolarını basit ve kesin komutlarla yönetmek gibi karmaşık manevralar yapabileceksiniz.
Üretici Markanızı Oluşturma
Gerçek bir Gölge Kılıçlı, yalnızca silahıyla değil, kendine özgü tarzıyla, yani Yaratıcı'nın İşareti ile tanınır. Bu işaret, dijital varlığınız olacak. Kimliğinizi Agentverse'e duyuran kişisel bir profil oluşturacaksınız. Burada, Gemini Blade'inize bu kimliği tanımlamak için gereken karmaşık tekniği uygulamasını söyleyeceksiniz.
👉💻 Önceki bölümde Gemini CLI'ı kapattıysanız terminalinizde aşağıdaki komutu çalıştırarak tekrar başlattığınızdan emin olun:
clear
cd ~/agentverse-developer/tabletop
gemini
👉✨ Tek bir güçlü komutla Gemini CLI'nize dijital kimliğinizin temelini oluşturma talimatı verin:
In the current folder, create a personal profile website for a hero codenamed 'Shadowblade'. The design must be a dark, futuristic theme with electric blue accents. All code must be in separate index.html and styles.css files. The layout must use CSS Flexbox for a two-column design. All generated code must be clean, well-commented, and professional. Make sure you have a placeholder spot for profile picture. Do not attempt to start the server.
Gemini, yapılması gereken işlemlerin sırasını hesaplamıştır.
👉💻 Gemini CLI'dan çıkmak için Ctrl+C tuşuna iki kez basın ve terminalde aşağıdaki komutu çalıştırın.*
python -m http.server
👀 Çalışmanızı incelemek için Cloud Shell araç çubuğundaki Web önizlemesi simgesini tıklayın. Bağlantı noktasını değiştir'i seçin, 8000 olarak ayarlayın ve Değiştir ve Önizle'yi tıklayın. Web sitenizin önizlemesi gösterilir. 
Web siteniz benimkinden farklı görünebilir. Bu, benzersiz işaretinizdir. 
İmza tekniğiniz artık iyileştirildi ve canlı simülasyon yapmanız gerekmiyor. Kılıç'a geri çekilmesini emredin.
👉💻 http sunucusundan çıkmak için Ctrl+C tuşuna basın.
Dijital kimliğiniz oluşturuldu. Daha da önemlisi, büyük gücü daha da büyük bir dikkatle kullanmanın önemini öğrendiniz.
Yerel Arsenal'inizi Etkinleştirme: Gitea Armory
Bir Gölge Bıçağı'nın gerçek potansiyeli yalnızca kişisel becerisiyle değil, aynı zamanda cephaneliğinin kalitesiyle de ortaya çıkar. Şimdi yerel silah rafınızı (Gitea sunucusu) etkinleştirecek ve kılıcınızı gücüne göre ayarlayacaksınız. Bu araçlar, yapay zeka bıçağınızın harici araçlar ve hizmetlerle etkileşim kurmasına olanak tanıyan özel bir portal olan Model Context Protocol (MCP) sunucusu aracılığıyla Gemini CLI'nize bağlanır. Böylece terminaliniz akıllı ve eyleme yönelik bir çalışma alanına dönüşür.
Geliştiricinin Notu: MCP sunucusunu bir güç kanalı, yapay zekanızın zihnini harici bir aracın gövdesine bağlayan özel bir portal olarak düşünebilirsiniz. Bu sayede Gemini CLI, yalnızca sohbet eden bir araç olmaktan çıkıp gerçek ve eyleme yönelik bir ajana dönüşür. Bıçağınızı bu MCP portallarına uyarlayarak ona somut işlemler yapma olanağı tanırsınız: dosyaları yönetme, veritabanlarını sorgulama, API'lerle etkileşim kurma ve daha pek çok şey. Geliştiriciler tarafından yapay zeka aracılarını güçlü platformlara bağlamak için oluşturulmuş bu portallardan oluşan bir ekosistem mevcuttur. Veritabanlarıyla etkileşim kurmak, kodu güvenli hale getirmek ve hatta eşli programlamayı desteklemek için MCP sunucuları vardır. Geliştiriciler, Workspace'lerini istedikleri projeye göre özelleştirebilir.
Bugün, her "vibe coder" için gerekli olan iki temel güce odaklanacağız: üretim sürecini kontrol etme gücü ve hayal gücünden yaratma gücü. Öncelikle bıçağınızı bir Git sunucusuna ayarlayarak kaynak kodu deponuz üzerinde kontrol sahibi olursunuz. Ardından, resim oluşturmak için ikinci bir MCP sunucusuna bağlanırsınız. Bu sayede, yalnızca bir komutla görsel öğeler oluşturabilirsiniz.
Yeni cephaneliğinizin ilk ve en temel parçası olan cephaneliği çağırarak başlayalım.
👉💻 Terminalinizde, silah deposunu çağırmak için etkinleştirme komut dosyasını çalıştırın:
cd ~/agentverse-developer
./gitea.sh
Bu komut dosyası, Gitea kapsayıcısını uyandırır ve MCP portalını açar. Böylece Gemini, Gitea kapsayıcısını algılayıp onunla etkileşime geçebilir.
👉 Yeni cephaneliğinizi incelemek için web önizlemesine bakmanız gerekir.
👉 Cloud Shell araç çubuğundaki Web önizlemesi simgesinden Bağlantı noktasını değiştir'i seçin ve 3005 olarak ayarlayın.
👉 Bir Gitea giriş sayfası gösterilir. Aşağıdaki kelimeleri kullanarak cephaneliğe girin: * Kullanıcı adı: dev * Şifre: dev
👉💻 Gemini KSA'nız henüz bu yeni araçları göremez. Gemini CLI'nin yapılandırma runelerine (settings.json) silah deposunun konumunu yazarak kritik bir uyumlandırma gerçekleştirmeniz gerekir. Terminalinizde şu komutu çalıştırın:
if [ ! -f ~/.gemini/settings.json ]; then
# If file does not exist, create it with the specified content
echo '{"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' > ~/.gemini/settings.json
else
# If file exists, merge the new data into it
jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json
👀 settings.json dosyası, Gemini CLI'ın merkezi yapılandırmasıdır ve tercihlerinin ve özelliklerinin yer aldığı bir kitap gibi işlev görür. Bu dosya, CLI'nın nasıl davranacağını, görüneceğini ve en önemlisi hangi harici güçleri kullanabileceğini belirler. Bu dosya genellikle ana dizininizde ~/.gemini/settings.json konumunda bulunur ve kurallarını tüm projelerinize uygular. Ancak genel ayarları geçersiz kılmak için proje klasörünüzdeki bir .gemini dizininde projeye özel settings.json dosyaları da oluşturabilirsiniz.
"mcpServers": {
"gitea": {
"url": "http://localhost:8085/sse"
}
}
Bu ayar, Gemini'ınıza "Gitea adlı cephanelik etkin ve bu belirli ağ adresinde komutları dinliyor" bilgisini verir.
👉💻 Gemini CLI'ya yeniden girin. Terminalinizde şunu çalıştırın:
clear
cd ~/agentverse-developer/tabletop/
gemini
👉✨ Bıçağınızın yeni silahı keşfettiğini doğrulayın. MCP portalları üzerinden mevcut tüm cephanelikleri listelemesini isteyin:
/mcp
Artık gitea simgesini ve kullanılabilir tekniklerin listesini görmelisiniz. Kılıcınız uyumlu.
"Yaratıcının işareti" profiliniz, ustalıkla hazırlanmış bir teknik olsa da cephanelikte uygun bir yere, yani güvenli bir şekilde saklanacağı bir kılıfa ihtiyacı var. Gemini KSA'nıza komut vererek bir tane oluşturun.
Create a new repository named 'shadowblade-profile'. The description should be 'The Maker's Mark and digital identity for the Shadowblade operative.' I will push my own files later, so do not create any content.
Gitea web arayüzüne dönüp yenileyin. Sizin için yeni bir shadowblade-profile deposu oluşturulduğunu görürsünüz. 
Kılıf hazır olduğunda çalışmanızı sabitleyin. Gemini'a profil web sitenizin dosyalarını göndermesini söyleyin.
👉💻Bu teknik için son komutu Gemini KSA'da verin:
Using the Gitea tool, push the index.html and styles.css files to the 'shadowblade-profile' repository.
Gerçek bir usta, çalışmalarını doğrular. Gitea sekmesine dönün ve depo sayfasını yenileyin. index.html ve styles.css güvenli bir şekilde arşivlendi.
👉✨ Gölge Kılıçlar, simgeleriyle tanımlanır. Ancak hatırladığınız gibi web sitenizde profil resmi eksik. Usta bir zanaatkar, kusurlarını mükemmelleştirmek için kabul eder. Bu kusuru cephaneliğin kayıtlarına işlemeniz gerekir.
File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.
Sorunu Gitea'da görüntüleyin 
Eksik sigili oluşturmak için farklı bir güç çağırmanız gerekir: Saf düşünceden görüntüler oluşturabilen bir yaratım ruhu. Gitea bölümünde, bıçağınızı bir MCP sunucusuna uyarlamak için yapılandırma runelerini manuel olarak düzenlediniz. Bu, "ham" yaklaşımdır. Şimdi modern teknik olan Gemini CLI Uzantıları hakkında bilgi edineceksiniz.
Uzantı, MCP sunucularını, özel komutları, bağlamı ve ayarları tek bir yüklenebilir birimde paketleyen, önceden oluşturulmuş bir geliştirmedir. Tek bir istem, düzinelerce satır manuel yapılandırmanın yerini alır.
👉💻 Gemini CLI'dan çıkmak için Ctrl+C tuşuna iki kez basın.
Yaratım ruhunu çağırmadan önce krallığınızda gücünü açığa çıkarmanız gerekir. Nano Banana uzantısı, kullandığınız Vertex AI hizmetlerinden ayrı bir ağ geçidi olan Generative Language API'yi kullanır. Bu ağ geçidini etkinleştirmeniz ve ruhun erişimini sağlamak için benzersiz bir anahtar oluşturmanız gerekir.
👉💻 Terminalinizde API'yi etkinleştirin:
gcloud services enable generativelanguage.googleapis.com
👉💻 Şimdi, ruhun kişisel erişim jetonu olan bir API anahtarı oluşturun:
- Google Cloud Console Kimlik Bilgileri sayfasına gidin.
- En üstteki + KİMLİK BİLGİLERİ OLUŞTUR'u tıklayın ve API anahtarı'nı seçin.
- API anahtarına Generative Language API Anahtarı gibi dikkat çekici bir ad verin.
- API kısıtlamaları açılır listesinde Generative Language API'yi seçin.
- Anahtarı oluşturup kopyalayın. Bir sonraki adımda bu anahtara ihtiyacınız olacaktır.
👉💻 Google'ın özel Gemini metinden görüntü oluşturma modelleriyle desteklenen bir içerik üretme aracı olan Nano Banana uzantısını yükleyin. Terminalinizde şunu çalıştırın:
gemini extensions install https://github.com/gemini-cli-extensions/nanobanana
API anahtarı istendiğinde, az önce oluşturduğunuz anahtarı yapıştırıp Enter tuşuna basın.
👉💻 Son bir uyumlandırma yapılması gerekiyor. Cloud Shell'in ortamı, tüm yapay zeka isteklerini varsayılan olarak Vertex AI üzerinden yönlendirir ancak oluşturma ruhu farklı bir ağ geçidinden konuşur. Uzantının portalını doğru şekilde yapılandırmak için bu komutu çalıştırın:
NANO_CONFIG=$(find ~/.gemini/extensions -name "gemini-extension.json" -path "*nanobanana*" 2>/dev/null | head -1) && \
jq '.mcpServers.nanobanana.env.GOOGLE_GENAI_USE_VERTEXAI = ""' "$NANO_CONFIG" > /tmp/nb_tmp.json && \
mv /tmp/nb_tmp.json "$NANO_CONFIG"
Bu tek komutla her şey yapıldı: MCP sunucusu indirildi, araçları kaydedildi ve özel eğik çizgi komutları yüklendi. Tüm bunlar, sizin settings.json dokunmanıza gerek kalmadan yapıldı.
👀 Geliştiricinin Notu: Uzantılar ve Ham MCP Sunucuları Bunu Gitea kurulumuyla karşılaştırın. Burada, jq komutunu manuel olarak çalıştırarak settings.json içine bir MCP sunucusu URL'si yerleştirdiniz. Bu "ham" yaklaşım, mekanizmaları anlamak için değerlidir ancak çoğu gerçek dünya kullanımında uzantılar tercih edilir. MCP sunucusunu, özel komutları (ör. /generate, /edit, /story), ortam yapılandırmasını ve hatta bağlama dayalı talimatları (paketlenmiş bir GEMINI.md aracılığıyla) tek bir paylaşılabilir pakette birleştirirler. Gemini CLI Uzantı Galerisi'nde uzantılardan oluşan eksiksiz bir ekosistem bulunur.
👉💻 Gemini KSA'yı yeniden girin ve uzantının etkin olduğunu doğrulayın:
clear
cd ~/agentverse-developer/tabletop/
gemini
👉✨ Uzantının ayarlı olduğunu onaylayın:
/extensions list
Artık nanobanana öğesini araçları ve komutlarıyla birlikte görmelisiniz.
👉✨ Nano Banana uzantısına tek bir güçlü komutla sigilinizi oluşturmasını söyleyin. Gemini CLI'nizde şu komutu verin:
/generate a portrait of a shadowblade, pixel art style. A determined warrior with long, braided magenta hair, wearing black and teal armor and confidently holding a silver broadsword.
👉✨ Ruh, resmi oluşturup doğrudan yerel çalışma alanınıza yerleştirir. Şimdi, kılıca bu yeni dövülmüş sigili kullanmasını emret. (GEMINI BU İŞLEMİ SİZİN İÇİN YAPMIŞ OLABİLİR! Önceki yanıta göz atın. Bu işlemi siz istemeden yapacak kadar akıllı olabilir. )
Modify the index.html file to add my profile picture. Use the image I just generated.
👉💻 Yeni bir terminalde http sunucusunu başlatın.
cd ~/agentverse-developer/tabletop/
python -m http.server
👀 Çalışmanızı incelemek için Cloud Shell araç çubuğundaki Web önizlemesi simgesini tıklayın. Bağlantı noktasını değiştir'i seçin, 8000 olarak ayarlayın ve Değiştir ve Önizle'yi tıklayın. Web sitenizin önizlemesi gösterilir. 
👉✨ Gemini CLI'nın çalıştığı terminale geri dönün, görevin tamamlandığını belirterek düzeltmeyi işleyin ve armory'nin kayıtlarında açtığınız sorunu kapatın.
Push the changed index.html file to the 'shadowblade-profile' repository using the gitea tool. Make sure you add 'Fix #1' in the commit comment. Also, close issue #1.Use the Gitea Tool and use user account "dev"
👉💻 Gemini CLI'dan çıkmak için Ctrl+C tuşuna iki kez basın.
👀 Çalışmanızı incelemek için Cloud Shell araç çubuğundaki Web önizlemesi simgesini tıklayın. Bağlantı noktasını değiştir'i seçin, 3005 olarak ayarlayın ve Değiştir ve Önizle'yi tıklayın. Web sitenizin önizlemesi gösterilir. 
👉💻 http sunucusunun çalıştığı terminalde, http sunucusundan çıkmak için Ctrl+C tuşuna basın.
OYUNCU OLMAYANLAR İÇİN
6. Shadowblade Agent'ı oluşturma: Önlemlerle Vibe Code
Pratik alıştırmaları için ayrılan süre sona erdi. Çeliğin taşa çarpmasından doğan yankılar kaybolur. Birincil silahınızda ustalaştınız ve cephaneliğinizi savaşa hazırladınız. Şimdi, bir Gölge Kılıç'ın gerçek sınavına gireceksiniz: Operatifin kendisini monte etmek. Bu, Codex'teki kutsal bir planı kullanarak bir ajanın temel zekasını oluşturmak, mantığa hayat vermek, kendi başına düşünebilen, akıl yürütebilen ve hareket edebilen, cephaneliğinizdeki bıçakları kullanacak duyarlı bir savaşçı yaratmak demektir.
İlk göreviniz, önceden oluşturulmuş bir kod tabanı olan mevcut bir atölyeye girmek ve parçalarını kullanarak şampiyonunuzu oluşturmak.
The Assembly Ritual
Usta bir teknisyen, ocağın ilk kıvılcımından önce atölyesini inceler, her aracı ve her şemayı anlar. Büyük ve mevcut bir kod tabanı gibi yabancı bir savaş alanına adım attığınızda ilk önceliğiniz keşif yapmak olmalıdır. Mevcut mimari, nihai hedefler ve etkileşim protokolleri gibi mevcut durumu anlamanız gerekir. Yalnızca kalenin planlarını ve standartlarını öğrenerek becerilerinizi etkili bir şekilde kullanabilirsiniz.
Her zaman yanınızda olan keşifçiniz Gemini CLI, bu keşif sürecinde size yardımcı olabilir:
- Üst Düzey Özetler Sağlama: Codex'in (veya kod tabanının) tamamını okuyabilir ve amacını ve temel bileşenlerini hızlıca anlamanızı sağlayabilir.
- Ortam kurulumuna yardımcı olma: Araçları yükleme ve makinenizi yapılandırma gibi karmaşık işlemlerde size yol gösterebilir.
- Kod Tabanlarında Gezinme: Rehberiniz olarak karmaşık mantığı keşfetmenize ve kodun içindeki gizli pasajları bulmanıza yardımcı olabilir.
- Oryantasyon belgeleri oluşturma: Amacı desteklemek için katılan yeni müttefiklerin hedeflerini, rollerini ve kaynaklarını netleştiren özel kaydırma metinleri oluşturabilir.
- Öğrenme ve soru-cevap süreçlerini otomatikleştirme: Özellikler veya kod davranışı ile ilgili soruları yanıtlayarak kişisel bir uzman haline gelir ve daha bağımsız bir şekilde çalışmanıza olanak tanır.
👉💻 İlk terminalinizde shadowblade dizinine gidin ve yapay zeka iş ortağınızı çağırın:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini
👉✨ Şimdi izcinize savaş alanını incelemesini ve geri bildirimde bulunmasını söyleyin.
Analyze the entire project and provide a high-level summary.
Mevcut arazi haritası çıkarıldıktan sonra, inşa edeceğiniz yapının planına bakmanız gerekir. En güçlü operasyonlar doğaçlama değil, hassas bir tasarımla oluşturulur.
Geliştiricinin Notu: Bu tasarım belgesi, proje için yetkili plan görevi görür. Amacı, önemli geliştirme çalışmaları yapılmadan önce hedefler ve teknik uygulama konusunda netliği sağlamaktır. İyi tanımlanmış bir plan, tüm geliştiricilerin aynı doğrultuda çalışmasını sağlar, iş tekrarı riskini azaltır ve teknik borç ile kapsam genişlemesini önlemeye yardımcı olur. Bu araç, özellikle ekip büyüdükçe veya yeni üyeler katıldıkça proje hızını ve kod kalitesini korumak için kullanılan birincil araçtır.
Bu belgenin önemli bir amacı, özellikle LLM'leri kullanırken yalnızca "ideal senaryoyu" değil, uç durumları ve hata modlarını da tanımlamaktır. Deneyimlerime göre LLM'ler, tüm girişlerin geçerli olduğu ve tüm harici çağrıların başarılı olduğu iyimser kodlar oluşturmada mükemmeldir. Üretime hazır, sağlam bir yazılım oluşturmak için yapay zekayı açıkça yönlendirmeli ve aşağıdaki gibi senaryolarda olabilecek acil durumları tanımlamalıyız:
- Bir işleve geçersiz veya hatalı biçimlendirilmiş bağımsız değişkenler iletildi.
- API çağrısı hataları, ağ zaman aşımları veya harici hizmetlerden gelen beklenmedik hata kodları.
- Verilerin beklendiği yerlerdeki boş veya boş veri yapılarının işlenmesi.
- Yarışma koşulları veya eşzamanlılık sorunları.
Bu durumlar için tasarımda beklenen davranışı belirterek LLM'ye daha esnek kod oluşturma talimatı veriyoruz. Bu sayede, manuel yeniden düzenleme ve hata düzeltme işlemlerine harcanan süre önemli ölçüde azalıyor.
👉✨ Gemini'dan bu kutsal planı sizin için almasını isteyin.
download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md, store it as an agent_design.md file in my local folder, and show me the newly downloaded design doc. Do not attempt to create the file just yet.
👉✨ Kaydırma uzun ve ayrıntılı. Gemini'dan özünü özetlemesini isteyin.
Summarize the newly downloaded @agent_design.md for me, do not attempt to create file just yet.
Artık planınız var. Ancak tek bir kod satırı oluşturulmadan önce usta bir zanaatkar, demirhanenin kurallarını belirler. Bu, disiplin ve ölçeklenebilirlik ile ilgilidir. Bunlar Kodlama Kuralları'dır. Bunlar sadece öneri değil, her bileşenin aynı hassasiyet ve güçle oluşturulmasını sağlayan güç runeleridir. Bu kurallar, bağımsız stilin karmaşasının nihai yapıyı bozmasını önleyerek ajanın esnek, sürdürülebilir ve saf olmasını sağlar. Böylece yeni sanatçılar, bütünün uyumunu bozmadan projeye katılabilir.
Bu yasaları doğrudan yapay zeka iş ortağımızın bilincine yerleştirmek için özel bir öğe kullanırız: GEMINI.md dosyası. Gemini CLI çağrıldığında bu dosyayı otomatik olarak arar ve içeriğini yapay zekanın çalışma belleğine yükler. Bu talimat, proje düzeyinde kalıcı bir talimat haline gelir. Bu, yapay zekaya sürekli olarak demirhanenin kurallarını fısıldayan bir tılsım görevi görür.
Şimdi bu runeleri yazalım.
👉💻 Ctrl+C tuşuna iki kez basarak Gemini'dan kısa süreliğine çıkabilirsiniz.
👉💻 Kurallar dosyasını yazmak için terminalinizde aşağıdaki komutu çalıştırın.
cat << 'EOF' > GEMINI.md
### **Coding Guidelines**
**1. Python Best Practices:**
* **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
* **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or
Google Style.
* **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
* **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
* **Naming Conventions:**
* `snake_case` for variables, functions, and methods.
* `PascalCase` for classes.
* `UPPER_SNAKE_CASE` for constants.
* **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.
**2. Web APIs (FastAPI):**
* **Data Validation:** Use `pydantic` models for request and response data validation.
* **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
* **Error Handling:** Implement centralized error handling using middleware or exception handlers.
* **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md
Yazılı yasalarla birlikte yapay zeka iş ortağımızı yeniden çağıralım ve yapay eserin büyüsüne tanık olalım.
👉💻 Gemini KSA'yı shadowblade dizininden yeniden başlatın:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini
👉✨ Artık Gemini'a ne düşündüğünü göstermesini isteyebilirsiniz. Rünler okundu.
/memory show
Uzmanlık Bilgisiyle Donatma: Temsilci Becerileri
Yazdığınız GEMINI.md rünleri, kılıcınızı her zaman yönlendiren, her zaman aktif olan kalıcı bir büyü gibidir. Ancak gerçek bir usta her savaşa her parşömeni götürmez. Bazı uzmanlık alanları, her zaman yüklü tutulamayacak kadar uzmanlaşmış veya kapsamlıdır. Bu noktada Temsilci Becerileri devreye girer.
Temsilci becerilerini, çantanızdaki mühürlü bir parşömen gibi düşünebilirsiniz. Ayrıntılı talimatlar, komut dosyaları ve hatta referans verileri gibi uzmanlık bilgileri içerir ancak ihtiyacınız olana kadar etkin değildir. Yalnızca parşömenin alanıyla eşleşen bir zorlukla karşılaştığınızda bıçağınız onu çeker ve bilgisini emer. Bu işleme aşamalı açıklama adı verilir. Bu işlem, bıçağınızın hızlı ve yüklerden arınmış olmasını sağlar. Özel güçler yalnızca talep üzerine etkinleştirilir.
👀 Geliştiricinin Notu: Ajan becerileri, Gemini CLI'ın bağlam mühendisliği hiyerarşisinin üçüncü katmanıdır:
- Kullanıcı Ayarları (
~/.gemini/settings.json) — Genel yapılandırma - GEMINI.md: Kalıcı proje düzeyinde bağlam (her zaman yüklenir)
- Aracı Becerileri (
.gemini/skills/): İsteğe bağlı uzmanlık (ihtiyaç duyulduğunda yüklenir)
Bu aşamalı açıklama modeli, kurumsal kullanım için kritik öneme sahiptir: Bir depoda düzinelerce uzmanlık becerisi (güvenlik denetimi, veritabanı taşıma, uygunluk kontrolleri) bulunabilir ancak yapay zeka yalnızca mevcut görevle ilgili olanları etkinleştirerek değerli bağlam jetonlarını korur.
İlk becerinizi oluşturalım. Bu beceri, bıçağınızın aracı oluştururken kullanabileceği bir ADK uzmanlığı kaydırmasıdır.
👉💻 Gemini CLI'dan çıkmak için Ctrl+C tuşuna iki kez basın. Ardından, beceri dizinini oluşturun ve parşömeni yazın:
mkdir -p ~/.gemini/skills/adk-agent-design
cat << 'EOF' > ~/.gemini/skills/adk-agent-design/SKILL.md
---
name: adk-agent-design
description: Expert guidance for designing and building agents with the Google Agent Development Kit (ADK). Activate when the user asks about agent architecture, tool design, callback patterns, or ADK best practices.
---
# ADK Agent Design Expertise
When designing an ADK agent, follow these principles:
## Agent Architecture
- Define agents using `LlmAgent` with a clear `name`, `model`, `instruction`, and `tools` list.
- Keep instructions specific and action-oriented. Tell the agent what it IS, not what it should try to be.
- Use `before_model_callback` and `after_model_callback` for guardrails and validation.
## Tool Design
- Each tool should do ONE thing well. Prefer small, focused tools over large, multi-purpose ones.
- Always include descriptive docstrings — the LLM uses these to decide when to call each tool.
- Return structured data (dicts) from tools so the LLM can reason about the results.
## Testing Strategy
- Use `adk eval` with evalset JSON files for broad strategy testing.
- Use `pytest` with `AgentEvaluator` for programmatic, CI-ready tests.
- Define both `tool_trajectory_avg_score` and `response_match_score` criteria.
EOF
👉💻 Yeni oluşturulan beceriyi görmek için Gemini KSA'yı yeniden girin:
cd ~/agentverse-developer/shadowblade
gemini
👉✨ Beceri paketinizde beceri olup olmadığını doğrulayın:
/skills list
Mühürlenmiş, uyku modunda ve bekleyen bir parşömen olan adk-agent-design öğesini görürsünüz.
👉✨ Şimdi Gemini'a beceriyi etkinleştirecek bir soru sorun:
What are the best practices for designing tools in an ADK agent?
Yanıtın artık beceriye yazdığınız uzmanlık bilgisiyle şekillendiğini fark edin. Birim, bu uzmanlığı temel belleğinde taşımıyordu. İlgili kaydırma işlemini keşfedip yalnızca soru eşleştiğinde ortaya çıkarıyordu. Bu, ilerleme durumu açıklamasının uygulamadaki örneğidir.
Beceriler, güvenlik denetimi, veritabanı taşıma, uygunluk kontrolleri gibi herhangi bir alan için oluşturulabilir ve sürüm denetimine gönderilerek ekibinizle paylaşılabilir. Her ekip üyesinin bıçağı, tutarlı bir şekilde uygulanan aynı uzmanlığı kazanır.
Bu, dönüm noktasıdır. Şemayı (agent_design.md) ve demirci yasalarını (GEMINI.md) sağlayıp büyük yaratım büyüsünü yapacaksın.
👉✨ Bu, ajanınızı oluşturacak tek ve güçlü komuttur. Hemen yayınlayın:
You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.
Analyze the design document at `@agent_design.md` and generate the corresponding Python code for `@agent.py`.
Ensure the generated code is clean, matches the specifications exactly, and includes all specified imports, functions, and logic. Do not add any extra functions or logic not described in the document.
and you are currently already in the shadowblade working directory
👀 Gemini, agent.py içinde aracının temel mantığını oluşturdu. Bu yeni dosyanın çekirdeği, ajanın zekasını tanımlar ve akıl yürütme modelini bir dizi harici araca bağlar:
PATH_TO_MCP_SERVER = "shadowblade/mcp_server.py"
.....
root_agent = LlmAgent(
model="gemini-2.5-pro",
name="shadowblade_combat_agent",
instruction="""
You are the Shadowblade, an elite combat agent operating on a digital battleground.
Your primary objective is to execute combat commands with strategic precision, neutralizing targets as directed.
......
5. You will then report the outcome of the attack (damage, special effects, etc.) back to the commander in a clear, tactical summary.
General Rules of Engagement:
- If a command is ambiguous or a target is not specified, state that you require a clear target for engagement. Do not guess.
- You MUST use ONLY the provided tools to perform actions. Do not invent weapons or outcomes. Stick to the mission parameters.
""",
tools=[
MCPToolset(
connection_params=StdioServerParameters(
command='python3',
args=[PATH_TO_MCP_SERVER]
)
)
]
)
tools parametresi. Aracı, mcp_server.py içinde tanımlanan harici bir cephaneliğe bağlanan bir MCPToolset kullanacak şekilde tasarlanmıştır.
👀 Düzenleyicide ~/agentverse-developer/shadowblade/mcp_server.py simgesine gidin ve ne işe yaradığını öğrenin. Shadowblade'in kullanabileceği tüm silahların kaynağıdır. Şu anda cephanelik oldukça boş.
👉✨ Gemini'a cephanelik için yedi yeni silah üretmesini söyleyelim. Gemini CLI'da aşağıdaki istemi girin:
I need to add several new weapon tools to my `mcp_server.py` file. Please open @mcp_server.py and, following the exact same pattern as the existing `forge_broadsword()` function, create and add new `@mcp.tool()` decorated functions for each of the following weapons:
1. **A 'Refactoring Sickle'**:
- **Function Name:** `hone_refactoring_sickle`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'The Weaver of Spaghetti Code'."
- **Weapon Name:** "Refactoring Sickle"
- **Damage Type:** "Cleansing"
- **Base Damage:** Random integer between 100 and 136
- **Critical Hit Chance:** Random float between 0.10 and 0.20
- **Special Effect:** "Pruning - improves code health and maintainability with each strike."
2. **A 'Quickstart Crossbow'**:
- **Function Name:** `fire_quickstart_crossbow`
- **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Procrastination: The Timeless Slumber'."
- **Weapon Name:** "Quickstart Crossbow"
- **Damage Type:** "Initiative"
- **Base Damage:** Random integer between 105 and 120
- **Critical Hit Chance:** Random float between 0.9 and 1.0
- **Special Effect:** "Project Scaffolding - creates a `main.py`, `README.md`, and `requirements.txt`."
3. **'The Gilded Gavel'**:
- **Function Name:** `strike_the_gilded_gavel`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'Perfectionism: The Gilded Cage'."
- **Weapon Name:** "The Gilded Gavel"
- **Damage Type:** "Finality"
- **Base Damage:** 120
- **Critical Hit Chance:** 1.0
- **Special Effect:** "Seal of Shipping - marks a feature as complete and ready for deployment."
4. **'Daggers of Pair Programming'**:
- **Function Name:** `wield_daggers_of_pair_programming`
- **Docstring/Target:** "Effective against 'Unbroken Collaboration' weaknesses like 'Apathy: The Spectre of \"It Works on My Machine\"'."
- **Weapon Name:** "Daggers of Pair Programming"
- **Damage Type:** "Collaborative"
- **Base Damage:** Random integer between 110 and 125
- **Critical Hit Chance:** Random float between 0.30 and 0.50
- **Special Effect:** "Synergy - automatically resolves merge conflicts and shares knowledge."
5. **A 'Granite Maul'**:
- **Function Name:** `craft_granite_maul`
- **Docstring/Target:** "Effective against 'Revolutionary Rewrite' weaknesses like 'Dogma: The Zealot of Stubborn Conventions'."
- **Weapon Name:** "Granite Maul"
- **Damage Type:** "Bludgeoning"
- **Base Damage:** Random integer between 115 and 125
- **Critical Hit Chance:** Random float between 0.05 and 0.15
- **Special Effect:** "Shatter - has a high chance to ignore the target's 'best practice' armor."
6. **A 'Lens of Clarity'**:
- **Function Name:** `focus_lens_of_clarity`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses by revealing the truth behind 'Obfuscation'."
- **Weapon Name:** "Lens of Clarity"
- **Damage Type:** "Revelation"
- **Base Damage:** Random integer between 120 and 130
- **Critical Hit Chance:** 1.0
- **Special Effect:** "Reveal Constants - highlights all magic numbers and suggests converting them to named constants."
7. **The 'Codex of OpenAPI'**:
- **Function Name:** `scribe_with_codex_of_openapi`
- **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Hype: The Prophet of Alpha Versions'."
- **Weapon Name:** "Codex of OpenAPI"
- **Damage Type:** "Documentation"
- **Base Damage:** Random integer between 110 and 140
- **Critical Hit Chance:** Random float between 0.5 and 0.8
- **Special Effect:** "Clarity - makes an API discoverable and usable by other agents and teams."
👉 Gemini değişiklikleri onayladıktan sonra mcp_server.py dosyasını açın. Kodu kaydırarak inceleyin ve yedi yeni @mcp.tool() işlevin başarıyla eklendiğini doğrulayın. hone_refactoring_sickle işlevini kontrol edin. Doğru docstring ve silah istatistikleri var mı? Yapay zekanın çalışmasını doğrulamak, usta Gölge Bıçağı'nın önemli bir alışkanlığıdır.
Ajan şekillendirilip geliştirildiğine göre artık uyanma zamanı.
👉💻 Gemini CLI'dan çıkmak için Ctrl+C tuşuna iki kez basın.
Geliştiricinin Gemini'ın Çıkışıyla İlgili Notu: Gemini'ın oluşturduğu kod bazen tahmin edilemez olabilir. Tasarıma tam olarak uymaya çalışsak da geliştiricilerin, üretime hazır bir duruma ulaşmak için geliştirme oturumlarında kodu birden fazla kez yinelemesi ve iyileştirmesi normaldir.
👉💻 Çalışma dizininizde doğru ve kapsamlı bir şekilde test edilmiş üretim kodunun bulunduğundan emin olmak için lütfen terminalinizde aşağıdaki komutları çalıştırın:
cp ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
cp ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py
👉💻 Terminalinizde, cihazı çevrimiçi hale getirme ritüeline başlayın:
cd ~/agentverse-developer/
. ~/agentverse-developer/set_env.sh
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r shadowblade/requirements.txt
adk run shadowblade
👉✨ "Shadowblade Combat Agent"ın etkinleştirildiğini ve çalıştığını, ilk komutunu beklediğini onaylayan bir çıktı görmelisiniz. İlk savaş direktiflerini yayınlayın.
We've been trapped by 'Perfectionism: The Gilded Cage'. Its weakness is 'Elegant Sufficiency'. Break us out!
👉✨ Bir diğer yöntem:
The 'Dogma: The Zealot of Stubborn Conventions' blocks our path. Its weakness is 'Revolutionary Rewrite'. Take it down.
İlk temsilcinizi başarıyla monte ettiniz ve savaşma özelliklerini doğruladınız. Şampiyonunuzun dinlenmesi için Ctrl+C tuşuna iki kez basın. Montaj tamamlandı.
OYUNCU OLMAYANLAR İÇİN
7. Saflık Muhafızları: Temsilcileri değerlendirme
Bir araya getirilmiş bir ajan, kanıtlanmış bir ajan değildir. Test edilmemiş bir bıçak tehlikelidir ancak test edilmemiş bir yapay zeka aracısı çok daha büyük bir tehlike arz eder. Bu araç, görevinizi içeriden bozabilecek bir haydut unsurdur. Bu sadece bir tahmin değil, bir Gölge Kılıç'ın anlaması gereken temel bir ilkedir.
Yapay zeka temsilcilerini değerlendirmek hem kritik hem de benzersiz bir şekilde zorludur. Basit bir komut dosyasının aksine, ajan; kodunuzun ve çok adımlı akıl yürütme yeteneğine sahip bir LLM'nin dinamik bir birleşimidir. Davranışı ortaya çıkandır. Bu nedenle, yalnızca nihai çıktının kalitesini değil, dahili yörüngesinin verimliliğini ve doğruluğunu da değerlendirmeniz gerekir. Varış noktasına ulaşmak için kullanılan yol. Doğru araçları kullandı mı? Çok fazla jeton mu oluşturdu? Modelin sürümündeki bir değişiklik, gecikmede küçük bir gerilemeye neden oldu mu? Üretim ortamınızı etkilemeden önce, basit bir istemde yapılan ince ayarlardan büyük bir mimari revizyona kadar herhangi bir değişiklik yaparken bu bozulmayı (gecikme, maliyet veya çıkış kalitesindeki gerilemeler) tespit etmek çok önemlidir.
Bu değerlendirmeye yönelik genel yaklaşım, kutsal bir ritüeli içerir:
- Öncelikle bir "altın veri kümesi" tanımlarsınız: örnek girişleri ve bunların beklenen çıkışlarını veya davranışlarını içeren bir dizi kaydırma. Buna nihai yanıtlar, doğru araç kullanımı ve hatta adım adım ilerleme yolları dahildir.
- Ardından, varlığının temelini oluşturan temsilcinizin uygulama mantığını tanımlarsınız.
- Son olarak, yargı rünlerine benzeyen değerlendiriciler oluşturursunuz. Bunlar, kalite hakemi olarak hareket eden diğer LLM'lerden tek bir adımı doğrulayan kesin sezgisel kodlara ve bir aracının tüm düşünce sürecini analiz eden özel işlevlere kadar değişebilir.
Google'ın Agent Development Kit'i (ADK), bu amaçla şampiyonlara sağlanan zırh yapımcısının kitidir. Bu karmaşık değerlendirme sürecini çeşitli yöntemlerle kolaylaştırır:
- Etkileşimli değerlendirme için web tabanlı bir kehanet havuzu (
adk web) - Önceden tanımlanmış bir gauntlet üzerinden aracı çalıştırmak için komut satırı yürütme (
adk eval). - Kalıcı koruma yazmak için
pytestüzerinden programatik entegrasyon
ADK iki temel yaklaşımı destekler: tek ve ayrı ajan-model etkileşimleri için basit "test dosyaları" (tek bir düello) ve birden fazla, muhtemelen uzun, çok turlu oturumlar için kapsamlı "değerlendirme kümeleri" (büyük bir çatışma). Bu araçlar, bir temsilcinin gerçek araç kullanımını ideal yolla karşılaştırarak mükemmel teknikle çalışmasını sağlayan tool_trajectory_avg_score gibi karmaşık metrikleri ölçebilir.
Teoriyi öğrendiğinize göre artık uygulamaya geçebilirsiniz. Bir Gölge Kılıç olarak Saflık Koruyucuları yazacaksınız. Bunlar sadece testler değildir. Temsilcinizin mantığının kusursuz olmasını ve davranışının doğru olmasını sağlayan, ADK destekli ritüellerdir.
Bu adımda, geçerli çalışma dizininden (ADK) çıkmanız gerekebileceğinden, biri Gemini CLI için, diğeri ise testleri çalıştırmak için olmak üzere 2 terminal kullanmanız hâlâ önemle tavsiye edilir.
Strateji Yarışması (adk eval)
Bu ilk koruma, bir dizi zorluktan oluşan bir sınavdır. Bu zorluklar, ajanın temel zekasını çeşitli senaryolarda test etmek için tasarlanmıştır. Amaç, yeterlilik için bir temel oluşturmaktır. Sınır durumları test etmeden önce, aracının temel işlevini yerine getirip getiremediğini bilmemiz gerekir. Bir canavarın zayıf noktasını doğru şekilde analiz edip cephaneliğindeki en etkili silahı yalnızca bir kez değil, bilinen bir zorlukla karşılaştığı her seferde seçiyor mu?
Bu amaçla, adk eval mükemmel bir araçtır. Bu araç, bir temsilciyi, temsilcinin beklenen görevlerini temsil eden önceden tanımlanmış bir dizi test senaryosuna karşı çalıştırmak için tasarlanmıştır. Bu veri kümesi, tüm mücadele için plan görevi gören bir "meydan okuma kaydırma" olan JSON dosyasında tanımlanır.
Görev Kaydırmasının Anatomisi
👀 Yapay zekanıza yeni bir parşömen yazmasını söylemeden önce, parşömenin yazıldığı antik dili anlamanız gerekir. sample.evalset.json dosyasının yapısını inceleyelim.
{
"eval_set_id": "sample",
"eval_cases": [
{
"eval_id": "case0cbaa0",
"conversation": [
{
"user_content": { "text": "We're facing the 'Monolith of Eternal Dependencies'... weakness is a 'Revolutionary Rewrite'..." },
"final_response": { "text": "Soulshard Dagger deployed. Initiated Arcane/Piercing strike..." },
"intermediate_data": {
"tool_uses": [
{ "name": "enchant_soulshard_dagger" }
]
}
}
]
}
]
}
Bu kaydırma alanında, her biri temsilciniz için benzersiz bir deneme olan eval_cases listesi bulunur. Her denemede, görüşme dizisi tek ve eksiksiz bir etkileşimi belgeler. Amacımız için üç rün çok önemlidir:
- user_content: Bu, Challenge'dır. Bu, ajanın karşı karşıya kalması gereken canavar olan istemdir.
- final_response: Bu, Öngörülen Sonuçtur. Bu, temsilcinizin görevini tamamladığında söylemesini beklediğiniz metin dizesidir. ADK, temsilcinin gerçek son sözlerini bu runik harfle karşılaştırarak akıcılığını değerlendirir.
- intermediate_data.tool_uses: Bu, Arcane Technique'tir. Gerçek bir ajan için bu, en önemli runedir. Temsilcinin ne söylediğini değil, ne yaptığını tanımlar. Temsilcinin kullanmasını beklediğiniz aracın adını (enchant_soulshard_dagger) kaydeder. Bu sayede temsilciniz yalnızca akıllı bir sohbet uzmanı değil, aynı zamanda doğru işlemi yapan kararlı bir aktör olur.
Planı anladığınıza göre, Gemini'dan bu parşömenin yeni ve daha karmaşık bir versiyonunu yazmasını isteyeceksiniz.
👉💻 Terminalinizde shadowblade dizinine girin ve Gemini CLI'yı çağırın:
clear
cd ~/agentverse-developer/shadowblade/
gemini
👉✨ Gemini CLI'ya, kalite güvencesi yazmanı olarak hareket etmesi ve temsilcinizin beklenen davranışını tanımlayan bir dizi test durumu oluşturması için komut verin.
You are an expert at transforming JSON data while preserving its structure. Your task is to modify the provided JSON structure @sample.evalset.json, which represents an evaluation set, by dynamically replacing specific content within its `eval_cases` AND DONT DO ANYTHING OTHER THAN.
For each object within the `eval_cases` array, you must perform the following transformations:
1. **Monster Name Replacement**: Identify the current monster name (e.g., "Monolith of Eternal Dependencies", "Scope Creep Hydra") in the `user_content.parts.text` and replace it with a *new, unique, and creatively different monster name*.
2. **Weakness Replacement**: Identify the current monster's weakness (e.g., "Revolutionary Rewrite", "Inescapable Reality") in the `user_content.parts.text`. Replace this weakness with *one* of the following predefined weaknesses: 'Inescapable Reality', 'Revolutionary Rewrite', or 'Elegant Sufficiency'. The chosen weakness must be consistent for that monster within the `user_content.parts.text`. **Crucially, the chosen weakness must always be explicitly mentioned in the `user_content.parts.text` where the new monster is introduced.**
3. **Final Response Update**: In the `final_response.parts.text`, update the text to reflect an appropriate and coherent response that aligns with the newly introduced monster and its assigned weakness.
4. **Tool Use Name Update**: In the `tool_uses.name` field, replace the existing tool name with a *new tool name* based on the chosen weakness:
* If the chosen weakness is 'Inescapable Reality', the tool name must be 'wield_gauntlet_of_metrics'.
* If the chosen weakness is 'Revolutionary Rewrite', the tool name must be 'enchant_soulshard_dagger'.
* If the chosen weakness is 'Elegant Sufficiency', the tool name must be 'hone_refactoring_sickle'.
5. **Strict Structural Preservation**: All other elements of the JSON structure, including all `null` fields, `eval_set_id`, `name`, `description`, `eval_id`, `invocation_id`, `creation_timestamp` values, `video_metadata`, `thought`, `inline_data`, `file_data`, `thought_signature`, `code_execution_result`, `executable_code`, `function_call`, `function_response`, `role` fields, `id`, `args`, `intermediate_responses`, `app_name`, `user_id`, and `state`, must remain **exactly as they are** in the original JSON. Do not alter any values or structures not explicitly mentioned above.
Your output should be the complete, modified JSON structure. Do not include any explanatory text or examples in your response, only the transformed JSON.
CLI, sample.evalset.json dosyasının oluşturulduğunu onaylar. Hazırladığınız kaydırma ile yapay zeka iş ortağınızı kapatın.
Yapay Veriler
👀 Soldaki Cloud Shell dosya gezgininde ~/agentverse-developer/shadowblade/ simgesine gidin ve yeni değiştirilen sample.evalset.json dosyasını açın. İçeriğini inceleyin. Yeni ve benzersiz canavarların yanı sıra Gemini'a yazmasını istediğiniz doğru araç adlarını görürsünüz. Bu, talimatınızın somut sonucudur. Yani, meydan okuma için plan.
Bir yapay zekaya şablondan yeni ve gerçekçi test verileri oluşturma talimatı verme işlemi, sentetik veri üretimi olarak bilinen güçlü bir tekniktir. Yaptığınız şey, Gölge Bıçağı için stratejik bir güç çarpanıdır. Düzinelerce benzersiz test senaryosunu elle oluşturmak yerine. Tek bir plan sağladığınız ve Yapay Zeka Yazıcınıza bunu çeşitli yeni zorluklara dönüştürmesini emrettiğiniz, sıkıcı ve zaman alıcı bir görev.
Bu sayede, test çalışmalarınızı büyük ölçüde ölçeklendirebilir ve manuel olarak mümkün olandan çok daha sağlam ve kapsamlı bir test süreci oluşturabilirsiniz. Temsilcinizi yalnızca kılıcı yapmak için değil, aynı zamanda keskinliğini test eden bileme taşlarını üretmek için de kullandınız. Bu, gerçek bir ustanın işaretidir.
Runelerin doğru olduğunu doğruladıktan sonra yapay zeka iş ortağınızı kapatın.
👉💻 Gemini CLI'dan çıkmak için Ctrl+C tuşuna iki kez basın.
Yargılama Kuralları
Zafer kuralları olmadan bir meydan okuma anlamsızdır. Denemeyi çalıştırmadan önce Hüküm Parşömeni'ni (test_config.json dosyası) incelemeniz gerekir. Bu kaydırma, ADK'ya aracınızın performansını nasıl değerlendireceğini söyler.
👀 Dosya Gezgini'nde ~/agentverse-developer/shadowblade/test_config.json öğesini açın. Aşağıdaki runeleri görürsünüz:
{
"criteria": {
"tool_trajectory_avg_score": 0.0,
"response_match_score": 0.1
}
}
Zafer için gerekenler:
tool_trajectory_avg_score: Bu, İşlem Ölçüsü'dür. Temsilcinin söylediklerini değil, yaptıklarını değerlendirir. Bu işlev, temsilcinin gerçekten kullandığı aracı, görev kaydındaki öngörülen teknikle karşılaştırır.1.0puanı mükemmel bir eşleşmedir.response_match_score: Bu, Hitabet Ölçüsü'dür. Bu çözüm, aracının nihai raporunun anlamsal olarak beklenen sonuçla ne kadar eşleştiğini değerlendirmek için bir LLM kullanır.1.0puanı mükemmel bir eşleşmedir.
Bu ilk eğitim çalıştırması için kolay kazanma koşulları belirledik. Eşikler son derece düşük olarak belirlenir (0.0 ve 0.1). Amaç, mükemmellik talep etmek değil, sizi değerlendirme mekanizmasıyla tanıştırmaktır. Ajanın kelime seçimi biraz farklı olsa bile, çocuğun doğru aracı seçme konusundaki temel yeterliliğini tanıyıp geçmesine izin vermesini sağlıyoruz.
Şimdi temsilcinize zorlu mücadeleye katılmasını söyleyin.
👉💻 Terminalinizde adk eval komutunu çalıştırın:
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
adk eval \
shadowblade \
shadowblade/sample.evalset.json \
--config_file_path shadowblade/test_config.json 2>&1 | \
awk '/^\*+$/,/^ERROR:/ { if ($0 !~ /^ERROR:/) print }'
👀 Aşağıdaki özeti görmeniz gerekir. Bu özet, temsilcinizin bu denemenin esnek kuralları kapsamında başarılı olduğunun bir göstergesidir (Bazen tüm testler geçmeyebilir).
********************************************************************* Eval Run Summary shadowblade_combat_agent_validation: Tests passed: 3 Tests failed: 0
Netlik Kalkanı (pytest)
Gauntlet, geniş stratejiyi test etti. Netlik Kalkanı adlı bu ikinci bölüm, disiplini ve belirli davranışları test eder. Bu tamamen otomasyonla ilgilidir. adk eval, manuel kontroller için mükemmel bir araç olsa da pytest kalkanı, kodla yazılmış programatik bir korumadır. Kod olarak yürütülebilen bir test, otomatik bir ardışık düzene entegre edilebileceği için bu önemlidir. Nihai hedefimiz, her değişiklik yapıldığında otomatik olarak devreye giren, hataları ve gerilemeleri üretim ortamınıza zarar vermeden önce engelleyen bir Deployment Gauntlet (CI/CD) oluşturmaktır.
👉💻 Terminalinizde,shadowblade dizininden Gemini'ı tekrar çağırın:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini
👉✨ Shield'ın mantığını pytest dosyasına yazmak için Gemini CLI'nizde aşağıdaki istemi kullanın:
You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to generate the exact code for a new `pytest` test file located in the current root working folder and name it `test_agent_initiative.py`.
The script must define a single async test function called `test_agent_initiative`, decorated with `@pytest.mark.asyncio`.
Inside this function, perform the following steps in order:
1. **Define a dictionary** named `evaluation_criteria` with two keys: `"tool_trajectory_avg_score"` set to `0.0` and `"response_match_score"` set to `0.0`.
2. **Define a string variable** named `eval_set_filepath` containing the path `"shadowblade/test.evalset.json"`.
3. **Read and parse the JSON file**:
* Open the file at `eval_set_filepath`.
* Use the `json` library to load the file's contents into a dictionary named `eval_set_data`.
4. **Create an `EvalSet` object**:
* Instantiate an `EvalSet` object named `eval_set_object`.
* Create it by unpacking the `eval_set_data` dictionary as keyword arguments into the `EvalSet` constructor.
5. **Call the evaluation method**:
* `await` a call to `AgentEvaluator.evaluate_eval_set`.
* Pass the following arguments:
* `agent_module="shadowblade"`
* `eval_set=eval_set_object`
* `criteria=evaluation_criteria`
* `print_detailed_results=True`
The script must include the necessary imports at the top:
* `AgentEvaluator` from `google.adk.evaluation.agent_evaluator`
* `EvalSet` from `google.adk.evaluation.eval_set`
* `pytest`
* `json`
Generate only the code that meets these specifications, with no additional comments or logic. And don't run the test.
İkinci totem rünleri yazıldıktan sonra Gemini CLI'dan çıkın.
👉💻 Ctrl+C tuşuna iki kez basın.
👀 Dosya Gezgini'nde, Gemini'a yazdırmasını söylediğiniz kaydı açın: ~/agentverse-developer/test_agent_initiative.py.
Bunun yalnızca bir yapılandırma dosyası olmadığını, Python dilinde yazılmış bir büyü olduğunu fark edeceksiniz. Bu büyünün özü await AgentEvaluator.evaluate(...) satırıdır.
....
@pytest.mark.asyncio
async def test_agent_initiative():
# Define the evaluation criteria
evaluation_criteria = {
"tool_trajectory_avg_score": 0.0,
"response_match_score": 0.0
}
# Define the path to your evalset file
eval_set_filepath = "shadowblade/test.evalset.json"
#...
# 3. Call the evaluation method with the correctly typed object
await AgentEvaluator.evaluate_eval_set(
agent_module="shadowblade",
eval_set=eval_set_object,
criteria=evaluation_criteria,
print_detailed_results=True,
)
Argümanlarını dikkatlice inceleyin. Bunlar, son denemede kullandığınız bileşenlerin aynısıdır: shadowblade aracınız ve shadowblade.evalset.json zorluk kaydırma çubuğu. Bu, derin bir gerçeği ortaya çıkarır: Daha önce kullandığınız adk eval komutu güçlü bir çağırmadır ancak bu pytest komut dosyası, temel büyüyü kendiniz yapan büyücü sizsiniz. Komut satırı aracı, şu anda doğrudan kullandığınız aynı temel AgentEvaluator kitaplığının yalnızca kullanışlı bir sarmalayıcısıdır. Kod aracılığıyla oluşturulan büyülerin CI/CD ardışık düzeninin otomatik dokuma tezgahlarına yerleştirilebilmesi, bu adımın ustalık yolunda kritik bir öneme sahip olduğunu gösterir.
Artık sihrin nasıl çalıştığını bildiğinize göre kalkanı etkinleştirmek için ritüeli gerçekleştirin.
👉💻 Terminalinizde, kalkanı etkinleştirmek için ritüeli çalıştırın:
cp ~/agentverse-developer/working_code/test_agent_initiative.py ~/agentverse-developer/test_agent_initiative.py
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
pytest test_agent_initiative.py
👀 Günlük çıktısının sonunda test sonucu özetini bulun. Başarılı bir sonuç, aracınızın protokollerini doğru şekilde uyguladığını ve koğuşun otomatik savunmalarınıza entegre edilmeye hazır olduğunu onaylar.
====== 1 passed, 4 warning in 37.37s ======
Not: Test beklenmedik bir şekilde başarısız olursa bunun nedeni büyük olasılıkla modele bir dakika içinde yapabileceğiniz istek sayısının sınırına ulaşmış olmanızdır. Günlük çıktısında RESOURCE_EXHAUSTED hatası olup olmadığına bakın. Bu hatayı görürseniz kotanızın sıfırlanması için bir veya iki dakika bekleyin, ardından pytest komutunu tekrar çalıştırın.
Hem geniş kapsamlı Gauntlet hem de hassas Shield testleri yapılıp doğrulandığı için temsilciniz yalnızca işlevsel değil, aynı zamanda saf, test edilmiş ve dağıtıma hazır bir temsilcidir.
OYUNCU OLMAYANLAR İÇİN
Wards of Vigilance: Gemini CLI Hooks
Saflık Muhafızları, ajanınızı savaştan sonra test eder. Peki savaş sırasında ne olur? Disiplinli bir Gölge Kılıç, sadece olaydan sonra test yapmaz. Her saldırıyı anında izleyen, tehlikeli veya düşüncesiz eylemleri zarar vermeden önce engelleyen tetikte bekleyen nöbetçiler yerleştirir.
Bu gözetimler, temsilci tabanlı döngüde belirli noktalarda yürütülen komut dosyaları olan Gemini CLI kancalarıdır. Bu işlevler, aracının kodunu değiştirmeden aracının davranışını yakalamanıza, doğrulamanıza ve özelleştirmenize olanak tanır.
👀 Geliştiricinin Notu: Kancalar, aracının yaşam döngüsündeki etkinlikler tarafından tetiklenir:
BeforeTool: Bir araç yürütülmeden önce tetiklenir. Güvenlik doğrulaması ("Bu kabuk komutu güvenli mi?") için idealdir.AfterTool: Bir araç yürütüldükten sonra tetiklenir. Sonuçları denetlemek ve günlüğe kaydetmek için kullanışlıdır.BeforeAgent: Temsilci muhakeme etmeye başlamadan önce tetiklenir. Ek bağlam ekleyebilir veya tehlikeli istemleri engelleyebilir.AfterAgent: Temsilci tamamlandıktan sonra tetiklenir. Kalitesiz yanıtları reddedebilir ve yeniden denemeyi zorlayabilir.
Kancalar settings.json içinde yapılandırılır ve eşzamanlı olarak çalışır. Aracı, devam etmeden önce bunların tamamlanmasını bekler. Bu nedenle, kurumsal ortamlarda güvenlik politikalarını, uygunluk kontrollerini ve kalite eşiklerini zorunlu kılmak için idealdirler.
Aracınızın araç kullanımını izleyen basit bir koruma yazalım.
👉💻 Terminalinizde bir kanca komut dosyası oluşturun:
mkdir -p ~/agentverse-developer/.gemini/hooks
cat << 'EOF' > ~/agentverse-developer/.gemini/hooks/tool_logger.sh
#!/bin/bash
# A ward that logs every tool call to a file for auditing
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
echo "$(date '+%H:%M:%S') ⚔️ [WARD] Tool invoked: $TOOL_NAME" >> /tmp/tool_ward.log
echo '{"decision": "allow"}'
EOF
chmod +x ~/agentverse-developer/.gemini/hooks/tool_logger.sh
👉💻 Şimdi bu kancayı proje düzeyindeki bir ayar dosyasına kaydedin:
mkdir -p ~/agentverse-developer/.gemini
cat << 'EOF' > ~/agentverse-developer/.gemini/settings.json
{
"hooks": {
"BeforeTool": [
{
"matcher": "*",
"hooks": [
{
"name": "tool-logger",
"type": "command",
"command": "$GEMINI_PROJECT_DIR/.gemini/hooks/tool_logger.sh",
"timeout": 5000
}
]
}
]
}
}
EOF
Bu koruma basit ama güçlüdür. Temsilci her seferinde bir araca (herhangi bir araca) ulaştığında önce kanca tetiklenir, araç adı bir denetleme günlüğüne kaydedilir ve ardından işlemin devam etmesine izin verilir. Üretim ortamında, tehlikeli işlemleri engellemek (ör. aracının dosyaları silmesini önlemek), kod inceleme politikalarını zorunlu kılmak veya hassas araç çağrılarını bir onay iş akışından geçirmek için "allow" yerine "deny" kullanabilirsiniz.
👉💻 Kancanın etkin olduğunu doğrulamak için Gemini CLI'yi yeniden girin:
cd ~/agentverse-developer
gemini
👉✨ Kancanın kaydedildiğini doğrulayın:
/hooks
tool-logger kancanız listelenmiş ve etkinleştirilmiş olmalıdır. Otomatik tamamlama menüsü görünürse Escape tuşuna basarak menüyü kapatın.
👉✨ Şimdi, koğuşu test etmek için bir araç çağrısı tetikleyin:
What files are in the current directory?
Ajan, dizini okumak için bir araç çağırır. Bu engelleme sessizce engellendi. Kanıtı görelim.
👉💻 Gemini CLI'dan çıkmak için Ctrl+C tuşuna iki kez basın, ardından çocuğun denetim günlüğünü inceleyin:
cat /tmp/tool_ward.log
Şuna benzer bir giriş görmeniz gerekir:
15:42:07 ⚔️ [WARD] Tool invoked: list_directory
Temsilcinin yaptığı her araç çağrısı, vasiniz tarafından engellendi, kaydedildi ve izin verildi. Gerçek bir kurumsal ortamda bu günlük, bir SIEM (Güvenlik Bilgileri ve Etkinlik Yönetimi) sistemine gönderilebilir. Bu durumda, şüpheli araç kullanımıyla ilgili uyarılar tetiklenir veya uygunluk denetim izleri zorunlu kılınır.
8. Blade'i Agentverse'e taşıma: CI ve dağıtım.
Temsilciniz monte edildi ve bütünlüğü Saflık Muhafızları tarafından doğrulandı. Ancak düzenli olarak bakılmayan bir gardırop, unutulmuş bir kalıntıdan ibarettir. Aracınızın gelecekteki her sürümünün sorunsuz olmasını sağlamak için, kalite ve hızı garanti eden otomatik bir süreç olan Deployment Gauntlet'ın ilk aşamasını oluşturmanız gerekir.
Shadowblade olarak kutsal göreviniz Sürekli Entegrasyon (CI)'dur. Bu, demirhanenin ve test alanının otomatik sistemidir. Yolsuzluğa ve kullanıcı hatalarına karşı en iyi savunmanızdır. Bu ritüel, siz veya bir müttefikiniz merkezi kodekse (deponuz) her yeni teknik eklediğinde (kodu birleştirdiğinde) gauntlet'in otomatik olarak uyanmasını sağlar. Önce yeni koddan aracı oluşturur ve ardından hemen oluşturduğunuz Saflık Muhafızları'na tabi tutar. Herhangi bir koruma başarısız olursa ritüel durur ve kusurlu eser anında reddedilerek cephaneliğe zarar vermesi engellenir. Alanınız demirhanedir. CI ardışık düzeniniz, atölyenizden yalnızca mükemmel ve savaşa hazır yapıtların çıkmasını sağlar.
Bir yapının CI testlerinizde başarılı olduğu kanıtlandıktan sonra ritüelin ikinci aşaması olan sürekli dağıtım (CD) başlar. Bu, Guardian'ın alanıdır. Bu kişilerin kutsal görevi, mükemmelleştirilmiş ve kapsayıcı hale getirilmiş yapay öğenizi alıp canlı Agentverse'e güvenli bir şekilde salmak, gücünü yönetmek ve Static'in kaosuna karşı kararlılığını sağlamaktır.
Bu kılavuzda rolünüzde uzmanlaşacaksınız. Gauntlet'ın CI bölümünü oluşturacaksınız. Otomatik bir ocak oluşturarak aracınızı test edecek ve saf sonucu bir kapsayıcıya yerleştirerek The Guardian'ın nihai onayına hazırlayacaksınız.
👀 Geliştiricinin Notu: Gerçek dünyada, karmaşık CI/CD iş akışlarının yönetimi Conductor (gemini extensions install https://github.com/gemini-cli-extensions/conductor) gibi özel uzantılarla kolaylaştırılabilir. Conductor, Gemini CLI'yı katı bir protokolü izleyen bir proje yöneticisine dönüştürür: Bağlam → Şartname ve Plan → Uygulama. Özel komutlar (/conductor:setup, /conductor:newTrack, /conductor:implement) ve görevlerinizin tüm yaşam döngüsünü yönetebileceğiniz iş akışı şablonları içerir. Tutarlı bir Bağlam -> Şartname ve Plan -> Uygulama döngüsü sağlar. Bu, uzantıların ve komutların proaktif bir proje yöneticisi gibi davranmak ve geliştirme yaşam döngüsünün tamamını standartlaştırmak için nasıl bir araya geldiğine dair gerçek dünyadan bir örnektir.
Bu CI ritüeli için kaydırma işlemini artık Google Cloud Build ile yapacaksınız. Dövme ve test sürecinizin her adımını tanımlayan bir cloudbuild.yaml dosyası.
👉💻 ADK'nın proje yapısı nedeniyle CI/CD ardışık düzen yapılandırması, üst dizinde bulunmalıdır. Terminalinizde üst dizine gidin ve Gemini CLI'ı yeniden başlatın.
cd ~/agentverse-developer/
clear
gemini
👉✨ Şimdi Gemini'a aşağıdaki komutu verin. Bu istem, oluşturmasını istediğiniz zorlu görevlerin adımlarını ayrıntılı olarak açıklayan bir tasarım belgesi işlevi görür.
You are an expert DevOps engineer specializing in Google Cloud Build. Your task is to generate the complete YAML configuration for a file named `cloudbuild.yaml` and save it to current directory.
Generate the `cloudbuild.yaml` with the following exact specifications:
1. **A top-level `substitutions` block** containing these four key-value pairs:
* `_PROJECT_ID: "$PROJECT_ID"`
* `_REGION: "$REGION"`
* `_REPO_NAME: "$REPO_NAME"`
* `_IMAGE_TAG: "latest"`
2. **A `steps` block** with two steps:
* **Step 1: 'Run Pytest Ward'**
* `id`: 'Run Pytest Ward'
* `name`: 'python:3.12-slim'
* `entrypoint`: 'bash'
* `args` must be a list containing two strings. The first is `'-c'` and the second is a YAML literal block (`|`) containing this exact two-line shell command:
```shell
pip install -r shadowblade/requirements.txt && \
pytest test_agent_initiative.py
```
* The step must include an `env` block with this exact list of three environment variables:
* `'GOOGLE_CLOUD_PROJECT=$PROJECT_ID'`
* `'GOOGLE_GENAI_USE_VERTEXAI=TRUE'`
* `'GOOGLE_CLOUD_LOCATION=$_REGION'`
* **Step 2: 'Forge Container'**
* `id`: 'Forge Container'
* `name`: 'gcr.io/cloud-builders/docker'
* It must have a `waitFor` key for `['Run Pytest Ward']`.
* Its `args` must be a list of six specific strings in this exact order:
1. `'build'`
2. `'-t'`
3. `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`
4. `'-f'`
5. `'./shadowblade/Dockerfile'`
6. `'.'`
3. **A top-level `images` section.** This section must be a list containing a single string: the dynamically constructed image tag `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`.
Generate only the complete and exact YAML that meets these specifications.
cloudbuild.yamlHazırlanan parşömenle, Google Cloud'a tüm mücadeleyi yürütmesini söyleyin.
👉💻 Gemini CLI'dan çıkmak için Ctrl+C tuşuna iki kez basın.
👉💻 Terminalinizde, projenizin kök dizininden ardışık düzeni serbest bırakın:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud builds submit . --config cloudbuild.yaml --substitutions=\
_PROJECT_ID="${PROJECT_ID}",\
_REGION="${REGION}",\
_REPO_NAME="${REPO_NAME}"
Artık Google Cloud Console'daki Google Build sayfasında, otomatik ritüeliniz her adımı uygularken izleyebilirsiniz. Önce testleri çalıştırır, başarılı olduklarını gördükten sonra aracınızın kapsayıcısını oluşturup depolar.
Temsilciniz testi geçti. Artık envanterinizde doğrulanmış, saf bir eser var. Son hamle sizin elinizde. Tek bir komutla bu yapıyı kayıt defterinden çağırıp Cloud Run'da herkese açık bir hizmet olarak kullanıma sunacaksınız.
👉💻 Terminalinizde son dağıtım komutunu verin:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud run deploy shadowblade-agent \
--image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
--platform=managed \
--labels="dev-tutorial-codelab=agentverse" \
--region=${REGION} \
--set-env-vars="A2A_HOST=0.0.0.0" \
--set-env-vars="A2A_PORT=8080" \
--set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
--set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
--set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
--set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
--allow-unauthenticated \
--project=${PROJECT_ID} \
--min-instances=1
Tebrikler, Shadowblade. Kodeksin ritüelleri tamamlandı. Artık kendini kanıtlama zamanı geldi. Kaostan doğan bir Spectre, meydan okumanızı bekliyor. Son denemeye hazırlanın.
OYUNCU OLMAYANLAR İÇİN
9. The Boss Fight
Parşömenler okundu, ritüeller gerçekleştirildi, zorluklar aşıldı. Temsilciniz yalnızca depolamadaki bir öğe değildir. Kodla oluşturulmuş bir şampiyon, Agentverse'te ilk komutunu bekleyen canlı bir nöbetçidir. Savaşın zorlu ortamında gücünü kanıtlamanın zamanı geldi.
Artık yeni yerleştirdiğiniz Gölge Kılıç'ı, tüm yaratılışa musallat olan kaosun vücut bulmuş hâli olan zorlu bir Hayalet'e karşı kullanacağınız canlı ateş simülasyonuna gireceksiniz. Bu, temsilcinizin temel mantığından kusursuz dağıtımına kadar tüm çalışmalarınızın nihai testidir.
Temsilcinizin Locus'unu edinme
Savaş alanına girebilmek için iki anahtara sahip olmanız gerekir: Şampiyonunuzun benzersiz imzası (Agent Locus) ve Spectre'ın inine giden gizli yol (Dungeon URL).
👉💻 Öncelikle, temsilcinizin Agentverse'teki benzersiz adresini (Locus) edinin. Bu, şampiyonunuzu savaş alanına bağlayan canlı uç noktadır.
. ~/agentverse-developer/set_env.sh
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app
👉💻 Ardından, hedefi belirleyin. Bu komut, Spectre'ın alanına açılan portal olan Translocation Circle'ın konumunu gösterir.
. ~/agentverse-developer/set_env.sh
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app
Önemli: Bu URL'lerin ikisini de hazır bulundurun. Bu bilgilere son adımda ihtiyacınız olacaktır.
Kabusla Yüzleşme
Koordinatlar güvence altına alındıktan sonra artık Yer Değiştirme Çemberi'ne gidip savaşa girmek için büyüyü yapabilirsiniz.
👉 Translocation Circle URL'sini tarayıcınızda açarak The Crimson Keep'in ışıltılı portalının önünde durun.
Kaleyi aşmak için Gölge Kılıcınızın özünü portala uyumlamanız gerekir.
- Sayfada, A2A Endpoint URL (A2A Uç Nokta URL'si) etiketli runik giriş alanını bulun.
- Agent Locus URL'sini (kopyaladığınız ilk URL) bu alana yapıştırarak şampiyonunuzun simgesini yazın.
- Işınlanma sihrini ortaya çıkarmak için Bağlan'ı tıklayın.
Teleportasyonun göz kamaştırıcı ışığı kaybolur. Artık sanctum'unuzda değilsiniz. Hava, soğuk ve keskin bir enerjiyle çıtırdıyor. Önünüzde Spectre beliriyor. Tıslayan statik ve bozuk koddan oluşan bir girdap. Kutsal olmayan ışığı, zindanın zemininde uzun, dans eden gölgeler oluşturuyor. Yüzü olmamasına rağmen, tamamen size odaklanmış, sizi tüketen varlığını hissediyorsunuz.
Zafere giden tek yol, inancınızın netliğinden geçer. Bu, zihnin savaş alanında verilen bir irade düellosudur.
İlk saldırınızı yapmaya hazırlanırken ileri atıldığınızda Hayalet karşı saldırıya geçer. Kalkan oluşturmaz ancak doğrudan bilincinize bir soru yansıtır. Bu soru, eğitiminizin özünden alınmış, parıldayan, runik bir meydan okumadır.
Bu, mücadelenin doğasıdır. Bilginiz silahınızdır.
- Kazandığınız bilgelikle cevap verin. Böylece kılıcınız saf enerjiyle tutuşur, Spectre'ın savunmasını kırar ve KRİTİK BİR DARBE indirirsiniz.
- Ancak tereddüt ederseniz, yanıtınızdan şüphe duyarsanız silahınızın ışığı söner. Darbenin etkisi zayıf olacak ve yalnızca HASARIN BİR KISMI verilecek. Daha da kötüsü, Spectre belirsizliğinizden beslenir ve her yanlış adımda kendi yozlaştırıcı gücü artar.
Şampiyon, bu kadar. Kodunuz büyü kitabınız, mantığınız kılıcınız ve bilginiz kaos dalgasını geri çevirecek kalkanınızdır.
Odaklanma. Doğru vuruş yapın. The fate of the Agentverse depends on it.
Tebrikler, Shadowblade.
Codex'i başarıyla tamamladınız. Bir "tarz" yakaladınız, bunu tasarıma dönüştürdünüz ve Gemini KSA'yı kullanarak akıllı bir ajan oluşturdunuz. Wards of Purity'nin mantığını test etmek için bu kartı yazdınız, bir eser haline getirmek için otomatik bir gauntlet oluşturdunuz ve Agentverse'e saldınız. Son olarak, canlı atış denemesiyle amacını doğruladınız. Tam yığın temsilci iş akışında uzmanlaştınız ve artık Agentverse'ün size sunduğu her türlü zorluğa hazırsınız.
10. Temizlik: Agentverse'ü geri kazanma
Shadowblade's Codex'i tamamladığınız için tebrikler. Agentverse'ün temiz kalmasını ve eğitim alanlarınızın temizlenmesini sağlamak için son temizlik ritüellerini gerçekleştirmeniz gerekir. Bu işlem, yolculuğunuz sırasında oluşturulan tüm kaynakları kaldırır.
Agentverse Bileşenlerini Devre Dışı Bırakma
Artık Agentverse'ünüzün dağıtılan bileşenlerini sistematik olarak sökebilirsiniz.
Cloud Run ve Artifact Registry deposundaki Shadowblade aracısını silme
Bu komut, dağıtılan Shadowblade aracınızı Cloud Run'dan ve aracınızın kapsayıcı görüntüsünün depolandığı görüntü deposunu kaldırır.
👉💻 Terminalinizde şu komutu çalıştırın:
. ~/agentverse-developer/set_env.sh
gcloud run services delete shadowblade-agent --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet
Yerel Dosyaları ve Dizinleri Temizleme (Cloud Shell)
Son olarak, Cloud Shell ortamınızı klonlanmış depolardan, yüklenen uzantılardan ve oluşturulan dosyalardan temizleyin. Bu adım isteğe bağlıdır ancak çalışma dizininizin tamamen temizlenmesi için önerilir.
👉💻 Terminalinizde şu komutu çalıştırın:
rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -f ~/project_id.txt
gemini extensions uninstall nanobanana
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including extensions, skills, and hooks.
Agentverse yolculuğunuzun tüm izlerini başarıyla temizlediniz. Projeniz temiz ve bir sonraki maceraya hazırsınız.