Services d’agent dans Unity Catalog

Important

Cette fonctionnalité est en version bêta. Les administrateurs de compte peuvent contrôler l’accès à cette fonctionnalité à partir de la page Aperçus de la console de compte. Consultez Gérer les préversions d’Azure Databricks.

Les Services d’agents offrent à tous vos agents un espace dédié dans Unity Catalog. Inscrivez des agents de n’importe quelle équipe à un seul endroit, parcourez et découvrez-les en même temps que vos tables, modèles et fonctions, et définissez des autorisations avec les mêmes octrois qui protègent vos autres ressources de catalogue Unity.

Découvrir des agents dans l’Explorateur de catalogues

Une fois enregistré, un service d'agent apparaît dans lCatalog Explorer sous le schéma où il a été créé. Toute personne ayant READ_METADATA sur le service d’agent peut le parcourir aux côtés des tables, des modèles et des fonctions du même schéma. Sélectionnez un service d’agent pour afficher son nom, sa description, sa connexion et ses autorisations actuelles.

Utilisez le comment champ pour ajouter une description lorsque vous créez ou mettez à jour un service d’agent. Cette description s’affiche dans l’Explorateur de catalogues et aide les collègues à comprendre ce que fait l’agent lorsqu’il le parcoure.

Cela donne à votre organisation un emplacement unique pour voir quels agents existent, qui les possède et qui a accès, sans avoir à les suivre dans des systèmes ou une documentation distincts.

Requirements

  • Pour créer un service d’agent, vous devez disposer de USE CATALOG et de USE SCHEMA sur le catalogue parent et le schéma, de CREATE SERVICE sur le schéma, et de USE CONNECTION sur la connexion qu’utilise le service d’agent.
  • Pour gérer les autorisations sur un service d’agent, vous devez être le propriétaire du service d’agent ou avoir le MANAGE privilège.

Créer un service d’agent

Un service d’agent référence une connexion Unity Catalog existante qui stocke l’hôte et les informations d’identification de l’agent. Créez la connexion avant de créer le service d’agent.

L’exemple suivant crée un service d’agent nommé support_agent dans le main.default schéma :

databricks api post \
  "/api/2.1/unity-catalog/agent-services?parent=schemas/main.default&agent_service_id=support_agent" \
  --json '{
    "agent_service_type": "AGENT_SERVICE_TYPE_EXTERNAL",
    "comment": "Support agent for the customer team",
    "config": {
      "source_connection": {
        "name": "connections/main.default.my_agent_connection"
      },
      "base_path": "/v1/chat",
      "system_prompt": "You are a helpful support assistant."
    }
  }'

La réponse inclut le nom de ressource du service d’agent :

{
  "name": "agent-services/main.default.support_agent",
  "agent_service_type": "AGENT_SERVICE_TYPE_EXTERNAL",
  "created_by": "you@company.com",
  "config": {
    "source_connection": { "name": "connections/main.default.my_agent_connection" },
    "base_path": "/v1/chat",
    "system_prompt": "You are a helpful support assistant."
  }
}

Obtenir et répertorier les services d’agent

Récupérez un service d’agent unique par son nom complet :

databricks api get "/api/2.1/unity-catalog/agent-services/main.default.support_agent"

Répertoriez tous les services d’agent dans un schéma :

databricks api get "/api/2.1/unity-catalog/agent-services?parent=schemas/main.default"

Pour répertorier les services d’agent sur l’ensemble du metastore, omettez le filtre de schéma :

databricks api get "/api/2.1/unity-catalog/agent-services"

Mettre à jour un service d’agent

Pour mettre à jour des champs spécifiques sans écraser les autres, utilisez une requête PATCH et indiquez les champs à modifier. L’exemple suivant met à jour l’invite système tout en laissant tous les autres champs inchangés :

databricks api patch \
  "/api/2.1/unity-catalog/agent-services/main.default.support_agent?update_mask=config.system_prompt" \
  --json '{ "config": { "system_prompt": "You are a concise support assistant." } }'

Champs que vous pouvez mettre à jour : comment, config.system_prompt, config.base_path.

Accorder l'accès

Définissez des autorisations sur un service d’agent avec le même modèle d’octroi qui protège vos autres objets sécurisables du catalogue Unity. Accordez EXECUTE aux utilisateurs et aux principaux de service :

databricks api patch \
  "/api/2.1/unity-catalog/permissions/AGENT_SERVICE/main.default.support_agent" \
  --json '{
    "changes": [
      { "principal": "teammate@company.com", "add": ["EXECUTE"] }
    ]
  }'

Inspectez les subventions actuelles :

databricks api get "/api/2.1/unity-catalog/permissions/AGENT_SERVICE/main.default.support_agent"

Révoquer l’accès :

databricks api patch \
  "/api/2.1/unity-catalog/permissions/AGENT_SERVICE/main.default.support_agent" \
  --json '{
    "changes": [
      { "principal": "teammate@company.com", "remove": ["EXECUTE"] }
    ]
  }'

Privilèges assignables : EXECUTE, , READ_METADATAMANAGE, ALL_PRIVILEGES.

Supprimer un service d’agent

databricks api delete "/api/2.1/unity-catalog/agent-services/main.default.support_agent"

Limitations

Pendant la version bêta, les limitations suivantes s’appliquent :

  • L’invocation de l’environnement d’exécution n’est pas disponible. Les agents ne peuvent pas être appelés via un service d’agent enregistré. La gestion des inscriptions et des autorisations est désormais disponible.
  • Les stratégies de service et les limites de débit ne sont pas prises en charge par l’API. La tentative de définition de ces champs retourne une erreur.
  • Sql DDL pour les services d’agent n’est pas disponible. Créez et gérez des services d’agent avec l’API REST.
  • les champs full_name et owner retournent null dans les réponses GET dans cette version.
  • La recherche globale de Unity Catalog n’affiche pas les services d’agents.

Étapes suivantes

  • Last updated on