Agents CLI'yı kullanarak Agent Runtime'a ADK aracısı dağıtma

1. Genel Bakış

Bu laboratuvar, Kaggle'ın 5-Day AI Agents: Intensive Vibe Coding Course with Google kursunun bir parçasıdır. Ek codelab'leri ve kaynakları etkinlik sitesinde bulabilirsiniz.

Bu codelab'de, ADK 2.0 aracısını yerel geliştirme ortamından üretime hazır bir dağıtıma geçirirsiniz. Grafik tabanlı iş akışınızı Google Cloud'daki Agent Runtime üzerinde paketlemek, doğrulamak ve canlı olarak barındırmak için agents-cli kullanacaksınız.

Bu dağıtım sürecini keşfetmek için Ambient Expense Agent'ın yerel bir prototipini buluta dağıtmadan önce sıfırdan oluşturacaksınız. (Bu aracının temel mantığını tasarlama hakkında daha ayrıntılı bilgi için Kaggle etkinlik sitesindeki temel codelab'lere bakın). Ortam Gideri Temsilcisi, standart talepleri anında onaylayıp daha büyük giderleri insan müdahalesiyle inceleme için işaretleyerek çalışanların gider raporlamasını kolaylaştırır. Bu otomatik onayları ve risk analizi adımlarını koordine etmek için ADK 2.0 grafik tabanlı iş akışını kullanır.

Neler öğreneceksiniz?

• Yerel Ambient Expense Agent projenizi bulut barındırma için hazırlama
• Gerekli dağıtım tanımlayıcıları ve üretim sarmalayıcıları nasıl oluşturulur?
• Nasıl deneme çalıştırması yapacağınız ve kodunuzu doğrudan Agent Runtime'a nasıl dağıtacağınız
• Cloud Trace'i kullanarak üretim aracınızın yürütme izlerini izleme

İhtiyacınız olanlar

• Faturalandırmanın etkin olduğu aktif bir Google Cloud projesi.
• gcloud SDK'nın yüklü ve kimliği doğrulanmış olması gerekir.
• uv paket yöneticisi yüklü olmalıdır.
• Google Antigravity IDE yüklü olmalıdır.

Ön koşullar

Bu codelab'de aşağıdaki konularda bilgi sahibi olduğunuz varsayılmaktadır:

• Terminal kullanarak sisteminizde gezinme
• Temel Python geliştirme kavramları
• Temel Google Cloud kavramları.

2. Google Cloud ortamınızı kurma

Dağıtım yapmadan önce Google Cloud projenizi yapılandırmanız ve gerekli API'leri etkinleştirmeniz gerekir.

👉 Antigravity istemi:

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

Antigravity bu istemi yürüttüğünde, projenizi yapılandırmak ve hizmetleri etkinleştirmek için gerekli gcloud terminal komutlarını önerip çalıştırır. Kimlik doğrulama adımında Antigravity, terminalde bir yetkilendirme URL'si gösterir. Web tarayıcınız üzerinden oturum açmak ve erişim izni vermek için bağlantıyı tıklayın. Tarayıcıda oturum açma işlemini tamamladığınızda Antigravity, proje ortamı değişkenlerinizi ayarlamak ve gerekli API'leri etkinleştirmek için yürütmeye devam eder.

Not: Bu yeni bir proje ise gcloud, önce Service Usage API'yi etkinleştirmenizi isteyebilir. İstenirse terminalde verilen bağlantıyı tıklayarak Cloud Console'da etkinleştirin.

3. Agents CLI ve ADK becerilerini ayarlama

Antigravity'nin ADK aracılarını iyi bir şekilde oluşturup dağıtabilmesi için ADK beceri setine ihtiyacı vardır. Bunlar ADK API'si, proje iskeleti, agents-cli dağıtım iş akışı ve değerlendirme için paketlenmiş referanslardır. agents-cli araç zincirini yüklediğinizde bu beceriler de kodlama aracınıza yüklenir. Böylece, yerel iskeleden bulut dağıtımına kadar aracınızın tüm yaşam döngüsünü yönetebilirsiniz.

