Yönetilen ajan oturumları

Important

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

Yönetilen ajan oturumları, ajanlarınıza oturum durumu için dayanıklı, çerçeveden bağımsız bir depolama sağlar: bir ajan veya framework'ün bir etkileşim için sakladığı durum. Bu, çoğu durumda, bir ajanın bir turun başında okuyup işlem sırasında buna eklemeler yaptığı konuşma geçmişi; yani mesajların, araç çağrılarının ve sonuçların sıralı dökümüdür. Ayrıca, etkileşim için bir çerçevenin devam ettiği başka bir durum da olabilir, örneğin bir LangGraph grafiği. Azure Databricks bunu Lakebase'te saklıyor ve depolama alanını sizin için yönetiyor, yani veritabanını oluşturmuyor veya işletmezsiniz.

Note

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

Yönetilen oturumları istediğiniz zaman kullanın:

  • Bir ajanın konuşma geçmişini, yeniden başlatmalardan sonra da korunacak ve daha sonra devam ettirilebilecek şekilde kalıcı olarak saklayın.
  • Sonraki mesajda tam bağlamı (araç çağrıları ve akıl yürütme dahil) yeniden oluşturun.
  • Kendi arayüzünden geçmiş konuşmaları listeleyin, özgeçmiş yapın ve dallayın.

Yönetilen oturumlar tek bir etkileşim durumunu (kısa süreli, oturum içi durum) tutar. Konuşmalar boyunca kalıcı ve uzun süreli hafıza için yönetilen ajan belleği kullanın.

Yönetilen oturumlar nasıl çalışır

Yönetilen ajan oturumları kaynak hiyerarşisi: Bir oturum deposu birçok oturum içerir ve her oturum çok sayıda sıralanmış oturum öğesi içerir.

Yönetilen oturumların üç seviyesi vardır:

  • Oturum deposu, bir ajanın oturumları için çalışma alanı kapsamlı konteynerdir. Bir mağaza oluşturmak, arka plandaki Lakebase depolamasını otomatik olarak hazırlar. Benzersiz bir çalışma alanı session_store_nameseçersiniz.
  • Bir oturum, bir mağaza içinde kalıcı bir etkileşimdir (genellikle bir konuşma konusu). Bir oturum şu şekilde tanımlanır:
    • actor_id (zorunlu): oturumun kime ait olduğunu, örneğin son kullanıcıya veya başka bir ajana. Tek bir konunun tüm oturumlarını gruplar, böylece bunları listeleyip filtreleyebilirsiniz. Kullanıcı başına bir uygulama geliştirdiğinizde, actor_id kullanıcının kimliğini (örneğin, uygulamanızın kimlik doğrulamasından doğrulanmış son kullanıcı kimliği) ayarlayın, böylece her kullanıcının oturumları gruplanmış kalır. Bunu güvenilir uygulama bağlamından ayarlayın, model veya kullanıcı tarafından sağlanan bir değer olarak değil.
    • session_id (isteğe bağlı): etkileşim için arayan tarafından seçilmiş bir kimlik. Belirtmediğinizde hizmet bir tane oluşturur.
    • parent_session_id (isteğe bağlı): bir oturumu çatallandığı oturuma bağlayarak dallanmış konuşmaları temsil eder.
  • Oturum öğesi, bir oturumun sıralanmış geçmişindeki bir giriştir. Her öğe, mesaj, araç çağrısı, araç sonucu veya akıl yürütme bloğu gibi opak ve JSON uyumlu data bir değer taşır. Azure Databricks her öğeyi bir item_id ve bir create_time olarak atamakta ve içeriğini incelemez veya doğrulamaz. Öğeler eklendikten sonra değişmezdir.

