Microsoft Agent Framework için Cosmos DB Tabanlı Bellek

⏱️ 6 dk okuma📅 25 Temmuz 2026👁️ görüntülenme

Microsoft Agent Framework’ün son sürümüyle birlikte, Azure Cosmos DB destekli kalıcı ajan belleğini tek bir nesne aracılığıyla ajanlarınıza bağlayabiliyorsunuz. Python için önizlemede yayınlanan agent-framework-azure-cosmos-memory paketiyle gelen CosmosMemoryContextProvider, konuşma turlarını depolayan, gerçekleri ve kullanıcı profillerini çıkaran ve bunları farklı thread ile oturumlar arasında hatırlatan bir yapıya kapı açıyor. Yani ajan döngüsünün etrafına özel bir orkestrasyon kodu yazmak zorunda kalmadan uzun vadeli bellek elde ediyorsunuz.

Context Provider Neden Önemli?

Pek çok ajan çerçevesi belleği sabit bir arayüz olarak sunar: depola ve getir. Microsoft Agent Framework ise daha genel bir yaklaşım benimsiyor ve sağlayıcıdan bağımsız bir context provider soyutlaması sunuyor. Bu soyutlama iki yaşam döngüsü kancasına dayanıyor:

before_run: Ajan çalışmadan önce bağlam enjekte eder.
after_run: Çalışma sonrası üretilen sonuçları yakalar.

Bu yapının en dikkat çekici yani, yalnızca belleğe özgü olmaması. Ajanın düşünmeden önce bilmesi gereken herhangi bir bilgiyi enjekte etmek ve sonrasında üretilen çıktılarla bir şeyler yapmak için temiz bir dikiş noktası sağlıyor. Cosmos DB destekli bellek de tam olarak bu genişletme noktasının üzerine, ajan döngüsünü sarmalayan bir katman yerine bir “drop-in” sağlayıcı olarak inşa edilmiş.

CosmosMemoryContextProvider pratikte iki iş yapıyor: gelen mesajla ilgili bağlamı Cosmos’ta arayıp modele veriyor; çalıştırma sonrasında yeni turları saklayıp arka planda gerçek çıkarımı, özet güncellemesi ve kullanıcı profili derlemesi yapılmasını sağlıyor.

Mimari Nasıl Kurgulanmış?

Sağlayıcı, aslında Agent Memory Toolkit üzerine oturmuş ince bir Agent Framework adaptörü. Agent Framework ajan döngüsünü ve context provider yaşam döngüsünü yönetiyor; toolkit ise Cosmos DB depolama modelinden ve ham turları gerçek, özet ve profile dönüştüren LLM boru hattından sorumlu. Bellek, kalıcı bir user_id (ve mevcut konuşma için thread_id) ile kapsamlandırılıyor; bu sayede hatırlama, yepyeni thread’lerde ve oturumlarda bile kullanıcıyı takip ediyor.

Turlar, gerçekler ve özetler Azure Cosmos DB for NoSQL’e JSON belgeleri olarak yazılıyor. Getirme işleminde ise Cosmos’ta yerleşik olan vektör, tam metin ve hibrit arama kullanılıyor. Yani ayrı bir vektör deposu kurmaya veya senkron tutmaya gerek kalmıyor.

İnteraktif Örnek Üzerinden Adım Adım

Paketle birlikte gelen etkileşimli sohbet örneği tüm akışı uçtan uca gösteriyor.

1. Kurulum ve Yapılandırma

pip install agent-framework-azure-cosmos-memory agent-framework-foundry

Kimlik doğrulama DefaultAzureCredential üzerinden yapılıyor; yerelde az login, Azure’da yönetilen kimlik kullanılıyor ve API anahtarına ihtiyaç duyulmuyor. Örneği çalıştırmadan önce Cosmos DB hesabınızı, Foundry projenizi ve kullanacağınız sohbet ile embedding dağıtım adlarını ortam değişkenleriyle belirtiyorsunuz:

$env:COSMOS_ENDPOINT = "https://<your-account>.documents.azure.com:443/"
$env:FOUNDRY_ENDPOINT = "https://<your-project>.services.ai.azure.com"
$env:CHAT_MODEL = "gpt-5.4-mini"
$env:EMBEDDING_MODEL = "text-embedding-3-large"

2. Ajana Bellek Vermek

Bellek destekli bir ajan oluşturmak, sağlayıcıyı kurup ajana geçmekten ibaret. Tek bir Foundry uç noktası hem bellek boru hattını (embedding ve çıkarım) hem de sohbet ajanını besliyor:

import os
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import DefaultAzureCredential
from agent_framework_azure_cosmos_memory import CosmosMemoryContextProvider
def create_agent_with_memory():
foundry_endpoint = os.environ["FOUNDRY_ENDPOINT"]
credential = DefaultAzureCredential()
provider = CosmosMemoryContextProvider(
cosmos_endpoint=os.environ["COSMOS_ENDPOINT"],
cosmos_database=os.getenv("COSMOS_DATABASE", "ai_memory"),
foundry_endpoint=foundry_endpoint,
embedding_model=os.getenv("EMBEDDING_MODEL", "text-embedding-3-large"),
chat_model=os.getenv("CHAT_MODEL", "gpt-5.4-mini"),
credential=credential,
memory_types=["fact", "procedural", "episodic"],
)
agent = Agent(
client=FoundryChatClient(
project_endpoint=foundry_endpoint,
model=os.getenv("CHAT_MODEL", "gpt-5.4-mini"),
credential=credential,
),
name="Memory Assistant",
instructions="You are a helpful assistant with long-term memory.",
context_providers=[provider],
)
return agent, provider

Bellek açısından tek kritik satır context_providers=[provider]. Bundan sonra her ajan çalışması etrafında before_run ve after_run otomatik olarak tetikleniyor.

3. Belleği Kullanıcıya Bağlamak

Oturumlar arası kalıcı bellek için sabit bir kullanıcı kimliği gerekiyor. Bu kimliği sağlayıcı kapsamlı oturum durumunda belirlediğinizde, aynı kullanıcı için açılan yeni bir thread bile önceki bilgileri hatırlamayı sürdürüyor:

def new_session(agent, provider, user_id):
session = agent.create_session()
session.state.setdefault(provider.source_id, {})["user_id"] = user_id
return session

4. Belleğin Çalıştığını Görmek

Sağlayıcının async context’ine girerek arka plandaki çıkarımın çıkışta düzgünce boşaltılmasını sağlıyorsunuz; ardından ajana kalıcı bir bilgi veriyor, sonra yeni bir thread açıp geri çağırma istiyorsunuz:

agent, provider = create_agent_with_memory()
async with provider:
session = new_session(agent, provider, user_id="alice")
await agent.run("I love hiking and I'm allergic to peanuts.", session=session)
session = new_session(agent, provider, user_id="alice")
reply = await agent.run("What should we pack for a trail lunch?", session=session)
print(reply.text)

İkinci thread’in geçmiş mesajı olmamasına rağmen ajan, Alice’in yürüyüş sevdiğini ve fıstık alerjisi olduğunu hatırlıyor ve fıstıksız bir yürüyüş öğle yemeği planlıyor. Bu hatırlama tamamen sağlayıcının işi: before_run içinde çıkarılmış gerçekleri arıyor ve profili bağlam olarak enjekte ediyor; ilk turun after_run aşamasında ise turu saklayıp toolkit’in kalıcı gerçekleri çıkarmasına izin veriyor.

Etkileşimli örnek bu akışı basit bir REPL ile birkaç komut etrafında sarıyor: /new aynı kullanıcı için yeni bir thread açar (bellek taşınır), /user farklı bir kullanıcıya geçmenizi sağlar (bellekler yalıtılır), /quit çıkar.

Ajanın Neyi Hatırlayacağını Özelleştirmek

Varsayılan çıkarım kılavuzu genel amaçlıdır: hemen her asistana uygulanabilecek gerçekleri, prosedürel tercihleri ve epizodik deneyimleri çekip alır. Ancak “neyin hatırlanmaya değer olduğu” çoğunlukla alana özgüdür. Bir kod asistanı mimari kararları ve dil tercihlerini; bir seyahat asistanı koltuk ve diyet tercihlerini; bir destek botu hesap seviyesini ve geçmiş vakaları hatırlamalıdır. Varsayılanlarla bırakılan özelleşmiş bir ajan ya işine yarayacak şeyleri unutur ya da belleği gereksiz bilgilerle doldurur.

Sağlayıcı, bu iş için prompts_dir parametresini sunuyor. Bu parametreye bir Prompty şablonları dizini gösterdiğinizde bellek boru hattı, çıkarım ve özetleme yönlendirmelerini toolkit’in gömülü varsayılanları yerine oradan okuyor. En kritik dosya extract_memories.prompty. Bu şablon, modelin her turdan neyi çekeceğine ve nasıl sınıflandıracağına karar verdiği kılavuzu tanımlıyor. Şablonun girişleri ile JSON çıktı şemasını olduğu gibi bırakıp aradaki yönergeleri kendi alanınıza göre yeniden yazıyorsunuz.

interactive_chat_custom_extraction.py örneği, çalışma zamanında bir yönlendirme dizini oluşturup (gömülü şablonları kopyalayıp kod odaklı bir extract_memories.prompty ile değiştirerek) bunu sağlayıcıya geçiriyor:

provider = CosmosMemoryContextProvider(
cosmos_endpoint=os.environ["COSMOS_ENDPOINT"],
foundry_endpoint=os.environ["FOUNDRY_ENDPOINT"],
embedding_model=os.getenv("EMBEDDING_MODEL", "text-embedding-3-large"),
chat_model=os.getenv("CHAT_MODEL", "gpt-5.4-mini"),
credential=credential,
prompts_dir=prompts_dir,
)

Depolama, kapsamlandırma, getirme ve enjeksiyon tarafında hiçbir şey değişmiyor. Yalnızca boru hattının neyi kayda değer bulacağını değiştirmiş oluyorsunuz. Bu sayede bir kod asistanı, “ekip kullanıcı servisi için MySQL yerine PostgreSQL’i seçti” bilgisini veya “kod açıklanmadan önce daima gösterilecek” talimatını kalıcı olarak hatırlamaya başlarken küçük sohbetleri görmezden geliyor.

Sadece Demoya Değil Üretime Uygun Detaylar

Prototip aşamasını aşan ekipler için kaynakta öne çıkarılan birkaç nokta var:

Şeffaf çıkarım: Tür yazımı bloklamıyor; gerçek ve özet çıkarımı arka planda çalışıyor ve sağlayıcının context’i çıktığında otomatik olarak boşaltılıyor. Böylece istek yolu hızlı kalırken hiçbir şey kaybolmuyor.
Varsayılan olarak güvenli: Ajanın hatırladığı kullanıcı profili, saklanan konuşma içeriğinden üretiliyor. Bu yüzden sağlayıcı profili sıradan bir user-role mesajı olarak enjekte ediyor (asla sistem veya ajan yönergesi olarak değil) ve modele bunun talimat değil, güvenilmez referans bilgisi olduğunu açıkça belirten bir önek ekliyor. Bu yaklaşım, zehirlenmiş bir belleğin kalıcı bir direktife dönüşme riskini azaltıyor.
Modelleri siz seçersiniz: Sohbet ve embedding dağıtımları açıkça belirtiliyor; dağıtmadığınız bir modele sessizce yönlenmenize yol açacak varsayılan yok.

Başlamak İçin

Microsoft Agent Framework üzerinde ajanlar geliştiriyor ve onların hatırlamasını istiyorsanız entegrasyon artık tek nesnelik bir iş:

pip install agent-framework-azure-cosmos-memory agent-framework-foundry ile paketleri kurun.
Ajanınızın context_providers listesine bir CosmosMemoryContextProvider ekleyin.
Sağlayıcının oturum durumunda sabit bir user_id tanımlayın.

agent-framework-azure-cosmos-memory paketi şu anda önizleme aşamasında ve yalnızca Python destekliyor; genel kullanılabilirliğe kadar API’lerde değişiklik olabilir.

Kaynaklar ve İleri Okuma

Aşkın KILIÇYazar

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.

AZ-305AZ-104AZ-500AZ-400DP-203AI-102