AI Ajanları Cosmos DB vNext Emülatörüyle Buluşuyor
Azure Cosmos DB vNext emülatörünü yerelde kullananlar için tanıdık bir döngü vardır: emülatörü başlat, bağlan, kaynakları oluştur, test verisini yükle, sorguları çalıştır ve sonuçları incele. Her adım tek başına basit görünse de asıl geliştirmeye başlamadan önce hatırı sayılır bir hazırlık yükü doğurur. AI kodlama ajanlarının bu döngüyü nasıl kısalttığını, Azure Cosmos DB Shell ve cosmosdb-emulator-vnext Agent Skill üzerinden inceleyelim.
Ajanlar emülatörle nasıl çalışır?
Emülatör, veritabanları, kapsayıcılar ve öğeler üzerinde çalışmayı sağlayan açık kaynaklı CLI olan Azure Cosmos DB Shell‘i barındırıyor. Shell doğrudan emülatör konteynerinin içinde çalışıyor; yerel uç noktayı ve bilinen anahtarı arka planda yönetiyor. Bu da geliştiriciye betiklenebilir, doğrudan bir arayüz sunuyor.
CLI’lar ajan iş akışlarına oldukça uygun bir arayüz tipidir: işlemleri açık komutlar hâlinde ortaya koyar ve ajanın inceleyebileceği çıktılar üretir. Bir ajan yardım (help) metinleri üzerinden komutları keşfedebilir, komutları etkileşimsiz çalıştırabilir, hatalara yanıt verebilir ve çıktıyı bir sonraki adıma karar vermek için kullanabilir. Azure Cosmos DB Shell bu modeli yerel emülatöre taşıyor. Örneğin bir ajan, emülatör konteyneri içinde Shell’i şu şekilde etkileşimsiz olarak çalıştırabilir:
docker exec <emulator-container> cosmoshell.sh -c '<command>'Bu yaklaşım GitHub Copilot CLI, Codex veya Claude Code gibi AI kodlama ajanlarına emülatörle çalışmak için doğrudan bir yol açıyor. Geliştirici artık görevi bir dizi kabuk komutuna çevirmek yerine, istediği sonucu tarif ediyor.
Agent Skill neden gerekli?
Komutlara erişim sadece başlangıç noktası. Ajanın, emülatörü bulmak, uygun komutları seçmek, güvenlik sınırlarına saygı göstermek ve yaptığı işi doğrulamak için bir çalışma yordamına ihtiyacı var. İşte Agent Skill bu boşluğu dolduruyor: göreve özgü rehberliği paketleyerek farklı istekler ve oturumlar arasında yeniden kullanılabilir hâle getiriyor.
Yerel emülatör için hazırlanan cosmosdb-emulator-vnext skill’i; ajanın kaynakları incelemesine, veritabanı ve kapsayıcı oluşturmasına, test verisi yüklemesine ve sorguları Azure Cosmos DB Shell üzerinden çalıştırmasına yardımcı oluyor.
Prompt’tan test verisine: çok kiracılı bir örnek
Diyelim ki çok kiracılı (multi-tenant) bir sipariş işleme uygulaması geliştiriyorsunuz. Entegrasyon testleri için birden fazla kiracıya ait, siparişin farklı yaşam döngüsü aşamalarını kapsayan veriye ihtiyacınız var. Bu veriyi elle üretmek ve güncel tutmak hızla zahmetli hâle geliyor.
Bunun yerine, bir kodlama ajanına şu türden bir prompt verilebilir:
Çok kiracılı bir sipariş işleme uygulaması geliştiriyorum ve entegrasyon testleri için gerçekçi veriye ihtiyacım var. Yerel Cosmos DB emülatörümü, iki kiracıya ait; yeni, sevk edilmiş ve iptal edilmiş siparişlerin karışımından oluşan sentetik verilerle kur. Hazır olduğunda veriyi bana göster.
Kaynakta anlatılan denemede prompt, yerel emülatör çalışırken GitHub Copilot CLI ile test edilmiş. Ajan emülatörü bulmuş, dahili Azure Cosmos DB Shell’i kullanmış ve /tenantId ile bölümlenmiş bir Orders kapsayıcısını OrdersDB içinde oluşturmuş.
Ardından her iki kiracı için dengeli bir sentetik sipariş kümesi üretmiş. Her sipariş; müşteri bilgileri, iç içe kalem listeleri, zaman damgaları, sevkiyat bilgileri ve toplamları içeriyor. Duruma özgü alanlar da eklenmiş: sevk edilmiş siparişler için takip bilgisi, iptal edilenler için iptal nedeni gibi.
Kurulum özeti şu şekilde:
- Veritabanı: OrdersDB
- Kapsayıcı: Orders
- Bölüm anahtarı: /tenantId
- Oluşturulan sipariş sayısı: 12
Ajan veriyi doğrulamak için kapsayıcıyı sorgulamış. 12 siparişin 6’sı kaynak yazıda şu şekilde paylaşılıyor:
| Sipariş | Kiracı | Müşteri | Durum | Toplam |
|---|---|---|---|---|
| ord-a001 | tenant-alpha | Alice Navarro | new | $145.96 |
| ord-a003 | tenant-alpha | Clara Mendes | shipped | $361.99 |
| ord-a005 | tenant-alpha | Elena Vasquez | cancelled | $129.00 |
| ord-b001 | tenant-beta | Grace Osei | new | $74.97 |
| ord-b003 | tenant-beta | Ingrid Sorensen | shipped | $249.00 |
| ord-b006 | tenant-beta | Luca Ferrari | cancelled | $101.97 |
İstek açık uçlu olduğundan isimler, değerler ve belge sayıları çalıştırmadan çalıştırmaya değişebilir. Fakat iş akışı aynı kalıyor: kaynakları oluştur, veriyi yükle, sonra da sorgulayarak doğrula. Kaydedilmiş siparişlerin gösterilmesi, verinin gerçekten emülatörde ve uygulama tarafından kullanılmaya hazır olduğunu teyit ediyor.
Bu noktada geliştirici, seed betiği yazmadan veya belgeleri elle birleştirmeden, kalıcı ve bölümlenmiş test verisine sahip hâle geliyor.
Neden Agent Skill kullanmak avantajlı?
Dikkat edilirse yukarıdaki prompt, uygulamanın ihtiyacını tarif ediyor; çalışma yordamını değil. Emülatörün nasıl bulunacağından, dahili shell’in nasıl kullanılacağından, etkileşimsiz komut tercihinden veya değişikliklerin nasıl doğrulanacağından hiç söz etmiyor.
Elbette bu talimatların hepsi her prompt’a tek tek eklenebilir. Tek seferlik bir görev için bu çalışır, ancak aynı rehberliği tekrar tekrar yazmak zamanla yorucu olur; önemli bir kısıt unutulduğunda veya farklı ifade edildiğinde sonuçlar da farklılaşabilir.
Rehberliği global yönergelere taşımak tekrarı önler; ama bu kez emülatöre özgü bağlam, alakasız görevlerde de devrede kalır. Agent Skill her iki dezavantajı da ortadan kaldırıyor. cosmosdb-emulator-vnext skill’i, emülatörle ilgili rehberliği tek yerde toplayıp yalnızca ilgili bir istek algılandığında devreye sokuyor. Markdown dosyası olarak paylaşılabiliyor, gözden geçirilebiliyor, test edilebiliyor, sürümlenebiliyor ve ekip kurallarına ya da test iş akışına göre uyarlanabiliyor.
Azure Cosmos DB Agent Kit ile ilişkisi
Aynı yaklaşım Azure Cosmos DB geliştirmesinin diğer alanlarına da uzanıyor. Azure Cosmos DB ekibi, AI kodlama ajanları için tasarlanmış skill koleksiyonu olan Azure Cosmos DB Agent Kit‘i sürdürüyor. Bu kit; veri modelleme, bölüm anahtarı tasarımı, sorgu optimizasyonu, SDK kullanımı, indeksleme, throughput, güvenlik ve izleme konularında rehberlik içeriyor. Emülatör skill’inin ileride Agent Kit içinde diğer skill’lerle birlikte tutulması da gündemde.
Kendiniz denemek isterseniz
Agent Skills, aynı skill’i farklı kodlama ajanları arasında yeniden kullanmanıza izin veren hafif ve açık bir standart. Skill’i yükleyip yerel emülatörünüzle çalışmaya başlamak için kaynakta verilen komut şu:
npx skills add abhirockzz/cosmosdb-vnext-emulator-skillArdından yukarıdaki sipariş prompt’unu çalıştırarak ilk test veri kümenizi oluşturabilir; oradan uygulamanızın ihtiyaç duyduğu veri ve iş akışlarına göre isteği uyarlayabilirsiniz. Yerel emülatör, Azure Cosmos DB Shell ve skill birlikte; kurulum işini tekrarlanabilir kıldığı gibi işin nasıl yapıldığını da gizlemiyor. Geliştirici ne tür bir veriye ihtiyaç duyduğunu tarif ediyor; ajan komutları açıkça çalıştırıyor, sonucu doğruluyor ve incelenebilir bir çalışma izi bırakıyor.
Kaynaklar ve İleri Okuma
- Orijinal yazı: AI agents, meet the Azure Cosmos DB vNext emulator (Abhishek Gupta, DevBlogs)
- Azure Cosmos DB Linux Emulator (Microsoft Learn)
- cosmosdb-vnext-emulator-skill (GitHub)
- Azure Cosmos DB Agent Kit (GitHub)
- Agent Skills
- GitHub Copilot CLI dokümantasyonu
- Azure Cosmos DB vNext Emulator: Yerelde Gerçek Gibi Test Etmek
- Azure Cosmos DB Shell Public Preview: CLI’a AI Geldi
- Copilot Coding Agent ile 10 Ay: Kodun Kalbinde Yapay Zekâ Gerçekten İşe Yarıyor mu?
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
4 comments