Eve + Azure Cosmos DB: Unutmayan Ajan Nasıl Kurulur

Çoğu “AI ajan” demosu, terminal kapanınca her şeyi unutuyor. Küçük bir hobi işi için idare eder tabi. Ama gerçek hayatta — müşteri destek asistanı, içerik üreten bir yardımcı, ya da triage yapan bir ajan — iş orada kopuyor. Çünkü model tek başına iki şeyi veremiyor size: kalıcı hafıza, ve anlama göre doğru bağlamı geri çağırma işi.

Ben bu yazıda son birkaç haftadır kurcaladığım bir birleşimden bahsedeceğim: Vercel’in yeni eve platformu ile Azure Cosmos DB‘nın vektör aramasını yan yana koyunca ortaya çıkan “unutmayan ajan” düzeni. Kağıt üstünde basit dürüyor. Pratikte de fena değil — ama birkaç pürüz var, onlara da geleceğiz.

Hmm, bunu nasıl anlatsamdı…

Önce şu “eve” olayını anlayalım

Vercel AI SDK ile daha önce biraz oynadıysanız, eve size tanıdık geliyor. Aynı kafanın ajanlara bakışı bu; açık konuşayım, fikir baya iş görüyor: ajanınız bir klasördür. Graf DSL öğrenmiyorsunuz, orkestrasyon için ayrı bir sürü boilerplate de yazmıyorsunuz. Dosyaları koyuyorsunuz, eve onları çalışan bir ajana bağlıyor.

Peki bu pratikte ne demek? Kısaca şöyle. Evet.

• Araçlar dosyadır. agent/tools/ içine bir defineTool({...}) bırakıyorsunuz — model önü görüyor. Kayıt yok, wiring yok. Zod ile şemayı yazıyorsunuz, JSON schema’yı eve kendi çıkarıyor.
• Talimatlar Markdown. instructions.md sizin system prompt’unuz oluyor. Davranışı değiştirmek için kod kurcalamıyorsunuz, düzyazıyı elden geçiriyorsunuz. — ciddi fark yaratıyor
• Model seçimi size ait. AI SDK’nın provider ekosistemi üstünde çalışıyor. OpenAI, Anthropic ya da — bu yazıda olduğu gibi — Azure OpenAI. Fark etmiyor aslında.

Azure OpenAI bağlantısı da sanıldığı kadar karışık değil, hatta ilk bakışta insan “bu kadar mı?” diyor:

import { createAzure } from "@ai-sdk/azure";
import { defineAgent } from "eve";
const azure = createAzure({
baseURL: `${process.env.AZURE_OPENAI_ENDPOINT}/openai`,
apiKey: process.env.AZURE_OPENAI_API_KEY,
apiVersion: "preview",
});
export default defineAgent({
model: azure.chat("gpt-4.1"),
});

Lokal tarafta eve dev deyince terminal içinde interaktif bir sohbet açılıyor. eve build işe deploy edilebilir bir sunucu üretiyor. Ajan dış dünyayla — blog API’niz, Cosmos DB, ne varsa — sadece sizin tanımladığınız araçlar üzerinden konuşuyor. Yalın. Ben de yalınlığı seviyorum, o yüzden bu taraf hoşuma gitti — dürüst olayım, biraz hayal kırıklığı —

İşte tam da bu noktada devreye giriyor.

Eve’in kasten yapmadığı şey

Eve size kalıcılık vermiyor. Bu bilinçli bir tercih, yanı öyle “unutulmuş” bir eksik değil — dürüst olayım, biraz hayal kırıklığı —. Bir model çağrısı stateless kalıyor, süreç yeniden başladığında konuşma uçup gidiyor; işte tam bu boşluğu Azure Cosmos DB dolduruyor. Stateless bir ajanı gerçekten hatırlayan bir şeye çeviriyor.

Neden agent memory için Cosmos DB?

Ajan hafizasi, klasik veritabanı tarafında biraz tuhaf bir yük profili çıkarıyor. Bakın şimdi; bir yandan minicik kayıtlar yazıyorsunuz, öbür taraftan anahtarla değil, anlamla okuma yapıyorsunuz, üstelik bunlar hızlı da olmalı. Peki neden zor? Çünkü is global dagilimla karışınca is biraz sapıtıyor; ayrıca ayrı bir vektör veritabanı çalıştırmak istemiyorsanız, hani olay daha da uğraştırıcı hâle geliyor.