👉 Aşağıdaki istemi Antigravity'ye kopyalayıp yapıştırın:

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

Antigravity bu istemi yürüttüğünde, KSA'yı ve yardımcı becerilerini yüklemek için terminalde uvx google-agents-cli setup komutunu çalıştırır. Ardından, yüklemeyi doğrulamak için agents-cli info komutunu çalıştırır ve yeni yüklenen alan becerilerini (ör. google-agents-cli-deploy ve google-agents-cli-workflow) doğrudan sohbette listeler.

Antigravity kullanıcıları için not: Bu codelab sırasında Antigravity, komutları yürütmeden veya kod yazmadan önce uygulama planları oluşturabilir ya da pop-up'lar gösterebilir. Antigravity'nin görevlere devam edebilmesi için bu planları veya pop-up'ları inceleyip onayladığınızdan emin olun.

Kota İpucu: Test veya geliştirme sırasında kotanız tükenirse Antigravity'deki modeli kullanılabilir başka bir modelle değiştirin.

4. Ajan projenizi oluşturma

Bulut ortamınız yapılandırıldıktan ve KSA becerileriniz yüklendikten sonra aracınız için yerel kod tabanı oluşturmaya hazırsınız demektir. Bu adımda, ADK 2.0 ile uyumlu, tamamen işlevsel bir Ambient Expense Agent prototipi oluşturmak için Antigravity'yi kullanırsınız.

Kaggle 5 Days of AI Agents kullanıcıları için not: 4. Gün için bu Vibecode Ambient Expense Agent Codelab'i başarıyla tamamladıysanız ve mevcut özel aracı kod tabanınızı dağıtmayı tercih ediyorsanız bu iskele oluşturma adımını atlayıp bir sonraki adıma geçebilirsiniz.

👉 Antigravity istemi:

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

Antigravity bu istemi yürüttüğünde, terminalde agents-cli scaffold create expense-agent --adk komutunu çalıştırmak için yeni yüklenen iskele becerilerinden yararlanır. Ardından, oluşturulan prototip kodunu doğrulayıp ayarlayarak expense-agent'nın $100 otomatik onay eşiğini ve Agent Development Kit (ADK) grafik iş akışındaki insan müdahalesiyle inceleme akışını doğru şekilde uyguladığından emin olur.

5. Üretim dağıtımına hazırlanma

Agent Runtime, üretimde yapay zeka aracılarını dağıtmanıza, yönetmenize ve ölçeklendirmenize olanak tanıyan, tümüyle yönetilen bir Google Cloud hizmetidir. Agent Runtime, oturum yönetimi, uzun süreli bellek ve güvenli kod yürütme korumalı alanları gibi özelliklerle durum bilgisi içeren bir ortam sunarak barındırma işlemlerinin karmaşıklığını yönetir.

Neden Agent Runtime'a dağıtmalısınız?

Antigravity ile yerel olarak aracı oluşturduğunuzda aracınız, localhost'ya karşı yerel makinenizde çalışır. Hızlı prototipleme için ideal olsa da yerel aracılar, dizüstü bilgisayarınızı kapattığınız anda çalışmayı durdurur.

Ajanınızı Agent Runtime'a dağıtmak, iş akışınızı tamamen yönetilen ve her zaman açık olan bir Google Cloud ortamına taşır. Bu, 7/24 etkin kalan güvenli bir canlı arka uç uç noktası oluşturur. Bir sonraki codelab'de, doğrudan bu bulut uç noktasına bağlanan bir web ön ucu oluşturacak ve böylece aracınıza herkese açık bir URL vereceksiniz.

Ayrıca Agent Runtime, özellikle yapay zeka aracıları için optimize edilmiş özel bir altyapı sunar. Bu altyapı, aşağıdakiler gibi yerleşik özellikler sağlar:

• Durumlu Yönetilen Yürütme: Oturum yönetimi ve uzun süreli bellek kalıcılığı, etkileşimli dönüşler boyunca yerleşiktir.
• Güvenli Korumalı Alan: Dinamik araç çağrılarını ve aracı tarafından oluşturulan kodu izole edilmiş ortamlarda güvenli bir şekilde yürütür.
• Kurumsal Gözlemlenebilirlik: Telemetri, doğrudan Cloud Trace ve Cloud Logging'e aktarılır.

Ajanınızı Agent Runtime'da barındırmak için yerel proje dizininizi üretim tanımlayıcıları, şemalar ve uç nokta sarmalayıcılarıyla geliştirmeniz gerekir.

👉 Antigravity istemi:

Scaffold the production deployment files for Agent Runtime.

Antigravity bu istemi yürüttüğünde, projenizin kök dizininde agents-cli scaffold enhance --deployment-target agent_runtime --yes komutunu çalıştırır. Bu komut, dizininizi tarar ve otomatik olarak şunları oluşturur:

• app/agent_runtime_app.py: Üretim düzeyinde hizmet sarmalayıcısı.
• deployment_metadata.json: Kaynakları başlatmak için Agent Runtime tarafından kullanılan düzen şeması.

app/agent.py'daki temel aracı mantığınız tamamen değişmeden kalır ve korunur.

6. Paketleme ve Yerel Doğrulama

Buluta yükleme işlemini başlatmadan önce paketlerinizi kilitleyin ve olası bağımlılık çakışmalarını belirlemek için yerel bir deneme çalıştırması yapın.

👉 Antigravity istemi:

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

Antigravity bu istemi yürüttüğünde, bulutta tutarlı kitaplık sürümleri sağlamak için önce terminalde uv lock komutunu çalıştırarak deterministik bir kilit dosyası oluşturur. Ardından, yapılandırmanın geçerliliğini doğrulamak ve bulut kaynaklarını sağlamadan dağıtım adımlarını önizlemek için agents-cli deploy --dry-run komutunu yürütür. Tüm dosyaların ve ayarların doğru olduğunu onaylamak için terminaldeki deneme yayını çıkışını inceleyebilirsiniz.

7. Agent Runtime'a dağıtma

Ambient Expense Agent'ınızı Agent Runtime'a dağıtın.

👉 Antigravity istemi:

Deploy this agent to Agent Runtime.

Antigravity bu istemi yürüttüğünde google-agents-cli-deploy becerisini etkinleştirir ve agents-cli deploy --project YOUR_PROJECT_ID --region us-west1 komutunu çalıştırır. Paketleme, yükleme ve Agent Runtime sağlama süreci genellikle 5-10 dakika sürer. Antigravity, terminaldeki dağıtım ilerleme durumunu izler ve tamamlandığında canlı uç nokta URL'nizi gösterir.

💡 Profesyonel İpucu (Zaman Aşımı Pencerelerini Yönetme): Uzun dağıtımlar sırasında terminalinizin kilitlenmesini istemiyorsanız Antigravity'ye dağıtımı eşzamansız olarak başlatmak için --no-wait işaretini kullanmasını ve daha sonra agents-cli deploy --status kullanarak ilerlemeyi kontrol etmesini söyleyebilirsiniz.

Aracınızı dağıtırken sorun yaşıyorsanız farklı bir bölge kullanmayı deneyin. Google Cloud Bölge Seçici aracı, gecikme süresi, fiyat ve karbon ayak izine göre projeniz için en iyi bölgeyi belirlemenize yardımcı olabilir.

8. Temsilcinizi test etme

Temsilciniz dağıtıldıktan sonra küçük harcamaları otomatik olarak onayladığını ve daha büyük harcamalar için insan müdahalesiyle doğrulama işlemi yapılması gerektiğini doğru şekilde işaretlediğini doğrulayabilirsiniz.

👉 Antigravity'den canlı olarak dağıtılan motoru doğrulaması için istemde bulunun:

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

Not: Antigravity, bu test istemini canlı uç noktanızda çalıştırırken herhangi bir dağıtım veya yürütme hatasıyla karşılaşırsa sorunu otomatik olarak ayıklamaya, gerekli kod düzeltmelerini uygulamaya ve aracıyı sizin için yeniden dağıtmaya çalışır.

Alternatif olarak, Cloud Console Playground önizlemesini kullanarak aracınızı manuel olarak test edebilirsiniz. Playground'u açmak için:

1. Google Cloud Console'da gezinme menüsünü kullanarak Agent Platform > Deployments'ı (Dağıtımlar) seçin.
2. Dağıtımlar listesinden dağıtılan aracınızı seçin.
3. Etkileşimli test sohbeti arayüzünü açmak için Playground düğmesini tıklayın.

👉 Otomatik Onay(<$100) özelliğini test etmek için aşağıdaki JSON yükünü sohbet kutusuna yapıştırın:

{"data": {"amount": 50.0, "submitter": "[e-mail]", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

Durumu "onaylandı" olan auto_approve düğümünün çıkışını gösteren bir JSON yanıtı alırsınız.

👉 İnsan etkileşimli (HITL) akışı test etmek için aşağıdaki JSON yükünü yapıştırın.

{"data": {"amount": 150.0, "submitter": "[e-mail]", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

Bu işlem, review_agent'ı tetikler, uyarıyı yayınlar ve ardından yürütmeyi duraklatarak onay isteyen bir RequestInput (insan müdahalesi) oluşturur.

9. Üretim aracınızı izleme ve gözlemleme

Agent Runtime ile telemetri otomatik olarak bağlanır. Her etkileşim, model çağrısı ve araç yürütme işlemi, projenize gerçek zamanlı günlükler ve aralıklar olarak aktarılır.

1. İzlemeleri İnceleme: Canlı işlem haritalarını denetlemek, gecikmeleri modellemek ve araç yürütme adımlarını incelemek için Cloud Trace Console'u açın.
2. Denetleme Günlükleri: Gerçek zamanlı standart çıkışı ve teşhis yığını izlerini incelemek için Cloud Logging'i kullanın.

3. Analytics'i toplama: İskele oluşturma sırasında --bq-analytics işareti etkinleştirildiyse onay oranlarını ve sohbet dönüşü trendlerini görüntülemek için günlüklerinizi BigQuery'de SQL kullanarak sorgulayın.

Aşağıdaki SQL sorgusu, onay oranlarını hesaplamayla ilgili bir örnek sunmaktadır. Antigravity'den bu sorguyu projenize ve BigQuery veri kümenize göre özelleştirmesini isteyebilirsiniz:

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. (İsteğe bağlı) Temsilci Kayıt Defteri'nde kaydı doğrulama

Kuruluşunuzdaki diğer hizmetlerin, geliştiricilerin veya aracıların harcama aracınızı güvenli bir şekilde keşfedip kullanabilmesi için aracınızın kurumsal Aracı Kayıt Defteri'ne (Gemini Enterprise) kaydedilmesi gerekir.

Ajanınızı Agent Runtime'a dağıttığınız için Agent Registry'ye otomatik olarak kaydedilir. Aracı çalışma zamanında aracınızla ilgili gelecekte yapılacak güncellemeler veya silme işlemleri de otomatik olarak Aracı Kayıt Defteri ile senkronize edilir.

👉 Antigravity'den, aracınızın otomatik kaydını doğrulamasını isteyin:

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

Antigravity bu istemi yürüttüğünde terminalde agents-cli publish gemini-enterprise --list komutunu çalıştırır. Bu işlem, Ajan Kayıt Defteri'ni sorgular ve projenizdeki tüm kayıtlı Gemini Enterprise ajanlarını listeler. Böylece, Ambient Expense Agent'ınızın etkin olduğunu ve kuruluşunuz genelinde bulunabileceğini doğrulayabilirsiniz.

11. Temizleme

Kaggle Kursu Katılımcıları: Bu laboratuvarı Kaggle'ın 5-Day AI Agents kursu kapsamında tamamlıyorsanız ve ön uç istemcisi ile Pub/Sub entegrasyonunu oluşturmak için bir sonraki laboratuvara (Vibecode and Deploy a Frontend for an ADK Agent) geçmeyi planlıyorsanız dağıtılan aracınızı silmeyin. Sonraki laboratuvar için bu etkin bulut altyapısına ihtiyacınız olacak.

Google Cloud hesabınızda sürekli olarak ücretlendirilmemek için işiniz bittiğinde dağıtılan kaynaklarınızı kapatıp temizlemeniz gerekir.

👉 Antigravity istemi:

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

Antigravity bu istemi yürüttüğünde tüm kaynak temizleme sürecini otomatikleştirir:

1. Dağıtılan Aracıyı Silme: Uzak aracı çalışma zamanı kimliğinizi almak için deployment_metadata.json okunur, ardından canlı motor örneği Vertex AI'dan programatik olarak silinir.
2. Yerel Çalışma Alanını Temizle: Eski deployment_metadata.json dosyasını proje kökünüzden kaldırır.
3. Artifact Registry'yi temizleme: Oluşturulan container görüntülerini Artifact Registry'den kaldırarak bulut depolama alanını boşaltmak için gcloud artifacts docker images delete komutunu yürütür.

12. Tebrikler

Tebrikler! Google Cloud'da üretime hazır bir Ambient Expense Agent'ı başarıyla dağıtıp doğruladınız.

Öğrendikleriniz

• Google Cloud kurulumu: Proje kimlik bilgilerini yapılandırdı ve gerekli platform API'lerini etkinleştirdi.
• Araçlar ve Beceriler: agents-cli yüklendi ve ADK yardımcı becerileri Antigravity'ye yüklendi.
• Üretim İskelesi: ADK 2.0 aracısı için oluşturulan Agent Runtime iskelesi.
• Yerel Doğrulama: Belirleyici kilit dosyaları (uv lock) oluşturuldu ve deneme kontrolleri yapıldı.
• Cloud Deployment: Aracınızı yönetilen Agent Runtime altyapısında canlı olarak barındırın.
• Gözlemlenebilirlik ve Analiz: Cloud Trace'te izlenen yürütme ve BigQuery'de analiz edilen telemetri.
• Kuruluş Bulma: Kuruluşun Agent Registry'ye otomatik olarak kaydedilmesi doğrulanır.

Sırada ne var?

• BigQuery Analytics'i kullanma: Onay oranlarını ve zaman içindeki etkileşim dönüşü trendlerini analiz etmek için BigQuery'de aracınızın telemetri günlüklerini sorgulayın.
• Vibe to Live Codelab: Cloud Run'da bir ön uç istemcisi geliştirmek ve bunu doğrudan canlı Agent Runtime arka uç uç noktanıza bağlamak için Google Antigravity'yi kullanın.

Kaggle 5-Day AI Agents rozetinizi kazanın 🎉

Bu laboratuvarı Kaggle'ın 5-Day AI Agents: Intensive Vibe Coding Course with Google (5 Günde Yapay Zeka Ajanları: Google ile Yoğun Vibe Kodlama Kursu) kapsamında mı tamamladınız? Tamamlama rozetinizi talep edin:

5 Günlük Yapay Zeka Temsilcileri rozetini alma

Referanslar

• Agent Development Kit (ADK) Dokümanları
• Gemini Enterprise Ajan Platformu Çalışma Zamanları
• Agents CLI (agents-cli) Referans Kılavuzu
• Gemini Enterprise Ajan Kayıt Defteri'ne Genel Bakış
• Google Cloud Trace Belgeleri