Aller au contenu principal
Dernière mise à jour le

Créer un agent personnalisé à l'aide de l'API Supervisor (obsolète)

attention

L'API Supervisor a atteint sa fin de vie le 30 septembre 2026. Il n'est plus disponible. Pour créer des agents personnalisés, écrivez votre propre boucle d'agent et déployez-la avec la CLI Agent Bricks. Consultez Déployer des agents sur Databricks.

Vous pouvez créer un agent Databricks Apps qui utilise l'interface API Supervisor (obsolète) 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 lors de la création d'un agent personnalisé: une application déployée avec une interface de chat, un endpoint /invocations et une authentification. La différence est que Databricks exécute la boucle de l'agent pour vous. Votre agent.py effectue un seul appel API, et Databricks gère la sélection des outils, l'exécution et la synthèse des réponses.

L'API Supervisor fonctionne avec n'importe lequel des modèles de fondation pris en charge. Modifiez le champ model pour changer de fournisseur sans modifier vos définitions d'outils ni votre logique de gestionnaire.

Quand utiliser l'API Supervisor​

L'API Supervisor fonctionne bien lorsque votre agent n'utilise que des outils hébergés par Databricks et n'a pas besoin de logique personnalisée entre les appels d'outils. Utilisez une boucle d'agent personnalisée à la place si votre agent nécessite l'une des conditions suivantes :

  • Outils de fonction côté client (l'API Supervisor ne peut pas mélanger les outils hébergés et côté client dans une seule requête)
  • Endpoints d'agent autres que les Endpoint Agent Bricks Knowledge Assistant
  • Récupérateurs personnalisés, entrées/sorties personnalisées ou contrôle de streaming granulaire
  • Logique Python personnalisée entre les appels d'outils, comme le branchement conditionnel ou la gestion de l'état
  • Contrôle sur les paramètres d'inférence, tels que temperature

Pour consulter la référence complète de l'API et les parameter pris en charge, voir API Supervisor (obsolète).

Exigences​

Créez un agent personnalisé à l'aide de l'API Superviseur​

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

Pour créer une nouvelle application à partir d’un template, consultez la page Exécuter des agents sur Databricks Apps à l’aide du serveur d’agents hérité.

Une fois votre application configurée à partir du dernier Template, 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, en remplaçant la boucle d'agent manuelle. Il ajoute également la dépendance databricks-openai et note les limitations de la version bêta.

Le résultat est la même application déployée, avec une interface de discussion (chat), une authentification et un Endpoint /invocations, mais avec un code d'agent plus simple. Pour découvrir le flux de déploiement complet (déploiement sur des applications, ajout d'outils, évaluation), consultez Exécuter des agents sur Databricks Apps à l'aide du serveur d'agents hérités.

Outils et parameters pris en charge​

Pour consulter la liste complète des types d'outils pris en charge, des parameter de requête et des exemples de code, voir API Supervisor (obsolète).

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 Supervisor exécute la boucle de l'agent, elle exécute des outils hébergés en utilisant soit l'identité de l'application, soit l'identité de l'utilisateur demandeur. Choisissez en fonction de si tous les utilisateurs de l'application doivent partager le même accès à vos outils, ou si chaque utilisateur doit accéder uniquement à ce que ses propres autorisations permettent.

  • Autorisation de l'application (default) : Les outils fonctionnent en tant que Service Principal Databricks de l'application. Accordez l'autorisation au Service Principal Databricks sur chaque outil que l'agent utilise. Consultez Autorisation de l'application.
  • Autorisation de l'utilisateur : Les outils s'exécutent en tant qu'utilisateur ayant envoyé la demande, ainsi les autorisations Unity Catalog, les filtres de ligne et les masques de colonne s'appliquent par utilisateur. Voyez la section suivante.

Exécuter les outils en tant qu'utilisateur demandeur​

info

Aperçu

L'autorisation utilisateur est en préversion publique. Votre administrateur workspace doit l'activer avant que vous ne puissiez ajouter des périmètres à votre application. Consultez Ajouter des périmètres à une application.

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

  1. Ajoutez les périmètres d'autorisation utilisateur dont votre application a besoin. ai-gateway est requis pour tout accès à l'API Supervisor. Ajoutez le périmètre par outil pour chaque type d'outil que l'agent utilise :

Type d'outil

Portée requise

Tous les outils

ai-gateway

genie_space

genie

uc_function

mcp.functions

knowledge_assistant

model-serving

uc_connection

catalog.connections

Type d'outil

Portée 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 endpoint d'application en tant qu'outil, utilisez plutôt l'autorisation d'application. Pour savoir comment ajouter des périmètres via l'interface utilisateur du workspace ou les Declarative Automation Bundles, voyez Autorisation de l'utilisateur. 2. Dans votre gestionnaire agent.py, transmettez un client de workspace utilisateur à DatabricksOpenAI. C'est le seul câblage spécifique au superviseur : au lieu d'appeler une ressource directement avec le client utilisateur, vous le confiez au client qui exécute la boucle d'agent.

Python
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 ne sont renseignés qu'au moment de la query. Appelez-le à l'intérieur des gestionnaires invoke et stream, jamais dans __init__ ou au Startup. 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 qu'en tant que Service Principal Databricks de l'application, consultez Autorisation de l'utilisateur. 3. Octroyez à chaque utilisateur qui exécute l'agent l'autorisation requise sur chaque outil, tel que CAN_RUN sur un Genie Agent ou CAN_QUERY sur un Endpoint d'assistant de connaissances.

Ressources supplémentaires​

Sur cette page