Yönetilen ajan belleği

Yönetilen aracı belleği, yapay zeka aracıları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, yönetilen belleğin bir aracının anılarını farklı kullanıcılar veya gruplar için nasıl ayrı tuttuğunu ifade eder. Her bellek girişi tam olarak bir kapsama aittir ve arama yalnızca sorguladığınız kapsamdaki girdileri döndürür.

• Kişisel bellek: Her kullanıcının tercihleri ve geçmiş kararları gibi kendi özel belleğini alması için kapsam olarak bir son kullanıcı kimliği kullanın. Kullanıcılar yalnızca kendi girdilerini görür. Kapsam değeri user_client , son kullanıcının kimliğini otomatik olarak alır.
• Kurumsal bilgi: Şirket bilgileri, sözlükler ve en iyi uygulamalar gibi, aracının herhangi bir kullanıcısının yararlanabileceği bilgileri depolamak için kuruluş veya ekip kimliği gibi paylaşılan bir anahtar kullanın.

Tek bir aracı, her ikisini de aynı anda kullanabilir: aynı konuşma içinde bir kullanıcının kişisel kapsamından ve paylaşılan kurumsal kapsamdan okuyabilir. scope her bellek girişi isteğinde gereklidir.

Yönetilen bellek becerilerini kullanmaya başlama

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 denetimi

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

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