Aracı belleği

Important

Bu özellik Beta sürümündedir. Bunu kullanmak için, bir çalışma alanı yöneticisinin Önizlemeler sayfasından Ajan Bellek Oturumları'nı açması gerekir. Bkz. Azure Databricks önizlemelerini yönetme.

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

AgentKit SDK ve REST API örnekleri, bir destek ajanı için ajan belleğini yapılandırır: bir bellek deposu oluşturur, kullanıcının tercihini kaydeder ve bunu sonraki bir konuşmada geri çağırır. Agent Bricks CLI örneği, bir bellek deposunu CLI ile oluşturup dağıttığınız bir ajana bağlar. 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 Tuğlalar

Ajanınızı Agent Bricks CLI ile oluşturursanız, agentbricks init, agent.toml içinde bir bellek deposu tanımlar. agentbricks deploy henüz mevcut değilse depoyu oluşturur ve dağıtılan ajana depoya erişim izni verir.

Bir yol seçin:

  • Boş başlat (çoğu ajan): Ajanı dağıtıma alın. agentbricks init tarafından bildirilen bellek deposunu agentbricks deploy oluşturur. my-agent adlı bir aracıyı dağıtmak için aşağıdakileri çalıştırın:

    agentbricks deploy my-agent

  • Depoda zaten bulunan anılarla başlayın: Önce depoyu oluşturun, kayıtlar ekleyin, sonra depoyu ajana bağlayın ve dağıtıma alın.

    1. Adı my-agent-memory olan bir mağaza oluşturmak için aşağıdakileri çalıştırın. Çıktı, mağaza adından ayrı oluşturulmuş bir tanımlayıcı olan store ID'yi içerir:

      agentbricks memory stores create --name my-agent-memory

    2. Bir giriş eklemek için, <store-id> yerine önceki adımdaki store ID’yi koyarak aşağıdakileri çalıştırın:

      agentbricks memory entries create --store <store-id> --actor-id you@example.com \
  --path /preferences/style.md --content "Prefers Python and concise answers with code examples."

    3. Mağazayı bağlamak ve ajanı dağıtmak için şunları çalıştırın. agentbricks memory bind, agent.toml içindeki mağaza adını değiştirir ve agentbricks deploy mevcut mağazayı adıyla bulur ve yeni bir mağaza oluşturmak yerine kullanır:

      agentbricks memory bind my-agent-memory
agentbricks deploy my-agent

--path, store içindeki girdinin anahtarıdır; makinenizdeki bir dosya değildir. --actor-id hafızanın ait olduğu kullanıcıdır. Dağıtılan bir ajan, oturum açmış kullanıcının e-posta adresini aktör kimliği olarak kullanır, bu nedenle her girdiyi ajanla sohbet eden kullanıcının e-posta adresiyle başlatın.

Agent Bricks CLI'de memory bind ve agentbricks deploy, bir mağazaya adıyla atıfta bulunur. Tek bir depoya etki eden komutlar, örneğin memory entries create, oluşturulan depo kimliğini alır.

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. İzin seviyeleri, desteklenen işlemler ve örnekler için Ajan belleği ve oturum depoları için izinleri yönetme bölümüne bakın.

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: