Yönetilen ajan belleği

Important

Bu özellik Beta sürümündedir. Çalışma alanı yöneticileri Bu özelliğe erişimi Önizlemeler sayfasından denetleyebilir. Bkz. Azure Databricks önizlemelerini yönetme.

Yönetilen ajan belleği, ajanlarınıza konuşmalar arasında uzun süreli bellek sağlar. Azure Databricks altyapıyı işletir ve her kapsamın belleğini yalıtır; böylece depolama veya bölümlemeyi kendiniz yönetmeniz gerekmez.

Yönetilen bellekle aracılarınız şunları yapabilir:

• Konuşmalar arasında kullanıcı tercihlerini, geçmiş kararları ve birikmiş bağlamı anımsayın.
• Unity Kataloğu idaresi ile bu bilgilerin güvenliğini sağlayın.
• Aracılar ve projeler arasında bellek paylaşma.
• Zaman içinde doğruluklarını ve verimliliklerini geliştirin.

Gereksinimler

• Unity Kataloğu'nu etkinleştirmiş bir Databricks çalışma alanı.
• CREATE MEMORY STORE Üst şemada bellek depoları oluşturma ayrıcalığı.

Yönetilen bellek nasıl çalışır?

Yönetilen belleğin iki düzeyi vardır:

• Bellek deposu, bellek girdileri için kapsayıcı görevi gören güvenli hale getirilebilen bir Unity Kataloğudur. Bellek deposu, diğer Unity Kataloğu varlıklarıyla aynı idareyi, erişim denetimini ve kökeni devralır.
• Bellek girişi, bir bellek deposunda depolanan tek bir içerik parçasıdır. Her girdi bir kapsam ve bir yol tarafından tanımlanır. Kapsam, bir girdinin ait olduğu bellekleri belirler ve yol, bir kapsam içindeki girdileri bir dosya yoluna benzer şekilde düzenler (örneğin, /memories/preferences.md).

Scope

Kapsam, bir hafızayı bir kullanıcıya özel veya bir grup arasında paylaşma şeklidir. Uygulamanız her okuma ve yazma için bir kapsam belirler ve arama yalnızca eşleşen kapsama sahip girişleri döndürür. Temsilcinizin hatırlaması gereken stratejiyi seçin:

• Her kullanıcı için özel bellek: Kapsamı doğrulanmış son kullanıcı kimliğine ayarlayın. Her kullanıcı kendi bölümüne sahip olur ve sadece kendi girişlerini görür. Değer user_client , son kullanıcının kimliğini sizin için çözer.
  • Örnek: Bir destek temsilcisi, bir kullanıcının iletişim tercihlerini ve geçmiş taleplerini hatırlar.
• Bir grup için paylaşılan hafıza: Kapsamı, seçtiğiniz sabit bir anahtara ayarlayın; örneğin bir organizasyon, ekip veya proje kimliği. Her kullanıcı aynı anıları okur ve yazar.
  • Örnek: Bir ekip temsilcisi, şirket terimleri ve iç politikaların ortak bir sözlüğünü hatırlıyor.
• Başka bir şeyle bölünen hafıza: Kapsamı, kiracı kimliği veya user_id:project bileşik gibi kendi değerlerinizden oluşturun.
  • Örnek: Çoklu kiracılı bir uygulama, her müşterinin belleğini ayrı tutar veya her proje için tek bir kullanıcının belleği izole edilir.

Tek bir ajan, stratejileri tek bir konuşmada birleştirebilir. Örneğin, aynı istekte bir kullanıcının özel belleği ve paylaşılan ekip belleğini okuyabilir.

Kapsamı uygulama kodunuzda, isteğin değiştiremeyeceği güvenilir çağıran bağlamından ayarlayın: kullanıcı başına bellek için OBO belirtecindeki doğrulanmış son kullanıcı kimliğini ya da paylaşılan bellek için güvenilir bir kiracı, ekip veya proje anahtarını kullanın. Modelin bunu seçmesine asla izin verme. Kapsam stratejiniz bir son kullanıcı kimliğine bağlıysa, paylaşılan bir kapsama dönmek yerine son kullanıcı kimliği içermeyen istekleri reddedin. Yetenekmanaged-memory bu kurulumda size rehberlik eder.

Scope anıları ayırıyor ama mağazaya erişim vermiyor. Bir çağıranın bunu açmak için yine de WRITE MEMORY STORE veya READ MEMORY STORE ayrıcalığına sahip olması gerekir. Bkz. Bellek erişim kontrolü.

Warning

Kapsam, kullanıcılar arasındaki izolasyon sınırıdır, ancak erişim kontrolü değildir. Uygulama servisi yöneticisi her kapsamı okuyabilir, bu yüzden kimlik bilgilerini buna göre koruyun.

