Gérer les autorisations pour la mémoire de l'agent et les magasins de session

info

Bêta

Cette fonctionnalité est en version Bêta. Pour l'utiliser, un administrateur de workspace doit activer Sessions mémoire d'agent depuis la page Aperçus . Consultez Gérer les aperçus Databricks.

Les mémoires d’agent et les magasins de sessions utilisent le même modèle d’autorisation au niveau du magasin. Une autorisation s’applique au contenu du magasin : chaque entrée de mémoire dans un magasin de mémoire, ou chaque session et élément de session dans un magasin de session.

Vous pouvez accorder l'accès à un utilisateur Databricks ou à un service principal. Identifiez un utilisateur par e-mail et un service principal par son ID d'application (client). Les autorisations de stockage ne prennent pas en charge les groupes.

Exigences

Un magasin de mémoire ou un magasin de session existant.
Pour les exemples Agent Bricks CLI ou AgentKit SDK, Python 3.10 ou supérieur et databricks-agentbricks 0.8.0 ou supérieur.

Modèle d'accès au niveau du magasin

Le magasin est la limite de sécurité. Des champs tels que actor_id, session_id, path et metadata organisent et filtrent les données, mais ils ne restreignent pas l’accès. Un principal ayant accès au magasin peut accéder aux données de chaque acteur du magasin. Pour isoler les données entre les tenants ou les utilisateurs, créez un magasin distinct pour chaque limite de sécurité.

Les autorisations de stockage ont les niveaux suivants :

Autorisation	Lire les données du magasin	Écrire les données de stockage
`READ`	Oui	Non
`WRITE`	Oui	Oui. `WRITE` inclut `READ`.
Aucun accès	Non	Non. Vous ne pouvez pas accorder cet état. Pour supprimer l'accès explicite d'un principal, utilisez l'opération Revoke. L'opération Get signale cet état comme `PERMISSION_LEVEL_UNSPECIFIED`.

Autorisation	Lire les données du magasin	Écrire les données de stockage
`READ`	Oui	Non
`WRITE`	Oui	Oui. `WRITE` inclut `READ`.
Aucun accès	Non	Non. Vous ne pouvez pas accorder cet état. Pour supprimer l'accès explicite d'un principal, utilisez l'opération Revoke. L'opération Get signale cet état comme `PERMISSION_LEVEL_UNSPECIFIED`.

Seuls le créateur du magasin et les administrateurs du Workspace peuvent gérer les autorisations :

Le créateur du stockage a un accès WRITE implicite et peut accorder, lister et révoquer des autorisations. Vous ne pouvez pas révoquer la propriété du créateur.
Un administrateur de workspace peut accorder, répertorier et révoquer des permissions sur n'importe quel magasin du workspace. Être administrateur de workspace ne donne pas en soi accès aux données. Un administrateur sans accès aux données existantes doit s'accorder READ ou WRITE pour utiliser le store.
Un utilisateur ou un Service Principal avec READ ou WRITE peut utiliser le magasin mais ne peut pas gérer ses permissions.

L’accès hérité provient de l’appartenance à un rôle Postgres dans le projet Lakebase sous-jacent, tel que databricks_superuser. Les opérations d’autorisation de stockage ne modifient pas ces appartenances à un rôle. Voir Gérer les autorisations pour les rôles Postgres.

Opérations d'autorisation

Les autorisations de stockage prennent en charge quatre opérations :

Opérations	Comportement
Accorder	Accorde `READ` ou `WRITE` à un utilisateur ou à un Service Principal. L’opération est idempotente. L’octroi de `READ` à un principal disposant de `WRITE` ne rétrograde pas l’octroi existant.
Obtenir	Tout appelant authentifié peut exécuter Get. Elle ne renvoie que l'autorisation effective de l'appelant, y compris l'accès implicite du créateur et l'accès hérité. Elle renvoie `PERMISSION_LEVEL_UNSPECIFIED` lorsque l'appelant n'a aucun accès.
Liste	Renvoie des accords explicites aux utilisateurs et aux services principaux. Elle exclut l'accès implicite du créateur, l'autorité de gestion de l'administrateur de workspace et l'accès hérité. Un résultat vide ne prouve pas qu’aucun mandant ne peut accéder au magasin.
Révoquer	Supprime les attributions explicites `READ` et `WRITE` d'un principal. L'opération est idempotente. Elle ne supprime pas la propriété ni l'accès hérité.

