Authentification pour les agents IA

Les agents IA doivent souvent s’authentifier auprès d’autres ressources pour effectuer des tâches. Par exemple, un agent déployé peut avoir besoin d’accéder à un index Recherche vectorielle pour interroger des données non structurées, un point de terminaison de service pour appeler un modèle de base ou des fonctions catalogue Unity pour exécuter une logique personnalisée.

Cette page traite des méthodes d’authentification pour les agents déployés sur Databricks Apps. Pour les agents déployés sur des points de terminaison du service de modèle, consultez Authentification des agents IA (Modèle servant).

Databricks Apps fournit deux méthodes d’authentification pour les agents. Chaque méthode sert différents cas d’usage :

Vous pouvez combiner les deux méthodes dans un seul agent. Par exemple, utilisez l’autorisation d’application pour accéder à un index de recherche vectorielle partagée tout en utilisant l’autorisation utilisateur pour interroger des tables spécifiques à l’utilisateur.

Configurer l’authentification avec l’interface utilisateur de l’espace de travail ou des lots d'automatisation déclarative

Vous pouvez configurer tous les paramètres d’authentification de deux façons :

• Interface utilisateur de l’espace de travail : modifiez l’application et gérez les ressources et les étendues à partir de l’étape Configurer . Recommandé lorsque vous effectuez une itération sur une application unique dans l’espace de travail.
• Automation déclarative des bundles : déclarez des ressources, des périmètres, et des variables d’environnement dans un databricks.yml fichier et déployez avec databricks bundle deploy. Recommandé lorsque vous souhaitez utiliser le contrôle de version basé sur Git, CI/CD ou envoyer le même agent entre les espaces de travail. Tous les modèles d’agent sont fournis avec un databricks.yml.

Les deux chemins produisent la même configuration d’exécution. Le reste de cette page affiche chaque instruction dans les deux formulaires afin de pouvoir en sélectionner un et rester cohérent dans votre projet.

Pour ajouter une ressource à l’application via l’un ou l’autre chemin d’accès, vous devez disposer Can Manage d’autorisations sur la ressource et l’application.

Pour obtenir la référence complète de l’offre groupée, consultez la ressource d’application et app.resources. Pour une procédure pas à pas pour bundle de bout en bout, consultez Gérer les applications Databricks en utilisant des bundles d'automatisation déclaratifs.

Autorisation de l’application

Par défaut, Databricks Apps s’authentifie à l’aide de l’autorisation d’application. Databricks crée automatiquement un principal de service lorsque vous créez l’application, et agit comme l’identité de l’application.

Tous les utilisateurs qui interagissent avec l’application partagent les mêmes autorisations définies pour le principal de service. Ce modèle fonctionne bien lorsque vous souhaitez que tous les utilisateurs voient les mêmes données ou lorsque l’application effectue des opérations partagées non liées aux contrôles d’accès spécifiques à l’utilisateur.

Pour plus d’informations sur l’autorisation d’application, consultez Autorisation d’application.

Accorder des autorisations à l’expérience MLflow

Votre agent a besoin d’accéder à une expérience MLflow pour consigner les traces et les résultats d’évaluation. Accordez au principal de service Can Edit l’autorisation pour l’expérience.

Interface utilisateur de l’espace de travail

1. Cliquez sur Modifier sur la page d’accueil de votre application.
2. Accédez à l’étape Configurer .
3. Dans la section Ressources de l’application , ajoutez la ressource d’expérience MLflow avec Can Edit autorisation.

Consultez Ajouter une ressource d’expérience MLflow à une application Databricks.

Paquets d'Automatisation déclarative

1. Déclarez l'expérience sous la liste resources dans databricks.yml de votre application. L’affectation name à la ressource est référencée ultérieurement lorsque vous configurez des variables d’environnement.

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   

2. Redéployez l’offre groupée :

   databricks bundle deploy
   databricks bundle run my_agent
   

Consultez app.resources.experiment pour tous les champs.