Ajanın kaydettiği ve hatırladığı şeyler

Yönetilen bellek, bellek deposunu ve girişleri okuma ve yazma API'lerini sağlar. Uygulamanız, ajanın neyi kaydettiğini, ne zaman belleği geri aldığını ve sonuçları nasıl kullandığını kontrol eder.

Bu davranışı ajanın sistem isteğinde tanımlayın: ajana hangi kalıcı bilgileri kaydedeceğini ve ne zaman alınacağını söyleyin. managed-memory becerisi ve şablonlar, bu sistem istemini MEMORY_INSTRUCTIONS adlı bir sabitte tutar. Kapsam, güvenilir uygulama kodunda ayrı olarak yapılandırılır ve model tarafından asla seçilmez.

Metinleri kapsam stratejinizle eşleştirin. Aşağıda kullanıcı başına stratejiye bir örnek verilmiştir:

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

Yönetilen hafıza becerilerine başlayın

Bir aracıya yönetilen bellek eklemenin en kolay yolu Claude Code becerisidir managed-memory . Beceri sizin için tüm kurulumu işler ve hem OpenAI Aracıları SDK'sı hem de LangGraph ile çalışır.

Beceriyi projenize şu iki yoldan biriyle dahil edin:

Şablondan başlama

Beceri, Databricks uygulama şablonları içinde sunulur. Aracı şablonlarından birini kullanarak yeni bir aracının iskeletini oluşturun, .claude/skills/managed-memory/ altında beceriyi bulun.

1. Şablon deposunu kopyalayın:

   git clone https://github.com/databricks/app-templates.git
   

2. app-templates göz atın, başlamak için bir temsilci şablonu seçin. Örneğin, OpenAI Aracıları SDK şablonunu kullanmak için:

   cd app-templates/agent-openai-agents-sdk
   

   Note

   "advanced" uygulama şablonları için, dağıttıktan sonra uygulama hizmeti sorumlusuna Lakebase Postgres ayrıcalıkları vermeniz gerekir; aksi takdirde oturum kurulumu 502 hatası döndürür.

3. Beceri projenize eklendikten sonra ne istediğinizi açıklayın ve gerisini kodlama yardımcınız üstlenir:

   Tavsiye

   Add Databricks managed long-term memory to my agent.
   

Mevcut projeye beceri ekleme

Zaten bir aracı projeniz varsa, beceriyi buna ekleyin.

1. Beceri dizini mevcut değilse oluşturun:

   mkdir -p .claude/skills/managed-memory
   

2. SKILL.md managed-memory dosyasını indirin ve konumuna kaydedin.

3. Beceri projenize eklendikten sonra ne istediğinizi açıklayın ve gerisini kodlama yardımcınız üstlenir:

   Tavsiye

   Add Databricks managed long-term memory to my agent.
   

Bellek depolarını el ile oluşturma ve kullanma

Bu bölümde Claude Code becerisi olmadan managed-memory bellek deposu oluşturma ve kullanma gösterilmektedir.

Aşağıdaki örnek, bir kullanıcının tercihlerini depolayan ve bunları sonraki bir konuşmada alan bir müşteri destek aracısı için yönetilen belleği ayarlar.

1. API'leri çağırmak için Databricks CLI kullanarak bir OAuth belirteci oluşturun:

   databricks auth login --host ${DATABRICKS_HOST}
   databricks auth token
   

2. Ajanınızın anılarını tutmak için bir bellek deposu oluşturun:

   curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "support_agent_memory",
       "catalog_name": "main",
       "schema_name": "default",
       "description": "Long-term memory for the customer support agent"
     }'
   

3. Ajan bir kullanıcı hakkında bir şey öğrendikten sonra bir bellek girdisi yazın. scope, girişi tek bir kullanıcıya ayırır. Tam bellek metni için contents alanını, geri getirmeyi iyileştiren kısa bir özet için ise description alanını kullanın:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "path": "/memories/preferences.md",
       "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
       "description": "User 123 communication preferences and account details"
     }'
   

4. Ajanın öğrendiklerini geri almak için daha sonraki bir konuşmada o kullanıcının bellek girdilerinde arama yapın:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries:search" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "scope": "user-123",
       "query": "communication preferences"
     }'
   

Uç noktalar, istek alanları ve yanıt alanları dahil olmak üzere tam REST API için Memory API referansına bakın.

Bir ajana konuşmalarla bellek ekleme

Yukarıdaki REST iş akışı, bellek depoyu ve giriş API'lerini doğrudan çağırır. Uç noktaya hizmet veren bir Azure Databricks modeli üzerinde aracı oluşturduğunuzda, bunun yerine SDK'daki OpenAI uyumlu istemciyle bir databricks-openai bellek deposu bağlayın.

