Yönetilen ajan belleği

Important

Bu özellik Beta sürümündedir.

Yönetilen ajan belleği, ajanlarınıza konuşmalar boyunca kalıcı ve uzun vadeli hafıza sağlar. Azure Databricks, belleği Lakebase'te saklar ve depolama, indeksleme ve anlamsal aramayı sizin için yönetir; böylece ajanlarınız kullanıcı tercihlerini, geçmiş kararları ve birikmiş bağlamı siz bir veritabanı çalıştırmadan hatırlayabilir.

Note

Önizleme sırasında, bellek kayıtlarınızı saklayan temel Lakebase örneği için faturalandırılırsınız. Yönetilen ajan belleği için ek ücret uygulanmaz. Önizleme ilerledikçe fiyatlandırma değişebilir.

Yönetilen belleği kullanarak ajanlarınızın şunları yapmasını istediğinizde:

  • Ayrı konuşmalarda kullanıcı tercihlerini, gerçeklerini ve kararlarını hatırlayın.
  • Bir ajanın önceki oturumlarda öğrendiklerine göre yanıtları kişiselleştirin.
  • Birikmiş bilgileri ajanlar ve projeler arasında paylaşın.
  • Zamanla doğruluk ve verimlilik açısından gelişin.

Yönetilen bellek, herhangi bir çerçeve üzerinde kurulmuş ajanlarla çalışır. Tek bir etkileşimde kısa vadeli konuşma geçmişi için yönetilen ajan oturumları kullanın.

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

Yönetilen ajan belleği kaynak hiyerarşisi: bir bellek deposu, her biri actor_id, isteğe bağlı session_id ve yol ile tanımlanan ve içerik ile bir açıklama barındıran birçok bellek girdisi içerir.

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

  • Bir bellek deposu, bir ajanın anıları için çalışma alanı kapsamlı konteynerdir. Bir mağaza oluşturmak, arka plandaki Lakebase depolamasını otomatik olarak hazırlar. Bir mağaza, display_name ile adreslenir.
  • Bir hafıza kaydı, bir mağazadaki bireysel bir içerik parçasıdır. Her girişin serbest biçimli bir metni content, erişim için kullanılan kısa bir metni description ve onu düzenleyen ve bölümlere ayıran bir dizi alanı vardır:
    • actor_id (zorunlu): belleğin kime ait olduğunu, örneğin son kullanıcıya veya başka bir ajana.
    • session_id (isteğe bağlı): hafızanın hangi oturumdan yakalandığını, takip ve kaynağını kaydeder. Belirli bir oturuma bağlı olmayan hafıza için ayarsız bırakın.
    • path (zorunlu): bir aktör içindeki girişleri düzenleyen dosya sistemi benzeri bir yol, örneğin /preferences/response-style.md.

Bir girdi, , session_idve path. actor_idbirleşimiyle benzersiz şekilde tanımlanır.

Veri Çekme

Belleği iki şekilde geri alın:

  • Listeleyin bir aktör için girişleri, isteğe bağlı olarak session_id ya da bir path önekiyle filtrelenmiş. Bunu, bir ajanın bildiklerinin indeksini incelemek veya render etmek için kullanın.
  • Doğal dil sorgusu olan bir aktör için girişleri arayın. Arama, tam metin (BM25) alaka puanına göre sıralanmış en ilgili girişleri döndürür.

Gereksinimler

  • AgentKit SDK'yı kullanmak için Python 3.10 veya üzerini yükleyin. AgentKit SDK, aşağıdaki örneklerde kullanılan ajan API'leri için Databricks Python istemcisidir. REST API'sini doğrudan herhangi bir dilden çağırabilirsiniz, Python gereksinimi olmadan.

Get started

Bu örnekler, bir destek ajanı için yönetilen bellek oluşturur: bir bellek deposu oluşturur, kullanıcının tercihini kaydeder ve sonraki bir konuşmada geri çağırır. Projenize uygun müşteriyi seçin. Bir bellek deposu display_name 3 ila 56 karakter olmalı, küçük harfle başlayıp harf veya sayı ile bitmeli ve yalnızca küçük harfler, sayılar ve tire içermelidir.

AgentKit SDK

AgentKit SDK, paket içinde databricks-agentbricks dağıtılan ajan API'leri için Databricks Python istemcisidir. Databricks SDK'sının WorkspaceClient ile kimlik doğrulaması yapar.

  1. AgentKit SDK'sını kurun:

    pip install databricks-agentbricks

  2. Ajanınız için bir hafıza deposu oluşturun. AgentKitClient Kimlik bilgilerinizle doğrulanıyor WorkspaceClient :

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
memory_store = client.memory_stores.create("support-agent-memory")

  3. Ajan bir kullanıcı hakkında kalıcı bir şey öğrendikten sonra bir hafıza kaydet. actor_id bu hafızanın kime ait olduğunu, path onu ilgili aktör içinde organize ettiğini ve description geri getirmeyi iyileştirdiğini gösterir:

    memory_store.add(
    actor_id="user-123",
    path="/preferences/communication.md",
    content="Prefers email over phone. Timezone: PST. Enterprise subscription.",
    description="User 123 communication preferences",
)

  4. Kullanıcının sonraki bir konuşmada doğal dil aramasıyla anılarını hatırlayın:

    results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)

