Remarque
L’accès à cette page requiert une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page requiert une autorisation. Vous pouvez essayer de modifier des répertoires.
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-agentbricks0.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
WRITEet 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
READouWRITEpour utiliser le magasin. - Un utilisateur ou un principal de service qui possède
READouWRITEpeut 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. |