Aller au contenu principal
Dernière mise à jour le

Enregistrer des agents (services aux agents)

info

Bêta

Les services d'agent sont en version bêta. Unity AI Gateway est disponible de manière générale, mais ses fonctionnalités bêta sont activées séparément. Un administrateur de compte doit activer les fonctionnalités bêta de Unity AI Gateway depuis la page Aperçus de la console de compte. Consultez Gérer les aperçus Databricks.

Enregistrez les agents dans Unity Catalog afin que les agents de chaque équipe soient regroupés au même endroit. Lorsque vous enregistrez un agent en tant que service d'agent, vous pouvez le parcourir et le découvrir aux côtés de vos tables, modèles et fonctions, et définir des autorisations avec les mêmes droits que ceux qui protègent vos autres actifs Unity Catalog.

Découvrir les agents dans l'Explorateur de catalogues​

Une fois qu’un service d’agent est enregistré, il apparaît dans Catalog Explorer sous le schéma où il a été créé. Pour voir un service d’agent, un utilisateur doit disposer d’un privilège explicite sur celui-ci, tel que EXECUTE. Sélectionnez un service d’agent pour afficher son nom, sa description, sa connexion et ses autorisations actuelles.

remarque

L'octroi de EXECUTE permet également à l'utilisateur d'appeler le service d'agent, et pas seulement de le découvrir. Ne l'accordez qu'aux utilisateurs qui doivent être en mesure d'utiliser l'agent.

Utilisez le champ comment pour ajouter une description lorsque vous créez ou mettez à jour un service d'agent. Cette description apparaît dans l'Explorateur de catalogues et aide les collaborateurs à comprendre ce que fait l'agent lorsqu'ils le parcourent.

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

Exigences​

  • Les fonctionnalités bêta de Unity AI Gateway activées pour votre compte. Consultez Gérer les aperçus Databricks.
  • Pour **créer** un service d'agent, vous devez avoir USE CATALOG et USE SCHEMA sur le catalogue et le schéma parents, CREATE SERVICE sur le schéma et USE CONNECTION sur la connexion à laquelle le service d'agent fait référence.
  • Pour gérer les autorisations sur un service d'agent, vous devez être le propriétaire du service d'agent ou disposer du privilège MANAGE.

Créer un service d’agent​

Un service d'agent référence une connexion Unity Catalog existante qui contient l'hôte et les informations d'identification pour 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 schéma main.default :

Bash
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 comprend le nom de la ressource du service d'agent :

JSON
{
  "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 lister les services d'agent​

Récupérer un service d'agent unique par son nom complet :

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

Lister tous les services d'agent dans un schéma :

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

Pour lister les services d'agent sur l'ensemble du métastore, omettez le filtre de schéma :

Bash
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 spécifiez les champs à modifier. L'exemple suivant met à jour l'invite système tout en laissant tous les autres champs inchangés :

Bash
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 les autorisations sur un service d'agent avec le même modèle d'octroi qui protège vos autres objets sécurisables d'Unity Catalog. Accordez EXECUTE aux utilisateurs et aux Service Principals :

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

Inspecter les octrois actuels :

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

Révoquer l'accès :

Bash
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 METADATA, MANAGE, ALL PRIVILEGES.

Supprimer un service d'agent​

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

Limitations​

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

  • L'invocation du Runtime n'est pas disponible. Les Agents ne peuvent pas être appelés via un service d'agent enregistré. L'inscription et la gestion des autorisations sont désormais disponibles.
  • Les politiques de service et les cadences maximales ne sont pas prises en charge par l'API. Tenter de définir ces champs renvoie une erreur.
  • Le DDL SQL pour les services d’agent n’est pas disponible. Créez et gérez des services d'agent avec l'API REST.
  • full_name et owner champs renvoient null dans les réponses GET dans cette version.
  • La recherche globale d'Unity Catalog n'affiche pas les services d'agent.
  • Le privilège BROWSE n’est pas pris en charge. Pour voir un service d’agent, un utilisateur doit disposer d’un privilège explicite sur celui-ci, tel que EXECUTE.

Étapes suivantes​

Sur cette page