Konuşma, bir bellek deposu tarafından yedeklenen ve tek bir kapsama sabitlenen OpenAI uyumlu konuşma durumudur (iletilerin ve araç çağrılarının çalışma geçmişi). Aracının önceki etkileşimleri hatırlamasını sağlamak için istekler arasında aynı konuşmayı yeniden kullanın.

1. Mevcut bellek depolarını ve kapsamı yeni bir konuşmaya bağlayın. memory_store.name veri deposunun üç düzeyli adıdır ve scope konuşma durumunu genellikle son kullanıcıya göre bölümlendirir:

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   workspace_client = WorkspaceClient()
   user_id = str(workspace_client.current_user.me().id)
   
   client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)
   
   conversation = client.conversations.create(
       extra_body={
           "memory_store": {"name": "main.default.support_agent_memory"},
           "scope": {"kind": "user", "value": user_id},
       },
   )
   

2. Konuşma kimliğini responses.create öğesine iletin. Aracı, konuşmanın durumunu bu kapsam altındaki bağlı bellek deposunda okur ve yazar:

   response = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
       stream=True,
   )
   
   for event in response:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

3. Ajanın önceki konuşmaları anımsaması için sonraki isteklerde aynı konuşma kimliğini yeniden kullanın. Sıra başına yeni bir konuşma oluşturmayın:

   followup = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
       stream=True,
   )
   
   for event in followup:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

Konuşma uç noktaları ve istek alanları için bkz . Konuşma API'leri.

Bellek erişim kontrolü

Bellek depoları, Unity Catalog içinde güvenliği sağlanabilen nesnelerdir. Aşağıdaki ayrıcalıklar erişimi denetler:

Privilege	Şunlar için geçerlidir:	Açıklama
CREATE MEMORY STORE	Ana şema	Şema altında yeni bellek depoları oluşturun.
READ MEMORY STORE	Bellek depolama	Bellek deposu meta verilerini ve girdilerini okuyun.
WRITE MEMORY STORE	Bellek depolama	Bir depoda bellek girdileri oluşturun, güncelleyin ve silin.
MANAGE	Bellek depolama	Bellek deposunun kendisini güncelleştirin veya silin. Diğer kullanıcılara izinler verin.
USE SCHEMA	Ana şema	Bellek depolarını bir şemada listeleyin.

Kısa süreli belleği uygulayın

Bellek girdisi API’leri, ajanınızın kullanabileceği araçlar olarak uzun süreli bellek sağlar. Bir oturumda aracınıza yönetilen kısa süreli bellek vermek için Databricks, bellek deponuzu bir konuşmaya bağlamanızı önerir. Ayrıca şunları da yapabilirsiniz:

• OpenAI session= parametresi veya bir LangGraph kontrol noktası oluşturucu gibi ajan çerçevenizin oturum belleğini koruyun.
• Konuşma geçmişi deposu için kendi kendini yöneten ajan belleğini kullanın.

Güvenlik önerileri

Azure Databricks, yönetilen depolama, şifreleme, yalıtım mekanizmaları ve denetim izi sağlar. Uygulama geliştiricisi olarak Databricks aşağıdakileri önerir:

• Farklı bölümleme yapmak için kasıtlı bir nedeniniz yoksa (örneğin, proje başına veya hesap başına bellek) kullanıcı başına kapsam varsayılanını (user_client) kullanın.
• En az ayrıcalık ver: yalnızca aracınızın hizmet sorumlusu gereksinimleri.WRITE MEMORY STORE READ MEMORY STORE izinleri sınırlı tutun ve insan kullanıcılara veya büyük gruplara geniş kapsamlı izinler vermekten kaçının.
• Uygulama hizmet sorumlusunun kimlik bilgilerini koruyun: bunlar, mağazanın veri düzlemine erişimin anahtarıdır. Bunu yüksek değerli bir hizmet kimlik bilgisi olarak ele alın — kısa ömürlü belirteçler kullanın, bunu günlüklere kaydetmekten kaçının ve uygulamanıza SSRF’ye karşı korumalar ekleyin.

Limitations

• Bellek girişleri yalnızca uzun süreli bellek sağlar. Kısa ve uzun süreli bellek arasındaki fark için bkz. Kısa süreli ve uzun süreli bellek.
• Bellek depoları ve girdileri yalnızca Unity Kataloğu REST API'si aracılığıyla oluşturulur ve yönetilir; bu API'ler için Python SDK yoktur. Bir aracının bellek deposunu kullanmak için, onu OpenAI uyumlu istemciyi kullanarak bir konuşmaya bağlayın. Bkz. Konuşmalarla aracıya bellek ekleme.

Sonraki Adımlar

• Bellek API'si başvurusu