Gestion des permissions pour la mémoire des agents et les stockages de session

Important

Cette fonctionnalité est en version bêta. Pour l’utiliser, un administrateur d’espace de travail doit activer Agent Memory Sessions depuis la page Previews. Consultez Gérer les préversions d’Azure Databricks.

Les mémoires d’agent et de session utilisent le même modèle de permissions 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 chaque élément de session dans un magasin de sessions.

Vous pouvez accorder l’accès à un utilisateur ou un principal de service Azure Databricks. Identifiez un utilisateur par email et un principal de service par son identifiant d’application (client). Les autorisations de Store ne prennent pas en charge les groupes.

Spécifications

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

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

Le magasin est la délimitation de sécurité. Des champs comme 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 entité du magasin. Pour isoler les données entre locataires ou utilisateurs, créez un magasin de données séparé pour chaque délimitation de sécurité.

Les autorisations du Store ont les niveaux suivants :

Autorisation Lire les données du magasin Écrire les données du magasin
READ Yes No
WRITE Yes Yes. WRITE inclut READ.
Pas d’accès No No. 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 indique cet état comme PERMISSION_LEVEL_UNSPECIFIED.

Seuls le créateur du magasin et les administrateurs de l’espace de travail peuvent gérer les autorisations :

  • Le créateur du magasin dispose d’un accès implicite WRITE et peut accorder, lister et révoquer des permissions. Vous ne pouvez pas révoquer le statut de propriétaire du créateur.
  • Un administrateur d’espace de travail peut accorder, lister et révoquer des autorisations sur n’importe quelle boutique de l’espace de travail. Être administrateur d’espace de travail ne garantit pas en soi l’accès aux données. Un administrateur sans accès aux données existantes doit s’accorder lui-même READ ou WRITE pour utiliser le magasin.
  • Un utilisateur ou un principal de service qui possède READ ou WRITE peut utiliser le store 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 du magasin ne modifient pas ces appartenances aux rôles. Voir la section « Gérer les autorisations pour les rôles Postgres ».

Opérations d’autorisation

Les autorisations du magasin prennent en charge quatre opérations :

Operation Behavior
Grant Accorde READ ou WRITE à un utilisateur ou un principal de service. L’opération est idempotente. Accorder READ à un principal qui dispose déjà de WRITE ne passe pas à une version antérieure l’autorisation existante.
Get Tout appelant authentifié peut exécuter Get. Il ne renvoie que l’autorisation effective de l’appelant, y compris l’accès implicite du créateur et l’accès hérité. Il renvoie PERMISSION_LEVEL_UNSPECIFIED lorsque l’appelant n’a pas accès.
List Renvoie les autorisations explicites aux utilisateurs et aux principaux de service. Elle exclut l’accès implicite du créateur, l’autorité de gestion des administrateurs de l’espace de travail et l’accès hérité. Un résultat vide ne prouve pas qu’aucun principal ne peut accéder au magasin.
Revoke Supprime à la fois les autorisations explicites READ et WRITE d’un principal. L’opération est idempotente. Elle ne retire pas la propriété ni l’accès hérité.

L’API REST List utilise une taille de page par défaut de 100 autorisations et prend en charge jusqu’à 1 000 autorisations par page. Le SDK AgentKit assure automatiquement le suivi de toutes les pages. Avec la CLI Agent Bricks, utilisez --all pour renvoyer toutes les pages.

Pour rétrograder un principal de WRITE à READ, révoquez l’autorisation existante puis accordez READ. Ces opérations ne sont pas atomiques, donc le principal n’a pas d’accès explicite entre les deux appels.

Gérer les autorisations du magasin

Les exemples suivants gèrent les permissions sur un stockage mémoire. Pour un stockage de session, utilisez sessions stores plutôt que memory stores dans la CLI Agent Bricks, client.session_stores.get("<store-name>") dans le SDK AgentKit ou session-stores/<store-name> dans le chemin de l’API REST.

Agent Bricks

Les commandes d’autorisation acceptent les mêmes identifiants de magasin que les autres commandes de magasin. Les mémoires acceptent un ID de magasin, un nom de ressource ou un nom d’affichage non ambigu. Les magasins de sessions acceptent un nom de magasin ou un nom de ressource.

Pour accorder un accès à la lecture d’un utilisateur, exécutez les instructions suivantes :

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

Pour accorder un accès d’écriture à un principal de service, exécutez la commande suivante. Transmettez l’ID d’application du principal de service :

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

Pour obtenir votre propre autorisation effective, exécutez la commande suivante :

agentbricks memory stores permissions get <store-id>

Pour lister toutes les autorisations explicites, utilisez ce qui suit en tant que créateur de la boutique ou administrateur de l’espace de travail :

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

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

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

AgentKit SDK

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

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 par défaut. grant_permission() utilise WRITE comme permission par défaut. Passez explicitement les deux arguments lorsque vous accordez un accès utilisateur ou un accès en lecture seule.

REST API

Les points de terminaison d’autorisation sont sous /api/2.0/agents/memory-stores/<store-id>/permissions. Le corps de la requête identifie un utilisateur avec USER et un principal de service avec SERVICE_PRINCIPAL.

Définissez DATABRICKS_HOST sur l’URL de votre espace de travail, incluant https://, et DATABRICKS_TOKEN sur votre jeton d’accès.

Pour accorder un accès à la lecture d’un utilisateur, appelez l’opération Grant :

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 :

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

Pour lister les autorisations explicites, appelez l’opération List en tant que créateur du store ou administrateur d’espace de travail :

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 :

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 Accorder et Révoquer ne renvoient pas un objet de permission. Pour vérifier une modification, exécutez List en tant que créateur du magasin ou administrateur de l’espace de travail. Pour vérifier l’accès effectif, authentifiez-vous en tant que principal concerné et exécutez Get.

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

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

La dissociation d’un magasin supprime la liaison du projet d’agent. Elle ne révoque pas un accès déjà accordé au principal de service de l’application. Utilisez l’opération Révocation pour supprimer cet accès.

Ressources supplémentaires

Resource Description
Mémoire de l’agent Donnez aux agents une mémoire à long terme qui persiste à travers des conversations distinctes.
Sessions d’agents Stockez l’historique des conversations d’un agent afin qu’il puisse reprendre une interaction d’un tour à l’autre.