Microsoft Agent Framework’e Azure Cosmos DB belleği
Microsoft Agent Framework için sunulan yeni önizleme entegrasyonu, Azure Cosmos DB desteğiyle ajanların oturumlar arasında kalıcı bellek kullanmasını sağlıyor. Python paketi agent-framework-azure-cosmos-memory, konuşma turlarını saklıyor, kalıcı anılar çıkarıyor ve sonraki konuşmalarda ilgili bilgileri, özetleri ve kullanıcı profillerini yeniden kullanabiliyor.
Entegrasyon, Microsoft Agent Framework’ün bağlam sağlayıcıları (context providers) modelini kullanıyor. Uygulamanın ayrıca bir bellek arama akışı kurması veya ajanın bir bellek aracını çağırmaya karar vermesi gerekmiyor. Bellek, her ajan çalıştırmasının yaşam döngüsüne dahil ediliyor.
CosmosMemoryContextProvider nasıl çalışıyor?
Agent Framework’te bir ContextProvider, her ajan çağrısından önce ve sonra çalışabilir. Sağlayıcı, model çalıştırılmadan önce bağlama bilgi ekleyebilir, işlem tamamlandıktan sonra da yeni sonuçlara tepki verebilir. Bu yapı, bellek özelliklerini genişletmek için uygun bir nokta sunuyor.
CosmosMemoryContextProvider yaşam döngüsünün iki aşamasını da kullanıyor:
- Çalıştırma öncesinde: Gelen mesaja uygun anıları arıyor ve bunları modelin bağlamına ekliyor.
- Çalıştırma sonrasında: Yeni konuşma turlarını saklıyor. Azure Cosmos DB Agent Memory Toolkit arka planda gerçekleri çıkarıyor, özetler üretiyor ve kullanıcı profilini güncelliyor.
Agent Framework ajan döngüsünü ve sağlayıcının çağrılmasını yönetiyor. Sağlayıcı da bu yaşam döngüsünü Azure Cosmos DB Agent Memory Toolkit’e uyarlıyor. Depolama modeliyle bellek işleme hattını Toolkit yönetiyor. Azure Cosmos DB for NoSQL konuşma turlarını ve türetilen anıları saklıyor, aynı veritabanı üzerinden vektör, tam metin ve hibrit aramayı da destekliyor.
Python ajanına kalıcı bellek ekleme
Önizleme entegrasyonu, Agent Framework Foundry sağlayıcısıyla birlikte kurulabiliyor:
pip install --pre agent-framework-azure-cosmos-memory agent-framework-foundryÖrnekte Azure kaynakları için COSMOS_ENDPOINT, FOUNDRY_ENDPOINT, EMBEDDING_MODEL ve CHAT_MODEL ortam değişkenleri kullanılıyor. Daha sonra bellek sağlayıcısı oluşturuluyor ve ajanın context_providers koleksiyonuna ekleniyor.
import asyncio
import os
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_azure_cosmos_memory import CosmosMemoryContextProvider
from azure.identity.aio import DefaultAzureCredential
async def main() -> None:
credential = DefaultAzureCredential()
memory = CosmosMemoryContextProvider(
cosmos_endpoint=os.environ["COSMOS_ENDPOINT"],
cosmos_database=os.getenv("COSMOS_DATABASE", "ai_memory"),
foundry_endpoint=os.environ["FOUNDRY_ENDPOINT"],
embedding_model=os.environ["EMBEDDING_MODEL"],
chat_model=os.environ["CHAT_MODEL"],
credential=credential,
)
agent = Agent(
client=FoundryChatClient(
project_endpoint=os.environ["FOUNDRY_ENDPOINT"],
model=os.environ["CHAT_MODEL"],
credential=credential,
),
instructions="You are a helpful assistant with long-term memory.",
context_providers=[memory],
)
async with credential, memory:
first_session = agent.create_session()
first_session.state.setdefault(memory.source_id, {})["user_id"] = "alice"
await agent.run(
"I love hiking and I'm allergic to peanuts.",
session=first_session,
)
# Wait for background extraction so this immediate demo is deterministic.
await memory.flush()
# A new session for the same user can recall memories from the first one.
second_session = agent.create_session()
second_session.state.setdefault(memory.source_id, {})["user_id"] = "alice"
reply = await agent.run(
"What should I pack for a trail lunch?",
session=second_session,
)
print(reply.text)
asyncio.run(main())Örnekte iki ayrı oturum aynı user_id değeriyle ilişkilendiriliyor. İlk oturumda verilen bilgiler işlendiğinde ikinci oturum bu bilgilerden yararlanabiliyor. Sağlayıcının asenkron bağlamı kapatılırken devam eden arka plan çıkarma işlemleri tamamlanıyor. Örnekteki flush() çağrısı da arka plan çıkarımının bitmesini bekliyor.
Gerçek bir uygulamada user_id değerinin istekten doğrudan alınması yerine kimliği doğrulanmış kullanıcıdan türetilmesi gerekiyor. Sabit bir kullanıcı kimliği sağlanmazsa sağlayıcı, oturumlar arasında bilgi taşımak yerine oturum kapsamındaki belleği kullanıyor.
Örnekteki Foundry uç noktası, bellek Toolkit’inin çıkarma ve gömme modelleriyle sohbet ajanını destekliyor. DefaultAzureCredential yerel geliştirmede az login ile, üretim dağıtımlarında ise yönetilen kimlikle kullanılabiliyor. Bu nedenle anahtarları doğrudan kod içine koymak gerekmiyor.
Entegrasyonun sağladığı bellek özellikleri
CosmosMemoryContextProvider, Agent Framework geliştiricilerine tek bir bileştirilebilir sağlayıcıyla şu yetenekleri sunuyor:
- Oturumlar arası hatırlama: Kalıcı bir kullanıcı kimliği kapsamında önceki konuşmalardan bilgi çağırma.
- Türetilmiş bellek: Gerçekler, prosedürel ve episodik anılar, konu özetleri ve kullanıcı profilleri oluşturma.
- Hibrit arama: Azure Cosmos DB’nin vektör ve tam metin arama özelliklerini birlikte kullanma.
- Arka plan çıkarımı: Bellek işleme sürecini ajanın yanıt yolunu engellemeden yürütme.
- Etki alanına özel çıkarım: Varsayılan bellek kuralları yeterli olmadığında özel Prompty şablonlarından yararlanma.
Bu yaklaşımda görevler ayrılıyor: Agent Framework ajanı çalıştırıyor ve bağlamı birleştiriyor, Azure Cosmos DB ise uzun vadeli belleği saklıyor, işliyor ve geri getiriyor.
Önizleme durumu ve başlangıç kaynakları
agent-framework-azure-cosmos-memory şu anda yalnızca Python için sunuluyor. Paket ve API’ler genel kullanıma açılmadan önce değişebilir. Entegrasyonun mevcut biçimi bu nedenle önizleme kapsamı içinde değerlendirilmeli.
Başlangıç için Azure Cosmos DB ekibinin duyurusundaki ayrıntılı açıklama ve uygulama adımları incelenebilir. Temel kullanım ile etkileşimli sohbet örnekleri de çalıştırılabilir. Paket deposu, Agent Memory Toolkit ve Agent Framework bağlam sağlayıcıları hakkında daha fazla bilgi aşağıdaki kaynaklarda yer alıyor.
Kaynaklar ve İleri Okuma
- Microsoft Agent Framework için Azure Cosmos DB ile yerel bellek duyurusu
- Azure Cosmos DB Agent Memory Toolkit duyurusu
- agent-framework-azure-cosmos-memory paketi
- Temel kullanım örneği
- Etkileşimli sohbet örneği
- Agent Framework bağlam sağlayıcıları
- Bağlam sağlayıcısı entegrasyonları
- Agent Memory Toolkit
- Microsoft Agent Framework için Cosmos DB Tabanlı Bellek
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.
2 comments