Créer un agent personnalisé à l’aide de l’API Superviseur (bêta)

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 . Consultez Gérer les préversions d’Azure Databricks.

Vous pouvez créer un agent Azure Databricks Apps qui utilise l’API Supervisor (bêta) pour l’orchestration au lieu de gérer la boucle de l’agent dans votre propre code. Le résultat est le même que la création d’un agent personnalisé : une application déployée avec une interface utilisateur de conversation, un point de terminaison et une /invocations authentification. La différence est que Azure Databricks exécute la boucle de l’agent pour vous. Votre agent.py effectue un appel d’API unique, et Azure Databricks gère la sélection, l’exécution et la synthèse des réponses des outils.

L’API Superviseur fonctionne avec l’un des modèles de base pris en charge. Modifiez le champ model pour changer de prestataire sans toucher à vos définitions d’outils ou logique de gestion.

Quand utiliser l’API Superviseur

L'API Superviseur fonctionne bien lorsque votre agent utilise uniquement des outils hébergés Azure Databricks et n'a pas besoin d'une logique personnalisée entre les appels d'outils. Utilisez plutôt une boucle d’agent personnalisée si votre agent nécessite l’une des opérations suivantes :

  • Outils de fonction côté client (l’API Superviseur ne peut pas combiner les outils hébergés et côté client dans une requête)
  • Points de terminaison de l’agent autres que les points de terminaison du Assistant de connaissances du système de briques d’agent
  • Récupérateurs personnalisés, entrées/sorties personnalisées ou contrôle de streaming affiné
  • Logique Python personnalisée entre les appels d’outils, tels que la gestion des branches conditionnelles ou de l’état
  • Contrôler les paramètres d’inférence comme temperature

Pour obtenir la référence complète de l’API et les paramètres pris en charge, consultez l’API Superviseur (bêta) .

Requirements

Créer un agent personnalisé à l’aide de l’API Superviseur

Le point de départ recommandé consiste à créer une application à partir du dernier modèle d’application Databricks. Les derniers modèles incluent une compétence intégrée use-supervisor-api pour les assistants de codage IA, ainsi qu’une add-tools compétence pour l’ajout d’outils hébergés.

Pour créer une application à partir d’un modèle, consultez Créer un agent IA et le déployer sur Databricks Apps.

Une fois votre application configurée à partir du dernier modèle, ouvrez le projet dans votre assistant de codage IA et exécutez :

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

La compétence met à jour votre agent_server/agent.py pour appeler DatabricksOpenAI().responses.create() avec des outils hébergés, remplaçant ainsi la boucle de l’agent manuel. Il ajoute également la databricks-openai dépendance et note les limitations bêta.

Le résultat est la même application déployée, avec une interface utilisateur de conversation, une authentification et un /invocations point de terminaison, mais avec du code d’agent plus simple. Pour le flux de travail de déploiement complet (déployer sur Applications, ajouter des outils, évaluer), consultez Créer un agent IA et le déployer sur Databricks Apps.

Outils et paramètres pris en charge

Pour obtenir la liste complète des types d’outils pris en charge, des paramètres de requête et des exemples de code, consultez l’API Superviseur (bêta).

Pour chaque outil que vous ajoutez, accordez également l’autorisation de ressource correspondante dans databricks.yml. Consultez la compétence add-tools dans .claude/skills/ pour des exemples.

Autorisation pour les outils hébergés

Lorsque l’API Superviseur exécute la boucle de l’agent, elle exécute des outils hébergés à l’aide de l’identité de l’application ou de l’identité de l’utilisateur demandeur. Choisissez selon si tous les utilisateurs de l’application doivent partager le même accès à vos outils, ou chaque utilisateur doit accéder uniquement à ce que ses propres autorisations autorisent.

  • Autorisation d’application (valeur par défaut) : les outils s’exécutent en tant que principal de service de l’application. Accordez l’autorisation du principal de service sur chaque outil utilisé par l’agent. Consultez l’autorisation de l’application.
  • Autorisation de l’utilisateur : les outils s’exécutent en tant qu’utilisateur qui a envoyé la demande, de sorte que les autorisations du catalogue Unity, les filtres de lignes et les masques de colonne s’appliquent par utilisateur. Consultez la section suivante.

Exécuter des outils en tant qu’utilisateur demandeur

Important

L’autorisation utilisateur est en aperçu public. L’administrateur de votre espace de travail doit l’activer avant de pouvoir ajouter des étendues à votre application. Voir Ajouter des étendues à une application.

Pour exécuter des outils hébergés pour le compte de l’utilisateur demandeur, transférez le jeton de l’utilisateur au DatabricksOpenAI client et ajoutez les étendues d’autorisation utilisateur dont vos outils ont besoin.

  1. Ajoutez les étendues d’autorisation utilisateur dont votre application a besoin. ai-gateway est requis pour l’accès à l’API Superviseur. Ajoutez la portée spécifique à chaque outil pour chaque type d’outil utilisé par l’agent :

    Type d’outil Étendue requise
    Tous les outils ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    Le type d’outil app n’est pas pris en charge avec l’autorisation de l’utilisateur. Pour appeler un point de terminaison d’application en tant qu’outil, utilisez plutôt l’autorisation d’application. Pour savoir comment ajouter des étendues via l’interface utilisateur de l’espace de travail ou des bundles Automation déclaratifs, consultez Autorisation de l’utilisateur.

  2. Dans votre agent.py gestionnaire, transmettez un client d’espace de travail utilisateur à DatabricksOpenAI. Il s’agit du seul câblage spécifique au superviseur : au lieu d’appeler une ressource directement avec le client utilisateur, vous le donnez au client qui exécute la boucle de l’agent.

    from databricks_openai import DatabricksOpenAI
from agent_server.utils import get_user_workspace_client

# Inside your invoke or stream handler, not at app startup
client = DatabricksOpenAI(
  workspace_client=get_user_workspace_client(),
  use_ai_gateway=True,
)

    get_user_workspace_client() lit le jeton utilisateur transféré à partir des en-têtes de requête, qui sont renseignés uniquement au moment de la requête. Appelez-le dans les gestionnaires invoke et stream, jamais dans __init__ ni au démarrage de l’application. Si le jeton transféré est manquant, le client résultant n’est pas authentifié en tant qu’utilisateur demandeur. Pour savoir comment vérifier que l’agent s’exécute en tant qu’appelant plutôt que le principal de service de l’application, consultez Autorisation de l’utilisateur.

  3. Accordez à chaque utilisateur qui exécute l’agent les autorisations requises sur chaque outil, par exemple CAN_RUN sur un espace Genie ou CAN_QUERY sur un point de terminaison d’un assistant de connaissances.

Ressources supplémentaires

  • Last updated on