Ajan belleği ve oturum depoları için izinleri yönetin

Important

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

Ajan bellek depoları ve oturum depoları aynı depo düzeyindeki izin modelini kullanır. Bir izin, depo içeriğine uygulanır: bir bellek deposundaki her bellek girişi veya oturum deposundaki her oturum ve oturum öğesi.

Bir Azure Databricks kullanıcısına veya hizmet sorumlusuna erişim verebilirsiniz. Bir kullanıcıyı e-posta ile ve bir hizmet sorumlusunu uygulama (istemci) kimliğiyle tanımlayın. Mağaza izinlerinde grup desteği yok.

Requirements

• Mevcut bellek deposu veya oturum deposu.
• Agent Bricks CLI veya AgentKit SDK örnekleri için Python 3.10 veya üzeri ve databricks-agentbricks 0.8.0 or above gereklidir.

Mağaza düzeyinde erişim modeli

Depo güvenlik sınırıdır. session_id, path, metadata ve actor_id gibi alanlar verileri düzenler ve filtreler, ancak erişimi kısıtlamazlar. Mağaza erişimine sahip bir principal, mağazadaki her aktör için veriye erişebilir. Tenant’lar veya kullanıcılar arasında verileri izole etmek için, her güvenlik sınırı için ayrı bir veri deposu oluşturun.

Mağaza izinleri aşağıdaki seviyelere sahiptir:

İzin	Depo verilerini oku	Mağaza verilerini yaz
READ	Yes	No
WRITE	Yes	Yes. WRITE içerir READ.
Erişim yok	No	No. Bu durumu veremezsiniz. Bir asıl öğenin açık erişimini kaldırmak için Revoke işlemini kullanın. Get operasyonu bu durumu PERMISSION_LEVEL_UNSPECIFIED olarak bildiriyor.

Yalnızca mağaza oluşturucu ve çalışma alanı yöneticileri izinleri yönetebilir:

• Mağaza oluşturucu varsayılan WRITE erişime sahiptir ve izinleri verebilir, listeleyebilir ve iptal edebilir. Yaratıcının sahipliğini iptal edemezsiniz.
• Bir çalışma alanı yöneticisi, çalışma alanındaki herhangi bir store üzerinde izinleri verebilir, listeleyebilir ve iptal edebilir. Çalışma alanı yöneticisi olmak tek başına veri erişimi vermez. Mevcut veri erişimi olmayan bir yönetici, mağazayı kullanabilmek için kendisine READ veya WRITE erişimi vermelidir.
• READ veya WRITE ile bir kullanıcı veya hizmet sorumlusu mağazayı kullanabilir, ancak izinlerini yönetemez.

Miras alınan erişim, arka plandaki Lakebase projesindeki bir Postgres rolüne üyelikten gelir; örneğin databricks_superuser. Mağaza izni işlemleri bu rol üyeliklerini değiştirmez. Postgres rolleri için izinleri yönet'e bakın.

İzin işlemleri

Depo izinleri dört işlemi destekler:

Operation	Behavior
Grant	Hibe READ veya WRITE tek bir kullanıcıya ya da hizmet sorumlusuna verilir. Operasyon idempotenttir. WRITE olan bir sorumluya READ verilmesi, mevcut iznin düzeyini düşürmez.
Get	Kimliği doğrulanmış herhangi bir çağıran Get'i çalıştırabilir. Yalnızca arayanın etkili iznini, örtük yaratıcı erişimi ve miras erişimi dahil olmak üzere geri döndürür. Çağıran tarafın erişimi olmadığında PERMISSION_LEVEL_UNSPECIFIED döndürür.
List	Kullanıcılara ve hizmet sorumlularına açık izinleri döndürür. Yaratıcının örtük erişimini, çalışma alanı yöneticisi yönetim yetkisini ve miras alınan erişimi dışlar. Boş bir sonuç, hiçbir güvenlik sorumlusunun depoya erişemeyeceğini kanıtlamaz.
Revoke	Hem açık READ hem de WRITE izinlerini tek bir özneden kaldırır. Operasyon idempotenttir. Mülkiyeti veya devralınan erişimi kaldırmaz.

List REST API, varsayılan sayfa boyutu olan 100 hibse kullanır ve sayfa başına 1.000'e kadar hibe destekler. AgentKit SDK, tüm sayfaları otomatik olarak takip eder. Agent Bricks CLI ile, her sayfayı döndürmek için --all kullanın.

Bir prensipali WRITE düzeyinden READ düzeyine düşürmek için mevcut yetkiyi iptal edin ve ardından READ yetkisini verin. Bu işlemler atomik değildir, bu yüzden öznenin iki çağrı arasında açık bir erişimi yoktur.

Mağaza izinlerini yönet

Aşağıdaki örnekler bir bellek deposunda izinleri yönetir. Bir oturum deposu için, Agent Bricks CLI'da session-stores/<store-name> yerine client.session_stores.get("<store-name>"), AgentKit SDK'da memory stores veya REST API yolunda sessions stores kullanın.

Ajan Tuğlalar

İzin komutları, diğer depo komutlarıyla aynı depo tanımlayıcılarını kabul eder. Bellek depoları bir depo kimliği, kaynak adı veya belirsiz olmayan görünen ad kabul eder. Oturum mağazaları bir mağaza adı veya kaynak adını kabul eder.

Kullanıcıya okuma erişimi vermek için aşağıdakileri çalıştırın:

agentbricks memory stores permissions grant <store-id> \
  --user teammate@example.com --permission READ

Bir hizmet sorumlusuna yazma erişimi vermek için aşağıdakini çalıştırın. service principal'ın uygulama kimliğini ilet:

agentbricks memory stores permissions grant <store-id> \
  --service-principal <application-id> --permission WRITE

Kendi geçerli izninizi almak için aşağıdakini çalıştırın:

agentbricks memory stores permissions get <store-id>

Tüm açık izinleri listelemek için, aşağıdakileri mağaza oluşturucu veya çalışma alanı yöneticisi olarak çalıştırın:

agentbricks memory stores permissions list <store-id> --all

Bir kullanıcının açık erişimini iptal etmek için aşağıdakileri çalıştırın. --yes seçeneği onay istemini atlar:

agentbricks memory stores permissions revoke <store-id> \
  --user teammate@example.com --yes

AgentKit SDK

İzin yöntemleri hem SessionStore hem de MemoryStore nesnelerinde mevcuttur. Aşağıdaki örnek, izin seviyesini ve sorumlu türünü açıkça parametre olarak geçirir:

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
store = client.memory_stores.get("<store-id>")

# Grant a user read access.
store.grant_permission(
    "teammate@example.com",
    principal_type="USER",
    permission="READ",
)

# Return the authenticated caller's effective permission.
permission = store.get_permission()
print(permission.principal.name, permission.permission)

# List every explicit grant.
for grant in store.list_permissions(page_size=100):
    print(grant.principal.name, grant.principal.principal_type, grant.permission)

# Remove the user's explicit READ and WRITE grants.
store.revoke_permission("teammate@example.com", principal_type="USER")

grant_permission() ve revoke_permission(), varsayılan principal type olarak SERVICE_PRINCIPAL kullanır. grant_permission(), varsayılan izin olarak WRITE kullanır. Kullanıcı erişimi veya salt okunur erişim verdiğinizde her iki argümanı açıkça iletin.

REST API

İzin endpoint'leri /api/2.0/agents/memory-stores/<store-id>/permissions altındadır. İstek gövdesi, bir kullanıcıyı USER ile ve bir hizmet sorumlusunu SERVICE_PRINCIPAL ile tanımlar.

DATABRICKS_HOST değerini, https:// dahil olmak üzere çalışma alanı URL'nize, DATABRICKS_TOKEN değerini de erişim tokenınıza ayarlayın.

Kullanıcıya okuma erişimi vermek için Grant işlemini çağırın:

curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions:grant" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": {"principal_type": "USER", "name": "teammate@example.com"},
    "permission": "READ"
  }'

Kimlik doğrulaması yapılan arayanın geçerli iznini almak için Get işlemini çağırın:

curl "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions/self" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Açık izinleri listelemek için, List işlemini mağaza oluşturucu veya bir workspace admin'i olarak çağırın:

curl "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions?page_size=100" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Kullanıcının açıkça verilmiş erişimini iptal etmek için Revoke işlemini çağırın:

curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions:revoke" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": {"principal_type": "USER", "name": "teammate@example.com"}
  }'

Grant ve Revoke işlemleri izin nesnesi döndürmez. Bir değişikliği doğrulamak için, mağaza oluşturucu veya workspace yöneticisi olarak List'i çalıştırın. Etkili erişimi kontrol etmek için, etkilenen principal olarak kimlik doğrulamayı yapın ve Get çalıştırın.

Ajan dağıtımı ile yönetilen izinler

Bir ajan projesi bir bellek veya oturum deposu ilan ettiğinde, agentbricks deploy dağıtılan uygulamanın hizmet sorumlusuna o depoya erişim verir. Daha sonraki bir dağıtım işlemi, elle iptal ettiğiniz erişimi geri getirebilir.

Bir mağazanın bağlamasının çözülmesi, ajan projesinden bağlamayı kaldırır. Uygulamanın hizmet sorumlusuna önceden verilen erişimi iptal etmez. Bu erişimi kaldırmak için Yetkiyi Geri Alma işlemini kullanın.

Ek kaynaklar

Resource	Description
Aracı belleği	Ajanlara, ayrı konuşmalarda kalıcı uzun vadeli bir hafıza verin.
Agent oturumları	Bir ajanın konuşma geçmişini saklayarak turlar arasında etkileşimi sürdürebilsin.