Azure Blob Storage ile Deep Agents’a Kalıcı Dosya Sistemi
LangChain Deep Agents ile kurulan ajanların ürettiği dosyalar, süreç sonlandığında kaybolmak zorunda değil. AzureBlobBackend, Deep Agents’ın sanal dosya sistemini Azure Blob Storage üzerine taşıyor; böylece ajan çalışmaları süreçler arasında kalıcı oluyor, farklı ajanlar arasında paylaşılabiliyor ve Azure’un güvenlik ile veri yönetimi araçlarıyla yönetilebiliyor.
Deep Agents’ta dosya sistemi ne işe yarıyor
LangChain Deep Agents, LLM tabanlı ajanlar ve çok adımlı iş akışları için açık kaynaklı bir “harness”, yani çalıştırma iskeleti. Model tek başına akıl yürütüp yanıt üretebilir ama zaman içinde anlamlı iş çıkarması için doğru bağlamı getirecek, eylemleri yürütecek ve işi adımlara bölecek bir çerçeve gerekiyor. Deep Agents bu yapıyı planlama, bağlam yönetimi, sanal dosya sistemi, bellek ve beceriler (skills), uzmanlaşmış alt ajanlar ve insan onay noktaları üzerinden kuruyor.
Dosya sistemi bu bileşenler içinde en pratik soyutlamalardan biri. Ajan dosyaları listeler, arar, yalnızca o anki görev için gerekli olanı okur, çıktıları günceller, not tutar ve çalışmasını alt ajanlarla paylaşır. Dosya sistemi böylece hem bir çalışma alanı hem de uzun soluklu görevler için harici bellek oluyor. Deep Agents bu deseni listeleme, arama, okuma, yazma ve düzenleme araçlarıyla dışa açıyor.
Bulutta ölçekli çalışan ajanlarda her ajan için geleneksel bir dosya sistemi hazırlamak ve yaşam döngüsünü yönetmek ek altyapı yükü demek. Bu yükü azaltmak için LangChain ile Azure Storage ekipleri AzureBlobBackend‘i birlikte geliştirdi. Ajan ls, read_file, write_file, edit_file, glob ve grep gibi tanıdık araçlarla çalışmaya devam ederken altta dayanıklı ve esnek depolamayı Blob Storage sağlıyor. Entegrasyon langchain-azure-storage paketi üzerinden Public Preview aşamasında.
Blob Storage tabanlı dosya sisteminin sağladıkları
- Ajanın davranışını şekillendiren dosyalar, yani talimatlar, beceri kütüphaneleri, günlükler, bellek ve dışarı taşınan bağlam, oturumlar arasında korunuyor. Ajanlar tekrar eden çalıştırmalarda bu dosyaları okuyup güncelleyerek kazanılan deneyimi saklayan geri besleme döngüleri kurabiliyor.
- Blob container’ları, Azure rol tabanlı erişim denetimiyle (RBAC) güvenceye alınabilen erişim sınırları sunuyor; tanıdık blob yolları da paylaşılan çıktıları düzenli tutuyor. Birden fazla ajan aynı dosya sistemi üzerinde çalışırken erişim kapsamı ajan ajan ayarlanabiliyor.
- Kurumsal doküman koleksiyonlarında büyük havuzlar dayanıklı ve esnek depolamada durabiliyor, birden fazla ajan aynı korpusa worker’a bağlı yerel disklere bağımlı kalmadan erişebiliyor.
- Geliştiriciler ajanın oluşturduğu dosyaları Azure portal, Azure Storage Explorer ya da yetkili diğer uygulamalarla inceleyebiliyor, bağımsız işleme çalıştırabiliyor. Erişim denetimi, tanılama, saklama, kurtarma ve yaşam döngüsü yönetimi ajandan bağımsız olarak kullanılabiliyor.
Hızlı başlangıç: container, yetki ve kurulum
İlk adım, ajanın dosya sistemi olarak kullanılacak bir storage hesabı ve blob container seçmek. Mevcut bir container kullanılabilir ya da Azure portal’da storage hesabı açılıp Data storage > Containers bölümünden + Container ile yenisi oluşturulabilir. Kaynak makalede örnek ad olarak agent-files kullanılıyor. Sonra https://<storage-account>.blob.core.windows.net biçimindeki Blob service endpoint adresini not etmeniz gerekiyor.
Ajanı çalıştıracak kimliğe container üzerinde Storage Blob Data Contributor rolü atanıyor. Yerel geliştirmede rolü kendi kullanıcı hesabınıza verip Azure CLI ile oturum açıyorsunuz:
az loginUygulama Azure üzerinde çalıştığında aynı rol managed identity veya workload identity’ye atanıyor. Dağıtılan uygulamanın bu durumda ne Azure CLI oturumuna ne de storage hesap anahtarlarına ihtiyacı oluyor.
Python 3.11 veya üzeri gerekiyor. Depolama entegrasyonu şu şekilde kuruluyor:
pip install -U "langchain-azure-storage[deepagents]"Deep Agents birden fazla model sağlayıcısını destekliyor; sağlayıcı seçimi ve kurulumu için Deep Agents quickstart belgesi yönlendirici. Kaynaktaki örnek openai:gpt-6-astra modelini kullanıyor, bu tercihte langchain-openai kurulup API anahtarı tanımlanıyor:
pip install -U langchain-openaiBash için:
export OPENAI_API_KEY="your-api-key"PowerShell için:
$env:OPENAI_API_KEY = "your-api-key"Backend’i ajana bağlamak
AzureBlobBackend, Blob service endpoint ve container adıyla oluşturulup create_deep_agent fonksiyonuna veriliyor. Varsayılan kimlik DefaultAzureCredential olduğu için aynı kod yerelde Azure CLI oturumuyla, dağıtımda Azure kimliğiyle çalışıyor.
from deepagents import create_deep_agent
from langchain_azure_storage.deepagents import AzureBlobBackend
backend = AzureBlobBackend(
account_url="https://<storage-account>.blob.core.windows.net",
container_name="agent-files",
)
agent = create_deep_agent(
model="openai:gpt-6-astra",
backend=backend,
)
agent.invoke(
{
"messages": [
{
"role": "user",
"content": "Create /hello.py with a Python hello world script.",
}
]
}
)Bu örnekte ajan write_file aracıyla hello.py dosyasını bir blob olarak oluşturuyor.
Çalışma alanını ikinci bir ajanla paylaşmak
Aynı backend nesnesiyle ikinci bir ajan oluşturulduğunda, önceki konuşma durumuna sahip olmasa bile aynı Blob tabanlı çalışma alanını görüyor:
another_agent = create_deep_agent(
model="openai:gpt-6-astra",
backend=backend,
)
result = another_agent.invoke(
{
"messages": [
{
"role": "user",
"content": "Read /hello.py and explain what the script does.",
}
]
}
)
print(result["messages"][-1].content)Her iki ajan da aynı backend’i, dolayısıyla aynı Blob destekli dosya sistemini kullandığı için çıktılarını paylaşılan bir alan üzerinden takas edebiliyor.
Çok ajanlı örnek: mortgage paketi işleme
Kaynakta tam bir uygulama deseni olarak mortgage (konut kredisi) paketi işleme örneği veriliyor. Örnekte bir koordinatör ile paket alımı, doküman sınıflandırma, olgu çıkarımı ve kredi değerlendirmesi için dört uzman Deep Agent var. Her dosyayı Blob Storage’a göndermek yerine CompositeBackend ile yalnızca kalıcı olması gereken uygulama verisi üç Blob konumuna yönlendiriliyor:
/source/: salt okunur mortgage paketi kanıtları/guidance/: salt okunurAGENTS.mdtalimatları ve uzman becerileri/output/: her çalıştırma için paket dizini, sınıflandırma, çıkarılan olgular ve karar
source_backend = AzureBlobBackend(
account_url=account_url,
container_name="mortgage-packets",
prefix="MORT-2026-0042/",
)
guidance_backend = AzureBlobBackend(
account_url=account_url,
container_name="mortgage-agent-context",
)
output_backend = AzureBlobBackend(
account_url=account_url,
container_name="mortgage-decisions",
prefix=f"MORT-2026-0042/{run_id}/",
)
backend = CompositeBackend(
default=StateBackend(),
routes={
"/source/": source_backend,
"/guidance/": guidance_backend,
"/output/": output_backend,
},
)StateBackend, dışarı taşınan araç sonuçları, konuşma geçmişi ve ara planlar gibi thread kapsamındaki çalışma dosyalarını ajan durumunda tutuyor. Açıkça tanımlanan Blob rotaları ise thread veya süreç sınırlarını aşması gereken dosyaları, yani kaynak kanıtları, yeniden kullanılabilir talimat ve becerileri, üretilen kararları kalıcı hale getiriyor.
Örnekte kaynak kanıtların ve yönlendirme dosyalarının değiştirilmesini engellemek için create_deep_agent fonksiyonuna FilesystemPermission kuralları veriliyor. Bu kurallar koordinatör ve alt ajanları için /source/** ile /guidance/** altındaki yazma işlemlerini reddediyor.
Kimlik doğrulama ve güvenlik önerileri
AzureBlobBackend varsayılan olarak DefaultAzureCredential kullanıyor, yerelde Azure CLI kimliğini, Azure’da mevcut managed identity veya workload identity’yi değerlendirebiliyor. Güvenlik politikanız yalnızca managed identity ile kimlik doğrulamayı zorunlu kılıyorsa ManagedIdentityCredential açıkça geçilebiliyor. Kimliğin container’a erişimi olması gerekiyor ve credential hiçbir zaman ajana veya modele açılmıyor.
import os
from azure.identity import ManagedIdentityCredential
from langchain_azure_storage.deepagents import AzureBlobBackend
# System-assigned identity:
credential = ManagedIdentityCredential()
# For a user-assigned identity, use this instead:
# credential = ManagedIdentityCredential(
# client_id=os.environ["AZURE_CLIENT_ID"],
# )
backend = AzureBlobBackend(
account_url="https://<storage-account>.blob.core.windows.net",
container_name="agent-files",
credential=credential,
)Kaynakta öne çıkan diğer öneriler şunlar:
- Yalnızca kalıcı yolları Blob’a yönlendirin. Bellek, beceriler, paylaşılan politikalar, kaynak dokümanlar ve nihai çıktılar gibi thread’ler arası dosyalar
AzureBlobBackend‘e gitmeli; ara planlar ve dışarı taşınan araç sonuçları gibi thread kapsamlı dosyalarStateBackend‘e. - İzolasyon için ayrı container kullanın. Ayrı erişim sınırı gereken her ajan, tenant veya iş yüküne kendi container’ını atayın.
- En az ayrıcalık ilkesini uygulayın. Rol atamasını ilgili container kapsamına daraltın; salt okunur akışlarda Storage Blob Data Reader, yalnızca yazma veya silme gerektiğinde Storage Blob Data Contributor verin.
- Kurtarma özelliklerini açın. Blob soft delete’i etkinleştirin, uygun durumlarda blob versioning kullanın.
- Yıkıcı araçları sınırlayın. Ajanın silme yeteneğine ihtiyacı yoksa
FilesystemMiddlewareiçindedeletearacını bırakmayın ya da çalışmadan önce insan onayı isteyin.
Backend ajana verileri üzerine yazabilen ve silebilen işlemler de açıyor. Depolamaya yazma yetkisi verdiğiniz herhangi bir otomatik sisteme gösterdiğiniz özeni burada da göstermek gerekiyor.
Nereden devam etmeli?
Deep Agents storage backend örnekleri; Blob tabanlı dosya sistemiyle temel ajan oluşturma, tek çalışma alanını iki ajan arasında paylaşma ve CompositeBackend ile kalıcı bellek, paylaşılan dosya sistemi ve alt ajanları birleştirme senaryolarını çalıştırılabilir biçimde içeriyor. LangChain backend’leri için Microsoft entegrasyon dokümantasyonunu inceleyip langchain-azure-storage kaynak kodunu gözden geçirebilir, mortgage işleme örneğini kendi verinizle kuracağınız çok ajanlı iş akışı için başlangıç noktası olarak kullanabilirsiniz. Geri bildirim ve diğer LangChain depolama entegrasyonu fikirleri GitHub issue’ları üzerinden paylaşılabiliyor.
Entegrasyon LangChain ve Azure Storage ekiplerinin ortak çalışmasıyla geliştirildi. Kaynak yazıda entegrasyonun yürütülmesi ve incelemesi için Kyle Knapp’a, uygulama ve test katkıları için Dariel Dato-on’a teşekkür ediliyor.
Kaynaklar ve İleri Okuma
- Using Azure Blob Storage as a durable filesystem for LangChain Deep Agents (Azure SDK Blog, Vishnu Charan TJ)
- LangChain Deep Agents genel bakış dokümantasyonu
- LangChain blog: Deep Agents mimarisi
- Deep Agents backend dokümantasyonu
- Deep Agents quickstart
- Deep Agents dosya sistemi izinleri
- langchain-azure-storage kaynak kodu (GitHub)
- langchain-azure-storage paketi (PyPI)
- Mortgage packet processing örneği (README)
- Azure Storage yerleşik RBAC rolleri
- Python SDK kimlik doğrulama zincirleri (DefaultAzureCredential)
- Deep Agents + Cosmos DB: Operasyonel Veride Plan-Eylem-Doğrulama
- Azure Storage API’larında Entra ID ve RBAC Dönemi
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.
Yorum gönder