Accorder des autorisations à d’autres ressources Databricks

Si votre agent utilise d’autres ressources Databricks, telles que Genie Spaces, les index de recherche vectorielle ou les entrepôts SQL, accordez les autorisations du principal de service sur chacune d’elles.

Pour accéder au registre d’invites, accordez les autorisations CREATE FUNCTION, EXECUTE et MANAGE sur le schéma du catalogue Unity pour stocker des invites.

Lorsque vous accordez l’accès aux ressources du catalogue Unity, vous devez également accorder des autorisations à toutes les ressources dépendantes en aval. Par exemple, si vous accordez l’accès à un espace Génie, vous devez également accorder l’accès à ses tables, entrepôts SQL et fonctions catalogue Unity sous-jacentes.

Interface utilisateur de l’espace de travail

Ajoutez des ressources à l’application via la section Ressources de l’application lorsque vous créez ou modifiez l’application dans l’espace de travail Databricks.

1. Cliquez sur Modifier sur la page d’accueil de votre application.
2. Accédez à l’étape Configurer .
3. Dans les ressources d’application, cliquez sur + Ajouter une ressource pour chaque ressource que l’agent utilise et définissez l’autorisation.

Consultez Ajouter des ressources à une application Databricks pour obtenir la liste complète des ressources et captures d’écran prises en charge.

Paquets d'Automatisation déclarative

1. Déclarez chaque ressource utilisée par l’agent dans la resources liste sous votre application dans databricks.yml. L’exemple ci-dessous montre un agent qui utilise une expérience MLflow, un point de terminaison de service, un espace Génie, un entrepôt SQL, un index de recherche vectorielle, une fonction Catalogue Unity et une instance Lakebase. Chaque ressource name est référencée depuis config.env via value_from afin que l'agent reçoive l'identificateur résolu au moment de l'exécution.

   bundle:
     name: my_agent
   
   resources:
     apps:
       my_agent:
         name: 'my-agent'
         description: 'Custom agent deployed on Databricks Apps'
         source_code_path: ./
         config:
           command: ['uv', 'run', 'start-app']
           env:
             - name: MLFLOW_EXPERIMENT_ID
               value_from: 'experiment'
             - name: LAKEBASE_INSTANCE_NAME
               value_from: 'database'
   
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   
           - name: 'llm'
             serving_endpoint:
               name: 'databricks-claude-sonnet-4-5'
               permission: 'CAN_QUERY'
   
           - name: 'sales-genie'
             genie_space:
               space_id: '<genie-space-id>'
               permission: 'CAN_RUN'
   
           - name: 'warehouse'
             sql_warehouse:
               id: '<warehouse-id>'
               permission: 'CAN_USE'
   
           - name: 'docs-index'
             uc_securable:
               securable_full_name: 'main.docs.chunks_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'lookup-function'
             uc_securable:
               securable_full_name: 'main.tools.order_lookup'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'
   
           - name: 'database'
             database:
               instance_name: '<lakebase-instance-name>'
               database_name: 'databricks_postgres'
               permission: 'CAN_CONNECT_AND_CREATE'
   
   targets:
     dev:
       mode: development
       default: true
   

   Important

   Chaque valeur dans value_from doit correspondre à un champ config.env dans la liste name. Les incompatibilités entraînent la variable d’environnement à se résoudre en None dans l’application déployée.

2. Déployez et démarrez l’offre groupée :

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent
   

   bundle deploy charge la source et configure les ressources. bundle run démarre ou redémarre l’application avec la dernière source. L'argument de bundle run est la clé YAML sous resources.apps (ici my_agent), et non pas le champ name de l'application déployée.

Pour obtenir le schéma complet de chaque sous-type de ressource, consultez app.resources.

Le tableau suivant répertorie les autorisations minimales utilisées dans les exemples susmentionnés et la valeur équivalente des Offres Groupées d'Automatisation Déclarative pour chaque type de ressource :

