Créez un agent personnalisé à l'aide de l'API Superviseur (Bêta)

info

Bêta

Cette fonctionnalité est en bêta. Les administrateurs de compte peuvent contrôler l'accès à cette fonctionnalité depuis la page Aperçus . Voir Gérer les prévisualisations Databricks.

Vous pouvez créer un agent Databricks Apps qui utilise l'API de superviseur (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 chat, un /invocations Endpoint 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 la référence API complète et les paramètres pris en charge, consultez l'API Supervisor (Bêta).

Exigences

• Les Databricks Apps sont activées dans votre Workspace. Consultez Créer un agent d'IA et le déployer sur Databricks Apps.
• L'aperçu de Unity AI Gateway est activé pour votre compte. Voir Gérer les aperçus Databricks.
• Le package databricks-openai : pip install databricks-openai

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 Écrire un agent IA et le déployer sur Databricks Apps.

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 utilisateur de chat, une authentification et un endpoint /invocations, mais avec un code d'agent plus simple. Pour le workflow complet de déploiement (déployer sur Databricks Apps, ajouter des outils, évaluer), consultez Créer un agent IA et le déployer sur Databricks Apps.

Outils et parameters pris en charge

Pour la liste complète des types d'outils pris en charge, des paramètres de requête et des exemples de code, consultez API Supervisor (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 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

• API Supervisor (Beta): référence complète de l'API, outils pris en charge et exemples
• Créez un agent IA et déployez-le sur Databricks Apps: flux de travail de déploiement complet pour les agents d'applications.
• Créer un système multi-agents sur Databricks Apps: connecter plusieurs agents entre eux