Hmm, bunu nasıl anlatsamdı…

Cosmos DB NoSQL bu senaryoya fena oturuyor:

• Tek haneli milisaniye point read’ler — id ve partition key sizdeyse, olay baya hızlı dönüyor.
• Native vektör arama — embeddingleri orada tutup VectorDistance() ile sorguluyorsunuz. Yanına Pinecone, Qdrant, Weaviate kurayım mi diye dusunmenize gerek kalmıyor.
• Native TTL — geçici hafizalari süre dolunca silmek için cron job kovalamıyorsunuz. Açık konuşayım, ben en çok buna seviniyorum.
• Global dağıtım, otomatik indeksleme, esnek schema; yanı ilk bakışta sade dürüyor ama pratikte bayağı iş görüyor.

“Ajan hafizasi ayrı bir vektör DB istemez, tek bir doküman deposu ister — yeter ki hem key-value hem semantik sorgulasin.” Sahada gördüğüm en sağlam ilke bu.

Mimarinin kaba iskeleti

Ajanı kurarken kafamda üç ayrı hafıza kutusu var, işin aslı bu kadar basit görünüyor ama değil:

1. Kısa vadeli — mevcut konuşma turunun bağlamı. TTL 1 saat mesela.
2. Episodik — kullanıcının geçmiş etkileşimleri, “geçen hafta ne konuşmuştuk” gibi. TTL 30-90 gün.
3. Semantik/Kalıcı — kullanıcı tercihleri, önemli notlar, blogun ton rehberi. TTL yok.

Her hafıza kaydı bir Cosmos DB dokümanı oluyor. İçinde metin, embedding vektörü, tip, timestamp ve partition key olarak userId var; bu son kısım kritik, çünkü partition seçimini ters yaparsanız sonra performans da şaşırıyor, fatura da (ikisi aynı anda), ben bunu birkaç projede acı acı gördüm.

Çok konuştum, örnekle göstereyim.

Evet.

Container tanımı ve vektör politikası

Cosmos DB’de vektör aramayı açmak için container oluştururken indexing policy ile vector embedding policy tanımlamanız gerekiyor. Bak şimdi, kağıt üstünde ufak bir ayar gibi dürüyor. Yanlış yazınca bütün kurgu dağılıyor; aşağıdaki yapı fena değil, hatta çoğu senaryoda gayet iş görüyor:

const containerDef = {
id: "agent-memory",
partitionKey: { paths: ["/userId"] },
vectorEmbeddingPolicy: {
vectorEmbeddings: [{
path: "/embedding",
dataType: "float32",
distanceFunction: "cosine",
dimensions: 1536
}]
},
indexingPolicy: {
vectorIndexes: [{ path: "/embedding", type: "quantizedFlat" }]
}
};

1536 boyut, text-embedding-3-small ile uyumlu. Daha büyük modellere geçerseniz bunu 3072’ye çekebilirsiniz; ama şey, burada küçük bir kıvrım var, depolama ve RU maliyeti de düz çizgi gibi artıyor, yanı “bir tık büyütelim” deyip geçmeyin.

Hmm, bunu nasıl anlatsamdı…

Aslında, Peki neden?

Bir “hafıza kaydet” aracı yazmak

Eve tarafında araç tanımı gerçekten üç dört satır. Zod şemasını yazıyorsunuz, handler’ı yazıyorsunuz, iş bitiyor gibi dürüyor. Ama işin aslı biraz daha kıvrımlı, çünkü ilk bakışta basit görünen bu parça, bütün hafıza akışının kapısını açıyor.

// agent/tools/remember.ts
import { defineTool } from "eve";
import { z } from "zod";
import { saveMemory } from "../lib/memory";
export default defineTool({
description: "Kullanıcı hakkında hatırlanması gereken bir bilgiyi kalıcı hafızaya yazar.",
input: z.object({
userId: z.string(),
content: z.string(),
type: z.enum(["preference", "fact", "context"])
}),
async execute({ userId, content, type }) {
await saveMemory({ userId, content, type });
return { ok: true };
}
});

saveMemory içinde önce embedding üretiyorsunuz (Azure OpenAI’nın embedding deployment’ından), sonra Cosmos’a upsert ediyorsunuz. Fazla süsü yok. Ben ilk denememde saçma bir şey yaptım — embedding çağrısını her yazımda tetikledim, RU tüketimi bir anda tavana vurdu; sonra ufak bir cache ekledim ve aynı içerik tekrar gelince embedding’i yeniden hesaplamamaya başladım. Basit ama baya iş görüyor.

Semantik hatırlama — asıl büyü burada

Recall tarafı biraz daha eğlenceli, hatta ilk gördüğümde “bu kadar mı?” dedirtti (ki bu çoğu kişinin gözünden kaçıyor). Kullanıcının o anki sorusunu embedding’e çeviriyorsunuz, sonra Cosmos’a şöyle bir sorgu atıyorsunuz:

SELECT TOP 5 c.content, c.type,
VectorDistance(c.embedding, @queryVector) AS score
FROM c
WHERE c.userId = @userId
ORDER BY VectorDistance(c.embedding, @queryVector)

Model tool’u çağırırken bunu kendi yapıyor. Yanı kullanıcı “geçen sefer bahsettiğim o Next.js problemini hatırlıyor musun” dediğinde ajan recall aracını çağırıyor, en yakın 5 anıyı bulup context’e ekliyor; sonra da sanki olayları gerçekten aklında tutuyormuş gibi davranıyor. Açık konuşayım, tam da burada sistemin havası değişiyor.

Peki neden? Çünkü düz metin saklamak yetmiyor bazen. Evet.

Türkiye bağlamında bu ne anlama geliyor?

Sahada gördüğüm tablo su: Türkiye’deki kurumsal ekiplerin büyük kısmı hâlâ “AI ajan” deyince RAG boru hattını düşünüyor — bir vektör DB, bir LLM, arada da retriever. Kötü mu? Değil. Ama ajan davranışıyla karışınca is dağılıyor, yönetimi de biraz uğraştırıyor. Ayrı bir vektör DB (Pinecone, Weaviate) kullanmak hem lisans hem operasyon maliyeti demek; Cosmos DB. Azure faturanizda varsa, tek data store içinde hem operasyonel veriyi hem hafızayı tutmak ciddi bir sadeleşme. Daha fazla bilgi için

Partition key’i sohbet ID’sine göre seçmek

Yanlış seçim bu. Sohbet ID’sine göre partition ayırınca, kullanıcının geçmişini toparlamak için cross-partition sorguya mecbur kalıyorsunuz — hem yavaşlıyor hem de faturayı şişiriyor. userId ile partition edin; bir kullanıcının pek çok hafızası aynı yerde dursun, sonra aradığınızı bulmak da daha az can sıkıcı oluyor.

Her mesajı embed edip yazmak

Bunu da çok gördüm. Model bazen araya “tamam, anladım” ya bir düşüneyim… da “devam edeyim mi” gibi boş mesajlar sıkıştırıyor, şey gibi düşünün; bunları direkt hafızaya basarsanız depo çöp kutusuna dönüyor. Bir salience filtresi koyun (küçük bir prompt yeter), LLM’e “bu bilgi gerçekten hatırlanmaya değer mi” diye sorun; evet diyorsa yazın, değilse geçin gitsin.

TTL’i unutmak

Burası sessiz sedasız patlıyor. Kısa vadeli hafızayı TTL’sız bırakırsanız container zamanla şişiyor, sorgular ağırlaşıyor ve sız de “neden böyle öldü” diye bakıp kalıyorsunuz; Cosmos’ta doküman bazında TTL var, bunu kullanmamak biraz tembellik gibi dürüyor. Ben genelde ttl: 3600 ile 1 saatlik conversation buffer tutuyorum, kalıcı olanları da ttl: -1 ile bırakıyorum.

Managed Identity yerine key kullanmak

İşin garibi, Hâlâ connection string gören oluyorum, şaşırdım açıkçası. Azure Container Apps ya da App Service üstünde eve’i deploy ediyorsanız, Managed Identity ile Cosmos DB’ye bağlanın; key rotation diye bir dert kalmıyor, secret leak riski de baya azalıyor. Prod tarafında bence bu işin yolu bu.

Blog yazan bir ajan — pratik uygulama

