Aracı belleği

Important

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

Ajan hafızası, ajanlarınıza uzun vadeli bir hafıza sağlar ve bu hafıza konuşmalar boyunca devam eder. Azure Databricks, belleği Lakebase'te saklar ve depolama, indeksleme ve aramayı sizin için yönetir, böylece ajanlarınız kullanıcı tercihlerini, geçmiş kararlarını 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. Ajan belleğinin kendisi için ek ücret uygulanmaz. Önizleme ilerledikçe fiyatlandırma değişebilir.

Ajanlarınızın şunları yapmasını istediğinizde ajan belleğini kullanın:

  • 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.

Ajan belleği, herhangi bir çerçeve üzerinde kurulmuş ajanlarla çalışır. Tek bir etkileşimde kısa süreli konuşma geçmişi için ajan oturumlarını kullanın.

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.
  • memory_store.put() veya memory_store.list(path=...) kullanmak için, databricks-agentbricks 0.6.0 ve üzerini kurun.

Ajan belleği nasıl çalışır

Ajan bellek kaynak hiyerarşisi: Bir bellek deposu, her biri actor_id, isteğe bağlı session_id ve yol ile tanımlanan, içerik ve açıklama içeren birçok bellek girişi içerir.

Ajan belleğinin iki seviyesi 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ğazayı, mağazayı oluştururken seçtiğiniz mağaza kimliğiyle tanımlarsınız.
  • 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 ait olduğu oturum. Aktörün oturumları arasında geçerli olan bellek 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. Aynı yol iki farklı oturumda veya bir oturum altında ya da oturumsuz olarak iki ayrı kayıt olarak bulunur.

Girişler bir mağazaya iki şekilde girer: ajanınız veya uygulamanız onları doğrudan yazar ya da bir bellek pipeline’ı onları oturum deposundaki konuşmalardan damıtır.

Veri Çekme

Belleği iki şekilde geri alın:

  • Listele bir aktör için girişleri, isteğe bağlı olarak session_id, bir path ön eki veya tam bir path ile filtreleyerek. 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, en ilgili kayıtları alaka puanına göre sıralanmış olarak döndürür.

İki işlemden herhangi birinde bir session_id filtre, yalnızca o oturumla kaydedilen girişleri geri getirir. Oturum olmadan kaydedilen girişleri döndürmüyor.

Get started

Bu örnekler, bir destek ajanı için ajan belleği 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 kimliği 3 ila 56 karakter olmalı, küçük harfle başlamalı, 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",
)

    add(), o yolda zaten bir giriş varsa ALREADY_EXISTS ile başarısız olur. Girişi oluşturmak veya mevcut olanı güncellemek için memory_store.put() öğesini aynı argümanlarla çağırın.

  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?managed_memory_store_id=support-agent-memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"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"}'

    Eğer o yolda zaten bir giriş varsa, istek ALREADY_EXISTS (HTTP 409) hatasıyla başarısız olur. Bunun yerine mevcut girişi güncellemek için, onu yola göre arayın. Arama her oturum için yolun girişlerini döndürür, bu yüzden session_id ile eşleşeni seçin. name öğesinin son bölümü giriş kimliğidir:

    curl -G "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  --data-urlencode "actor_id=user-123" --data-urlencode "path=/preferences/communication.md"

    Sonra girişin içeriğini kimliğine göre güncelle:

    curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries/<entry-id>?update_mask=content" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"content": "Prefers email over phone. Timezone: PST."}'

  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, replacing any memory at the same path."""
        memory_store.put(actor_id=actor_id, path=path, content=content, description=description or None)
        return f"Saved memory at {path}"

    @function_tool
    def list_memories() -> str:
        """List the paths and descriptions of the user's long-term memories."""
        memories = memory_store.list(actor_id=actor_id)
        return "\n".join(f"{m.path}: {m.description}" if m.description else m.path for m in memories) or "No memory found."

    @function_tool
    def forget_memory(path: str) -> str:
        """Delete the long-term memory at a path, such as when the user asks you to forget it."""
        memories = list(memory_store.list(actor_id=actor_id, path=path))
        for memory in memories:
            memory.delete()
        return f"Forgot memory at {path}" if memories else f"No memory at {path}"

    return [search_memory, save_memory, list_memories, forget_memory]

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

put() girişi oluşturur veya zaten o yolda olan girişin içeriğini değiştirir. İçeriği bunun yerine yeni satırlar olarak eklemek için append=True iletin. put() atomik değildir, bu yüzden aynı yola eşzamanlı yazımlar birbirinin üzerine yazabilir. list(path=...) Her oturumda tam olarak o yoldaki girişleri döndürür, böylece forget_memory bir oturum altındaki yolda kaydedilen tüm girişleri de siler.

Aynı desen Claude Agent SDK ve diğer çerçevelerde de çalışır: mağazanın arama, koyma, listeleme ve silme işlemlerini çerçevenin araç türü olarak sarmalayın.

Aynı bellek deposunda da bir bellek pipeline çalıştırırsanız, pipeline ajanınızın işlediği herhangi bir aktör için kaydettiği kayıtları yeniden yazabilir, birleştirebilir, bölebilir veya silebilir.

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. Bellek depoları workspace kapsamlıdır, bu yüzden bir depoya ulaşabilen herhangi bir principal tüm aktörler arasında her kaydı okuyup 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. Sadece mağazanın yaratıcısı veya bir çalışma alanı yöneticisi erişim izni verebilir.

Limitations

  • Ajan belleği yalnızca uzun süreli bellek sağlar. Kısa süreli konuşma geçmişi için bkz. agent sessions.
  • Arama, girişleri alaka düzeyine göre sıralar; her girişin içeriği ve açıklaması üzerinde tam metin (BM25) ve anlamsal eşleştirmeyi birleştirir. 100 girişe kadar geri dönüyor ve sayfalamayı desteklemiyor.
  • 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 erişim kontrolü, bir mağazanın girişlerini kapsar. Her çalışma alanı kullanıcısı, kimlik ve açıklamaları dahil bellek depolarını listeleyebilir ve alabilir.
  • Bir mağazanın kimliğini oluşturduktan sonra değiştiremezsiniz. Sadece description güncellenebilir.

Sonraki Adımlar

  • Son güncelleştirme: