Verwalten Sie Berechtigungen für Agentengedächtnis und Sitzungsspeicher-Stores

Important

Dieses Feature befindet sich in der Betaversion. Um es zu verwenden, muss ein Workspace-Administrator Agent Memory Sessions auf der Seite Vorschau aktivieren. Siehe Manage Azure Databricks Previews.

Agentenspeicher und Sitzungsspeicher verwenden dasselbe Speicher-Level-Berechtigungsmodell. Eine Berechtigung gilt für den Inhalt des Stores: für jeden Speichereintrag in einem Speicher bzw. für jede Sitzung und jedes Sitzungselement in einem Sitzungsspeicher.

Du kannst einem Azure Databricks-Nutzer oder Service Principal Zugriff gewähren. Identifizieren Sie einen Benutzer per E-Mail und einen Service-Principal anhand seiner Anwendungs-(Client-)ID. Store-Berechtigungen unterstützen keine Gruppen.

Anforderungen

  • Ein bestehender Speicherspeicher oder Sitzungsspeicher.
  • Für die Agent Bricks CLI- oder AgentKit-SDK-Beispiele: Python 3.10 oder höher und AgentKit databricks-agentbricks 0.8.0 oder höher.

Zugriffsmodell auf Store-Ebene

Der Store ist die Sicherheitsgrenze. Felder wie actor_id, session_id, , pathsowie metadata organisieren und filtern Daten, aber sie schränken den Zugriff nicht ein. Ein Sicherheitsprinzipal mit Store-Zugriff kann auf Daten für jeden Akteur im Store zugreifen. Um Daten zwischen Tenants oder Benutzern zu isolieren, erstellen Sie für jede Sicherheitsgrenze einen separaten Datenspeicher.

Store-Berechtigungen haben folgende Stufen:

Erlaubnis Speicherdaten auslesen Speicherdaten schreiben
READ Yes No
WRITE Yes Yes. WRITE enthält READ.
Kein Zugriff No No. Du kannst diesen Status nicht vergeben. Um den expliziten Zugriff eines Sicherheitsprinzipals zu entfernen, verwenden Sie die Operation Revoke. Die Operation Get meldet diesen Zustand als PERMISSION_LEVEL_UNSPECIFIED.

Nur der Store-Ersteller und die Workspace-Administratoren können Berechtigungen verwalten:

  • Der Store-Ersteller hat impliziten WRITE Zugriff und kann Berechtigungen gewähren, auflisten und widerrufen. Du kannst dem Ersteller den Besitz nicht entziehen.
  • Ein Workspace-Administrator kann Berechtigungen für jeden Store im Workspace gewähren, listen und widerrufen. Workspace-Administrator zu sein gewährt an sich keinen Datenzugriff. Ein Administrator ohne vorhandenen Datenzugriff muss sich selbst READ oder WRITE gewähren, um den Store zu nutzen.
  • Ein Benutzer oder Dienstprinzipal mit READ oder WRITE kann den Store nutzen, kann aber dessen Berechtigungen nicht verwalten.

Der vererbte Zugang ergibt sich durch die Mitgliedschaft in einer Postgres-Rolle im zugrunde liegenden Lakebase-Projekt, wie zum Beispiel databricks_superuser. Store-Permission-Operationen ändern diese Rollenmitgliedschaften nicht. Siehe Berechtigungen verwalten für Postgres-Rollen.

Berechtigungsoperationen

Store-Berechtigungen unterstützen vier Operationen:

Operation Behavior
Grant Gewährt READ oder WRITE einem Nutzer oder Dienstprinzipal. Der Vorgang ist idempotent. Die Erteilung von READ an einen Prinzipal, der bereits über WRITE verfügt, stuft die bestehende Berechtigung nicht herab.
Get Jeder authentifizierte Anrufer kann Get ausführen. Es gibt nur die effektive Berechtigung des Aufrufers zurück, einschließlich implizitem Creator-Zugriff und geerbtem Zugriff. Es wird PERMISSION_LEVEL_UNSPECIFIED zurückgegeben, wenn der Anrufer keinen Zugriff hat.
List Gibt explizite Zuteilungen an Nutzer und Dienstprinzipale zurück. Er schließt den impliziten Zugriff des Erstellers, die Verwaltungsbefugnis des Workspace-Admins und den vererbten Zugriff aus. Ein leeres Ergebnis beweist nicht, dass kein Principal Zugriff auf den Store hat.
Revoke Entfernt sowohl explizite READ- als auch WRITE-Berechtigungen von einem Prinzipal. Der Vorgang ist idempotent. Es entfernt weder den Besitz noch den geerbten Zugriff.

Die List REST API verwendet eine Standardseitengröße von 100 Grants und unterstützt bis zu 1.000 Grants pro Seite. Das AgentKit SDK erfasst alle Seiten automatisch. Mit der Agent Bricks CLI kann man mit --all alle Seiten ausgeben.

Um einen Principal von WRITE auf READ herabzustufen, widerrufen Sie die bestehende Zuteilung und gewähren Sie dann READ. Diese Operationen sind nicht atomar, sodass der Sicherheitsprinzipal zwischen den beiden Aufrufen keinen expliziten Zugriff hat.

Store-Berechtigungen verwalten

Die folgenden Beispiele verwalten Berechtigungen in einem Arbeitsspeicher. Für einen Session-Store verwenden Sie sessions stores anstelle von memory stores im Agent Bricks CLI, client.session_stores.get("<store-name>") im AgentKit SDK oder session-stores/<store-name> im REST-API-Pfad.

Agent Bricks

Die Berechtigungsbefehle akzeptieren dieselben Store-Kennungen wie die anderen Store-Befehle. Speicher akzeptieren eine Speicher-ID, einen Ressourcennamen oder einen eindeutigen Anzeigenamen. Session-Stores akzeptieren einen Store- oder Ressourcennamen.

Um einem Benutzer Lesezugriff zu gewähren, führen Sie Folgendes aus:

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

Um einem Service Principal Schreibzugriff zu gewähren, führen Sie Folgendes aus. Geben Sie die Anwendungs-ID (Client-ID) des Service-Principals weiter:

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

Um Ihre eigene effektive Berechtigung zu erhalten, führen Sie Folgendes durch:

agentbricks memory stores permissions get <store-id>

Um alle expliziten Grants aufzulisten, führe Folgendes als Store-Ersteller oder Workspace-Administrator aus:

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

Um den expliziten Zugriff eines Nutzers zu widerrufen, führen Sie Folgendes aus. Die --yes Option überspringt die Bestätigungsaufforderung:

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

AgentKit SDK

Die Berechtigungsmethoden sind sowohl auf MemoryStore- als auch auf SessionStore-Objekten verfügbar. Das folgende Beispiel übergibt explizit die Berechtigungsstufe und den Prinzipaltyp:

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() und revoke_permission() verwenden SERVICE_PRINCIPAL als Standard-Principal-Typ. grant_permission() verwendet WRITE als Standardberechtigung. Geben Sie beide Argumente explizit durch, wenn Sie Benutzerzugriff oder Nur-Lesezugriff gewähren.

REST API

Die Berechtigungsendpunkte liegen unter /api/2.0/agents/memory-stores/<store-id>/permissions. Der Anfragetext identifiziert einen Benutzer mit USER und einen service principal mit SERVICE_PRINCIPAL.

Setzen Sie DATABRICKS_HOST auf Ihre Workspace-URL, einschließlich https://, und DATABRICKS_TOKEN auf Ihr Zugangstoken.

Um einem Benutzer Lesezugriff zu gewähren, rufen Sie die Grant-Operation auf:

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"
  }'

Um die effektive Berechtigung des authentifizierten Anrufers zu erhalten, rufen Sie die Operation „Get“ auf:

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

Um explizite Genehmigungen aufzulisten, rufen Sie den Vorgang „List“ als Store-Ersteller oder Workspace-Administrator auf:

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

Um den expliziten Zugriff des Nutzers zu widerrufen, rufen Sie die Operation Revoke auf:

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"}
  }'

Die Grant- und Revoke-Operationen geben kein Berechtigungsobjekt zurück. Um eine Änderung zu verifizieren, führe List als Store-Ersteller oder Workspace-Administrator aus. Um den effektiven Zugriff zu überprüfen, authentifiziere dich als betroffener Principal und führe Get aus.

Berechtigungen, die durch die Agentenbereitstellung verwaltet werden

Wenn ein Agentenprojekt einen Speicher- oder Sitzungsspeicher deklariert, gewährt agentbricks deploy dem Service-Principal der bereitgestellten App Zugriff auf diesen Speicher. Eine spätere Bereitstellung kann den Zugriff wiederherstellen, den du manuell widerrufen hast.

Das Entbinden eines Stores entfernt die Bindung aus dem Agentenprojekt. Sie widerruft keinen dem Dienstprinzipal der App bereits gewährten Zugriff. Verwenden Sie die Operation Widerrufen, um diesen Zugriff zu entfernen.

Zusätzliche Ressourcen

Resource Description
Agentspeicher Geben Sie den Agenten ein Langzeitgedächtnis, das über verschiedene Gespräche hinweg erhalten bleibt.
Agent-Sitzungen Speichere die Gesprächshistorie eines Agenten, damit er eine Interaktion über Runden hinweg fortsetzen kann.
  • Zuletzt aktualisiert um