Suivez le principe des privilèges minimum. Accordez au principal de service uniquement les autorisations dont l’agent a besoin et utilisez un principal de service dédié par application. Pour obtenir la liste complète, consultez les meilleures pratiques de sécurité.

Autorisation de l’utilisateur

L’autorisation de l’utilisateur permet à un agent d’agir avec l’identité de l’utilisateur effectuant la demande. Cela fournit les éléments suivants :

• Accès par utilisateur aux données sensibles
• Contrôles de données affinés appliqués par le catalogue Unity
• Pistes d’audit spécifiques à l’utilisateur
• Application automatique des filtres au niveau des lignes et des masques de colonne

Utilisez l’autorisation utilisateur lorsque votre agent doit accéder aux ressources à l’aide de l’identité de l’utilisateur demandeur au lieu du principal du service de l’application.

Fonctionnement de l’autorisation utilisateur

Lorsque vous configurez l’autorisation utilisateur pour votre agent :

1. Ajoutez des étendues d’API à votre application : définissez les API Databricks auxquelles l’application peut accéder pour le compte des utilisateurs. Voir Ajouter des étendues à une application.
2. Les informations d’identification de l’utilisateur sont limitées : Databricks accepte les informations d’identification de l’utilisateur et les limite uniquement aux étendues d’API que vous avez définies.
3. Routage de jetons : le jeton à portée réduite est mis à la disposition de votre application via l’en-tête x-forwarded-access-token HTTP.
4. MLflow AgentServer stocke le jeton : le serveur d’agent stocke automatiquement ce jeton par demande d’accès pratique dans le code de l’agent.

Configurez l’autorisation utilisateur en ajoutant des étendues dans l’interface utilisateur Databricks Apps lors de la création ou de la modification de votre application, ou par programmation à l’aide de l’API. Pour obtenir des instructions détaillées, consultez Ajouter des étendues à une application .

Les agents disposant d’une autorisation utilisateur peuvent accéder aux ressources Databricks suivantes :

• SQL Warehouse
• L'Espace des Génies
• Fichiers et répertoires
• Point de terminaison de mise en service de modèles
• Index de recherche vectorielle
• Connexions de catalogue Unity
• Tables de catalogue Unity

Implémenter l’autorisation utilisateur

Pour implémenter l’autorisation utilisateur, vous devez ajouter des étendues d’autorisation à votre application. Les étendues limitent ce que l’application peut faire au nom de l’utilisateur. Pour obtenir la liste des étendues et sémantiques d’étendue disponibles, consultez la sécurité basée sur l’étendue et l’escalade des privilèges.

Interface utilisateur de l’espace de travail

1. Dans l’interface utilisateur Databricks, accédez aux paramètres d’autorisation de votre application.
2. Sous Autorisation utilisateur, cliquez sur + Ajouter une étendue et sélectionnez les étendues dont l’application a besoin pour accéder aux ressources pour le compte de l’utilisateur.
3. Enregistrez les modifications et redémarrez l’application.

Paquets d'Automatisation déclarative

1. Déclarez les étendues sous user_api_scopes sur la ressource d'application dans databricks.yml:

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         user_api_scopes:
           - sql
           - dashboards.genie
           - serving.serving-endpoints
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   

2. Redéployez le bundle et redémarrez l’application :

   databricks bundle deploy
   databricks bundle run my_agent
   

   Note

   Après avoir activé l’autorisation utilisateur sur un espace de travail pour la première fois, vous devez redémarrer les applications existantes avant de pouvoir utiliser des étendues. Voir Ajouter des étendues à une application.

Pour configurer l’autorisation utilisateur dans votre code d’agent, récupérez l’en-tête de cette requête à partir de AgentServer et construisez un client d’espace de travail avec ces informations d’identification.