İtiraf edeyim, Örneğin son parça şu: eve’in içine blog yazma araçlarını da koyuyoruz. listPosts, createPost, updatePost gibi fonksiyonlar var. Bunlar gidip Next.js blogunuzun API endpoint’lerine bağlanıyor, işte olay bu. Ajan yazı üretirken hafızadan yazarın tonunu, sevdiği başlık formatını, daha önce hangi konulara girdiğini çekiyor; yanı ikinci yazıda “abi geçen seferkinin devamı gibi olsun. Biraz daha teknik” dediğinizde, gerçekten geçmişe bakıp ona göre yazıyor. Fena değil.

Peki neden önemli? Çünkü burada sadece “metin yaz” demiyoruz, biraz da bağlam veriyoruz. Yanı sistem bir yerden sonra sizin üslubunuzu kokluyor gibi oluyor (tabi tam insan gibi değil, o ayrı), ama yine de aynı çizgide kalmayı başarıyor. Az önce anlattığım şey basit dürüyor olabilir, ama pratikte asıl farkı orada görüyorsunuz.

Bu mimariyi Agent Framework Orchestration 1.0: Çoklu Ajan Koordinasyonu Yetişkin yazısındaki multi-agent yaklaşımıyla birleştirmek de mümkün — bir “yazar” ajanı, bir “editör” ajanı, üstüne ortak bir hafıza havuzu. Hatta bazen editör ajanı yazarın fazla dağıttığı yerleri toparlıyor, bazen de yazar “ben bunu böyle istememiştim” diye geri dönüyor; garip ama baya iş görüyor. Ama o başka bir yazının konusu.

Bir de şunu eklemek lazım: Cosmos DB’yi Logic Apps ile beslemek de seçenekler arasında. Mesela CRM’inizden müşteri — ki bu tartışılır — notu geldiğinde otomatik olarak hafızaya düşsün istiyorsanız, Cosmos DB Built-in Connector for Logic Apps Standard GA Öldü yazısında bahsettiğim connector işinizi görür. Açık konuşayım, her senaryoda şart değil; ama veri akışı biraz büyüyünce eliniz rahatlıyor (en azından benim deneyimim böyle). E sonra? İşte o zaman otomasyon kendini belli ediyor.

İlk adım olarak ne yapayım?

Denemek istiyorsanız, yol haritası aslında baya net; bir hafta sonu yetiyor, hatta biraz acele ederseniz cumartesi akşamı bile ilk sonuçları görürsünüz: (en azından benim deneyimim böyle)

1. Azure Portal’da bir Cosmos DB NoSQL account açın (Serverless, tek bölge — test için yeter). — bunu es geçmeyin
2. Vector policy’li bir container oluşturun (yukarıdaki tanımı kullanın). (bu kritik)
3. Azure OpenAI’de bir text-embedding-3-small deployment açın.
4. npm create eve-app ile bir eve projesi başlatın.
5. remember ve recall araçlarını yazın.
6. eve dev ile terminale düşün, kendinizle konuşun. İkinci turda hatırladığını göreceksiniz.

İlginç olan şu ki, Açık konuşayım, ilk denememde tam iki gün embed dimension mismatch hatasıyla uğraştım; çünkü bir yerde 1536 yazmışım, başka tarafta 3072 kalmış, sonra da neden olmuyor diye boş boş ekrana bakmışım. Kontrol edin, aynı boyutu heryerde tuttuğunuzdan emin olun. Küçük detay gibi dürüyor ama insanın sınırını ciddi bozuyor.

Şunu fark ettim: Peki neden?

Çünkü bu işte hata çoğu zaman modelde değil, ayarda çıkıyor; yanı embedding boyutu, container policy ve deployment tarafı birbirine tam oturmazsa sistem sessizce takılıyor, sız de “tamam ya çalışır şimdi” diye beklerken aslında yanlış yere bakmış oluyorsunuz. Evet, biraz can sıkıcı.

Neyse uzatmayalım; önce küçük bir kurulum yapın, sonra veriyi yazıp geri çağırmayı deneyin. Sonuç geldiğinde fark şurada ortaya çıkıyor: Eve konuşuyor gibi görünse de arka tarafta doğru vektör eşleşmesi yoksa hafıza kısmı neredeyse tamamen havada kalıyor. İşte kritik nokta bu.

Eğer ilk turda garip davranırsa şaşırmayın. Ben de şaşırdım açıkçası.

Peki bu yaklaşım kusursuz mu?

Değil tabi. Hatta hiç öyle değil. Eve henüz genç bir proje, o yüzden dokümantasyon Vercel’in AI SDK’sı kadar oturmuş sayılmaz; community örnekleri de az biraz sınırlı kalıyor, Cosmos DB tarafında vektör arama da hâlâ yeni sayılır (özellikle metadata ile vektörü birlikte sıraladığınız senaryolarda), kağıt üstünde güzel duran şey pratikte bazen ufak tefek cilaya ihtiyaç duyuyor.

İşin aslı bu. Zamanla toparlar diye bakıyorum. Bir de gpt-4.1 gibi büyük modellerde tool call latency bazen 2-3 saniyeye çıkabiliyor, kullanıcı bunu hissediyor yanı; streaming’i açık tutmak, ekranda bir “düşünüyorum” hali göstermek, hatta ufak bir bekleme animasyonu koymak bile fark yaratıyor, UX detayı gibi dürüyor ama kullanıcı tarafında baya iş görüyor.

Aslında, Yine de bütününe baktığımda — stateless bir ajanı gerçekten hatırlayan bir asistana çevirmek için şu an daha az sürtünmeli bir yol pek göremiyorum, hani başka kombinasyonlar var ama ya fazla uğraştırıyor ya da parçalar birbirine tam oturmuyor; açık konuşayım, ben bunu denemeye değer buluyorum.

Sıkça Sorulan Sorular

Ayrı bir vektör veritabanı yerine Cosmos DB kullanmak dezfayda yaratır mı?

Aşırı yüksek ölçekte —. Saniyede binlerce vektör araması yapıyorsanız — — en azından ben öyle düşünüyorum — Milvus veya Qdrant gibi özelleşmiş vektör DB’ler daha optimize kalıyor, bunu söylemek lazım. Ama tipik ajan hafıza yükünde, mesela kullanıcı başına birkaç yüz ile birkaç bin kayıt arası, Cosmos DB fazlasıyla yeterli. Hani ne farkı var diyorsunuz, değil mi? Açıkçası ekstra bir servisi ayağa kaldırıp yönetmemek başlı başına büyük bir avantaj bence.

Eve prod ortamında ne kadar stabil?

Henüz erken dönem bir proje, bunu göz önünde bulundurun. Vercel arkasında olduğu için tempo hızlı ilerliyor. Semver’e güvenip pinlemeden geçmeyin; tecrübeme göre prod deploy ederken lock file’ı çok sıkı tutmak, minör sürüm atlamalarını da manuel yapmak en sağlıklısı.

Embedding maliyetleri kontrolden çıkar mı?

Filtre koyarsanız hayır. Salience skorlaması ve content hash cache kullanıp aynı içeriği tekrar tekrar embed etmezseniz maliyet gayet öngörülebilir kalıyor. Aslında tipik senaryolarda aylık birkaç dolar bandında konuşuyoruz.

Managed Identity ile Cosmos DB’ye bağlanmak zor mu?

Hayır, birkaç satır iş. DefaultAzureCredential kullanıp Cosmos hesabında role assignment yapıyorsunuz — genelde Cosmos DB Built-in Data Contributor rolü yeterli oluyor. Böylece key rotation derdi de tamamen ortadan kalkıyor.

KVKK ve data residency açısından ne yapmalıyım?

Cosmos DB’yi Türkiye veya Avrupa bölgelerinden birinde açın. Kullanıcı verisini şifreli sütunlarda tutun, yanı Cosmos’taki CMK opsiyonunu değerlendirin. Ajan konuşmalarını loglarken PII maskeleme yapmayı ihmal etmeyin. Denetim gerekiyorsa diagnostic settings ile Log Analytics’e yönlendirmeniz yeterli.

Kaynaklar ve İleri Okuma

Building on Vercel’s eve + Azure Cosmos DB: An Agent That Remembers (Orijinal Yazı)

Bakın, Azure Cosmos DB NoSQL Vector Search Dokümantasyonu

Açık konuşayım, Azure Cosmos DB JavaScript SDK — GitHub

Vercel AI SDK Dokümantasyonu