Hizmet, bir oturumun öğeleri için deterministik bir sıralama tutar ve oturum deposuna karşı her işlemi yetkilendirir.

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 temsilcisi için yönetilen oturumları ayarlar: bir oturum deposu oluşturur, tek bir konuşma için bir oturum başlatır, konuşmadaki mesajları ekler ve daha sonraki bir istekte geçmişi yeniden okur. Projenize uygun müşteriyi seçin.

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. Bir oturum deposu oluşturun, ardından tek bir konuşma için bir oturum başlatın. actor_id konuşmanın kime ait olduğudur; isteğe bağlı session_id bu konuşmayı benzersiz şekilde tanımlar:

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
session_store = client.session_stores.create("support-agent-sessions")
session = session_store.add(actor_id="customer-123", session_id="case-456")

  3. Ajan çalışırken konuşma dönüşlerini ekleyin. Her eşya herhangi bir JSON uyumlu değerdir:

    session.append_items(
    [
        {"type": "message", "role": "user", "content": "I need help with my cluster."},
        {"type": "message", "role": "assistant", "content": "Let's take a look."},
    ]
)

  4. Takip talebinde oturumu yeniden yükleyin ve bağlamı yeniden oluşturmak için tam geçmişini okuyun:

    session = session_store.get("case-456")
# Request chronological order; list_items defaults to newest-first and auto-pages.
history = [item.data for item in session.list_items(order_by="create_time asc")]

REST API

İstemciler REST API'sini . /api/2.0/agents/session-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. Temsilciniz için bir oturum mağazası oluşturun:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores?session_store_name=support-agent-sessions" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"description": "Support agent conversation history"}'

  3. Tek bir konuşma için bir oturum başlatın. actor_id kime ait olduğudur; session_id bu konuşmayı benzersiz şekilde tanımlar:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions?session_id=case-456" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "customer-123"}'

  4. Ajan çalışırken bir konuşma sırası ekleyin:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions/case-456/items:append" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"items": [{"data": {"type": "message", "role": "user", "content": "I need help with my cluster."}}]}'

  5. Bağlamı yeniden inşa etmek için tarihi kronolojik sırayla okuyun:

    curl -G "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions/case-456/items" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" --data-urlencode "order_by=create_time asc"

İstemciler ayrıca en güncel öğenin kaldırılmasını, oturumun öğelerini temizlemeyi ve konuşmayı bağımsız bir kopyaya (isteğe bağlı olarak belirli bir öğeye kadar) aktarmayı destekler. Çocuk oturumları olan bir oturumu silmek, silmeyi onlara zincirleme olarak göndermek için bir güç seçeneği gerektirir (örneğin, session.delete(force=True)).

Bir ajan çerçevesinin oturumunu yönetilen oturumlarla destekleyin

OpenAI Agent SDK ve Claude Agent SDK gibi ajan çerçeveleri, bir çalışmanın başında konuşma geçmişini okur ve sonunda yeni öğeler ekler. Oturum mağazası doğrudan bu kalıba uyum sağlıyor:

Çerçeve operasyonu Oturum deposu çağrısı
Tarih okuyun list_items kronolojik sırayla (order_by="create_time asc")
Sıra öğeleri ekle append Yeni ürünler
Son öğeyi geri al pop En Son Ürün
İpi temizleyin clear Oturumun maddeleri

Kapsam ve erişim

Yönetilen oturumlar, oturumun öğelerini opak, JSON uyumlu değerler olarak saklar: hizmet, ajanınızın veya çerçevenizin eklediği her şeyi yorumlamadan devam eder ve geri döndürür. Çalıştırmalar, denetim noktaları veya onaylar gibi yürütme denetimi kaynaklarını birinci sınıf kavramlar olarak eklemez; ancak bu tür bir durumu serileştiren bir çerçeve, bunu öğeler olarak kalıcı hale getirebilir.

Oturum depoları çalışma alanı kapsamındadır ve erişim depo düzeyinde yetkilendirilir. ve actor_idmetadata alanları yalnızca gruplama ve filtrelemeyi destekler; erişim tanımazlar veya kısıtlamazlar. actor_id öğesini, model veya kullanıcı tarafından sağlanan bir değer yerine güvenilir uygulama bağlamından ayarlayın.

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 (session_store.grant_permission(principal_id)) ona erişim izni verin.

Yönetilen oturumlar ve yönetilen bellek bağımsızdır. Bir oturum veya oturum deposunu silmek, bellek deposunda tutulan belleği silmez.

Sonraki Adımlar

  • Last updated on