1. Dans votre code d’agent, importez l’utilitaire d’authentification :

   Si vous utilisez l’un des modèles fournis à partir de databricks/app-templates, importez l’utilitaire fourni :

   from databricks_app.utils import get_user_workspace_client
   

   Sinon, importez à partir des utilitaires du serveur d’agent :

   from agent_server.utils import get_user_workspace_client
   

   La get_user_workspace_client() fonction utilise le serveur agent pour capturer l’en-tête x-forwarded-access-token et construire un client d’espace de travail avec ces informations d’identification utilisateur, la gestion de l’authentification entre l’utilisateur, l’application et le serveur d’agent.

2. Initialisez le client d’espace de travail au moment de la requête, et non pendant le démarrage de l’application :

   Important

   Appelez get_user_workspace_client() à l’intérieur des gestionnaires invoke et stream, et non pas dans __init__ ni au démarrage de l’application. Les informations d’identification de l’utilisateur sont disponibles uniquement au moment de la requête lorsqu’un utilisateur effectue une demande. L’initialisation au démarrage de l’application échoue, car aucun contexte utilisateur n’existe encore.

   # In your agent code (inside invoke or stream handler)
   user_client = get_user_workspace_client()
   
   
   # Use user_client to access Databricks resources with user permissions
   response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)
   

Pour obtenir un guide complet sur l’ajout d’étendues et la compréhension de la sécurité basée sur l’étendue, consultez l’escalade de privilèges et de sécurité basée sur l’étendue. Demandez uniquement les étendues minimales dont votre agent a besoin et journalise chaque action effectuée pour le compte d’un utilisateur ; consultez les meilleures pratiques relatives à l’autorisation utilisateur.

S’authentifier auprès des serveurs MCP Databricks

Les serveurs MCP gérés par Databricks exposent les index de recherche vectorielle et les fonctions catalogue Unity en tant qu’outils par le biais d’URL du formulaire https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> et https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. Pour obtenir la liste des serveurs disponibles et leurs modèles d’URL, consultez Utiliser les serveurs MCP gérés par Databricks.

Pour vous authentifier, accordez au principal de service de l’agent (ou à l’utilisateur, si vous utilisez l’autorisation de l’utilisateur) l’accès à chaque ressource en aval dans ces schémas.

Par exemple, si votre agent utilise les URL de serveur MCP suivantes :

• https://<your-workspace>/api/2.0/mcp/vector-search/prod/customer_support
• https://<your-workspace>/api/2.0/mcp/vector-search/prod/billing
• https://<your-workspace>/api/2.0/mcp/functions/prod/billing

Vous devez accorder l’accès à chaque index de recherche vectorielle dans prod.customer_support et prod.billingà chaque fonction catalogue Unity dans prod.billing.

Interface utilisateur de l’espace de travail

Ajoutez chaque index et fonction en tant que ressource sous ressources d’application. Suivez les mêmes étapes que l’octroi d’autorisations à d’autres ressources Databricks.

Paquets d'Automatisation déclarative

1. Ajoutez une uc_securable entrée par index et par fonction dans la liste de resources votre application :

   resources:
     apps:
       my_agent:
         resources:
           - name: 'support-index'
             uc_securable:
               securable_full_name: 'prod.customer_support.tickets_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'billing-index'
             uc_securable:
               securable_full_name: 'prod.billing.invoices_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'refund-function'
             uc_securable:
               securable_full_name: 'prod.billing.process_refund'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'
   

2. Redéployez l’offre groupée :

   databricks bundle deploy
   databricks bundle run my_agent
   

Les serveurs MCP personnalisés hébergés en tant que leurs propres applications Databricks (noms d’applications précédés de ) ne sont pas encore pris en charge en tant que ressources groupées mcp-. Accordez manuellement le principal Can Use de service de l’agent à l’application serveur MCP avec databricks apps update-permissions. Consultez la compétence custom-mcp-server dans le référentiel de modèles d’agent.

Prochaines étapes

• Créer un agent IA et le déployer sur Databricks Apps
• Gérer les applications Databricks en utilisant des bundles d'automatisation déclaratifs
• Configurer l’autorisation dans une application Databricks
• Ajouter des ressources à une application Databricks
• Informations de référence sur les ressources d’application