Opérations	Comportement
Accorder	Accorde `READ` ou `WRITE` à un utilisateur ou à un Service Principal. L’opération est idempotente. L’octroi de `READ` à un principal disposant de `WRITE` ne rétrograde pas l’octroi existant.
Obtenir	Tout appelant authentifié peut exécuter Get. Elle ne renvoie que l'autorisation effective de l'appelant, y compris l'accès implicite du créateur et l'accès hérité. Elle renvoie `PERMISSION_LEVEL_UNSPECIFIED` lorsque l'appelant n'a aucun accès.
Liste	Renvoie des accords explicites aux utilisateurs et aux services principaux. Elle exclut l'accès implicite du créateur, l'autorité de gestion de l'administrateur de workspace et l'accès hérité. Un résultat vide ne prouve pas qu’aucun mandant ne peut accéder au magasin.
Révoquer	Supprime les attributions explicites `READ` et `WRITE` d'un principal. L'opération est idempotente. Elle ne supprime pas la propriété ni l'accès hérité.

L’API REST List utilise une taille de page default de 100 octroi et prend en charge jusqu’à 1 000 octrois par page. Le SDK AgentKit suit automatiquement toutes les pages. Avec l’Agent Bricks CLI, utilisez --all pour retourner chaque page.

Pour rétrograder un principal de WRITE à READ, révoquez l'octroi existant, puis accordez READ. Ces opérations ne sont pas atomiques, de sorte que le principal n'a aucun accès explicite entre les deux appels.

Gérer les autorisations de magasin

Les exemples suivants gèrent les autorisations sur un magasin de mémoire. Pour un magasin de session, utilisez sessions stores au lieu de memory stores dans Agent Bricks CLI, client.session_stores.get("<store-name>") dans le kit SDK AgentKit ou session-stores/<store-name> dans le chemin d’API REST.

Agent Bricks CLI
AgentKit SDK
REST API

Les commandes d’autorisation acceptent les mêmes identifiants de stockage que les autres commandes de stockage. Les stockages en mémoire acceptent un ID de stockage, un nom de ressource ou un nom d'affichage sans ambiguïté. Les stockages de session acceptent un nom de stockage ou un nom de ressource.

Pour accorder un accès en lecture à un utilisateur, exécutez ce qui suit :

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

Pour accorder à un service principal un accès en écriture, exécutez ce qui suit. Transmettez l'ID de l'application du service principal :

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

Pour obtenir votre propre autorisation effective, exécutez ce qui suit :

Bash
agentbricks memory stores permissions get <store-id>

Pour répertorier toutes les autorisations explicites, exécutez la commande suivante en tant que créateur du magasin ou administrateur de workspace :

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

Pour révoquer l'accès explicite d'un utilisateur, exécutez la commande suivante. L’option --yes ignore l’invite de confirmation :

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

Les méthodes d’autorisation sont disponibles sur les objets MemoryStore et SessionStore. L’exemple suivant transmet explicitement le niveau d’autorisation et le type de principal :

Python
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() et revoke_permission() utilisent SERVICE_PRINCIPAL comme type principal default. grant_permission() utilise WRITE comme autorisation par default. Passez explicitement les deux arguments lorsque vous accordez un accès utilisateur ou un accès en lecture seule.

Les Endpoint d'autorisation se trouvent sous /api/2.0/agents/memory-stores/<store-id>/permissions. Le corps de la requête identifie un utilisateur avec USER et un Service Principal avec SERVICE_PRINCIPAL.

Définissez DATABRICKS_HOST sur l'URL de votre workspace, en incluant https://, et DATABRICKS_TOKEN sur votre jeton d'accès.

Pour accorder un accès en lecture à un utilisateur, appelez l'opération Grant :

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

Pour obtenir l'autorisation effective de l'appelant authentifié, appelez l'opération Get :

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

Pour répertorier les autorisations explicites, appelez l'opération List en tant que créateur du magasin ou administrateur de workspace :

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

Pour révoquer l'accès explicite de l'utilisateur, appelez l'opération Revoke :

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

Les opérations Grant et Revoke ne renvoient pas d'objet d'autorisation. Pour vérifier une modification, exécutez List en tant que créateur du stockage ou administrateur du workspace. Pour vérifier l'accès effectif, authentifiez-vous en tant que mandataire concerné et exécutez Get.

Permissions gérées par le déploiement de l’agent

Quand un projet d’agent déclare un stockage de mémoire ou de session, agentbricks deploy accorde au service principal de l’application déployée l’accès à ce stockage. Un déploiement ultérieur peut restaurer l’accès que vous avez révoqué manuellement.

La suppression de la liaison d'un magasin supprime la liaison du projet d'agent. Cela ne révoque pas l'accès qui a déjà été accordé au Service Principal de l'application. Utilisez l'opération Revoke pour supprimer cet accès.

Ressources supplémentaires

- Mémoire de l'agent
- Donnez aux agents une mémoire à long terme qui persiste au-delà des conversations séparées.
- Sessions d'agent
- Stockez l'historique des conversations d'un agent afin qu'il puisse reprendre une interaction au cours des tours.

Exigences​

Modèle d'accès au niveau du magasin​

Opérations d'autorisation​

Gérer les autorisations de magasin​

Permissions gérées par le déploiement de l’agent​

Ressources supplémentaires​