REST API

İstemciler REST API'sini . /api/2.0/agents/memory-storesaltında çağırır. Python dışındaki diller için bunu doğrudan çağırın.

  1. Databricks CLI ile bir OAuth tokenı oluşturun:

    databricks auth login --host ${DATABRICKS_HOST}
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

  2. Ajanınız için bir hafıza deposu oluşturun:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"display_name": "support-agent-memory", "description": "Support agent memory"}'

  3. Bir kullanıcı için bir bellek kaydı kaydedin. actor_id, bunun kimin hafızası olduğunu belirtir, path onu düzenler ve description geri getirmeyi iyileştirir:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "path": "/preferences/communication.md", "content": "Prefers email over phone.", "description": "Communication preferences"}'

  4. Kullanıcının anılarını doğal dil aramasıyla hatırlayın:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "query": "communication preferences"}'

Ajanınıza bellek araçları verin.

Bir ajanın belleği ne zaman kaydedip geri çağıracağına karar vermesini sağlamak için, istemci işlemlerini araçlar hâline getirin ve ajanı bunları ne zaman kullanacağı konusunda sistem isteminde yönlendirin. actor_id değerini güvenilir uygulama kodunda doğrulanmış son kullanıcı kimliğinden ayarlayın. Modelin hangi hafızayı okuyup yazacağını asla seçmesine izin vermeyin.

Aşağıdaki örnek, memory_store bölümündeki AgentKit SDK örneğini OpenAI Agents SDK'de kullanılacak araçlar hâline getirir.

from agents import Agent, function_tool

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences and recall them when relevant.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

Aynı yaklaşım, Claude Agent SDK ve diğer çerçevelerde de işe yarar: deponun arama ve ekleme işlemlerini çerçevenin araç türü olarak sarmalayın.

Bölümleme ve güvenli bellek

Bir depoda, actor_id anıların kime ait olduğunu ayırt etmenizi sağlar. Her liste ve arama tek actor_idbir alana odaklanır, bu yüzden temsilcinizin hatırlaması gereken stratejiyi seçin:

  • Her kullanıcı için özel bellek: Doğrulanmış son kullanıcı kimliğine ayarlandı actor_id . Her kullanıcı kendi bölümüne sahip olur ve ajan sadece o kullanıcının girişlerini geri çağırır.
    • Örnek: Bir destek temsilcisi, bir kullanıcının iletişim tercihlerini ve geçmiş taleplerini hatırlar.
  • Bir grup için paylaşılan bellek:actor_id Seçtiğiniz sabit bir anahtara ayarlanabilir, örneğin bir ekip, proje veya organizasyon kimliği. Herkes aynı anıları okur ve yazar.
    • Örnek: Bir ekip temsilcisi, şirket terimleri ve iç geleneklerden oluşan ortak bir sözlüğü hatırlar.
  • Belleğin başka bir şeye göre bölünmesi:user:project öğesini kiracı kimliği veya actor_id kompozit gibi kendi değerlerinizden oluşturun.
    • Örnek: Çok kiracılı bir uygulama, her müşterinin kullanıcılarının birbirlerinden yalıtılmış kalması için actor_id değerini {tenant}:{user} olarak ayarlar.

Uygulama kodunuzda actor_id değerini güvenilir çağıran bağlamında ayarlayın: kullanıcı başına bellek için doğrulanmış son kullanıcı kimliği veya paylaşılan bellek için güvenilir bir ekip ya da proje anahtarı. Modelin bunu seçmesine asla izin verme. Stratejiniz bir son kullanıcı kimliğine bağlıysa, paylaşılan bir actor_id kullanıcısına geri dönmek yerine, böyle bir kimlik taşımayan istekleri reddedin.

Warning

actor_id anıları ayırır, ama erişim kontrolü değildir. Yönetilen bellek depoları çalışma alanı kapsamındadır; bu nedenle, bir depoya erişebilen herhangi bir principal tüm aktörlerdeki her girdiyi okuyabilir ve yazabilir. Güvenlik sınırı aktör değil, depodur. Kiracılar veya kullanıcılar arasında sıkı izolasyon için, sınır başına ayrı bir bellek deposu oluşturun.

Ajanınızın service principal'ı gibi başka bir principal'ın bir depoyu kullanmasına izin vermek için, AgentKit SDK'daki deponun izin verme işlemiyle (memory_store.grant_permission(principal_id)) ona erişim izni verin.

Limitations

  • Yönetilen bellek yalnızca uzun süreli bellek sağlar. Kısa vadeli konuşma geçmişi için yönetilen ajan oturumlarına bakınız.
  • Arama, 100'e kadar girişten oluşan en üstte N sonuç seti döndüren, ilgililik dereceli, tam metin (BM25) bir işlemdir. Sayfa belirleme veya vektör benzerlik aramasını desteklemez.
  • Erişim kontrolü mağaza düzeyinde uygulanır. Giriş başına ve aktör başına erişim kontrolü mevcut değildir.
  • Mağaza display_name oluşturulduktan sonra değişmezdir. Sadece description güncellenebilir.

Sonraki Adımlar

  • Last updated on