Aller au contenu principal
Dernière mise à jour le

Créez un agent personnalisé à l’aide de l’API de 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 Prévisualisations . Consultez Gérer les aperçus Databricks.

Vous pouvez créer un agent Databricks Apps qui utilise l'API de supervision (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 l'élaboration d'un agent personnalisé: une application déployée avec une interface utilisateur 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 d'API, et Databricks gère la sélection d'outils, l'exécution et la synthèse des réponses.

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

Quand utiliser l'API Supervisor​

L'API superviseur fonctionne bien lorsque votre agent utilise uniquement des outils hébergés par Databricks et ne nécessite pas de logique personnalisée entre les appels d'outils. Utilisez plutôt une boucle d'agent personnalisée si votre agent nécessite l'un des éléments suivants :

  • Outils de fonction côté client (l'API Supervisor ne peut pas mélanger des 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 précis du streaming
  • Logique Python personnalisée entre les appels d'outils, telle que l'embranchement conditionnel ou la gestion de l'état
  • Contrôle sur les parameters d'inférence tels que temperature

Pour la référence complète de l'API et les paramètres pris en charge, consultez API Supervisor (Bêta).

Exigences​

Développez un agent personnalisé en utilisant l'API Supervisor​

Le point de départ recommandé est de créer une nouvelle application à partir du dernier template d'application Databricks. Les derniers Template incluent une compétence use-supervisor-api intégrée pour les assistants de code 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 Créer un agent AI et le déployer sur Databricks Apps.

Une fois que votre application est configurée à partir du dernier Template, ouvrez le projet dans votre assistant de codage AI 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 la boucle d'agent manuelle. Cela 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 /invocations endpoint, mais avec un code d'agent plus simple. Pour le workflow de déploiement complet (déployer vers les applications, ajouter des outils, évaluer), voir Créer un agent IA et le déployer sur Databricks Apps.

Outils et paramètres 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 l'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 droits permettent.

  • Autorisation d'application (default) : les outils s'exécutent en tant que Databricks Service Principal de l'application. Accorder l'autorisation au Databricks Service Principal sur chaque outil que l'agent utilise. Voir Autorisation de l'application.
  • **Autorisation de l'utilisateur** : Les outils s'exécutent en tant qu'utilisateur qui a envoyé la requête, ainsi, les autorisations Unity Catalog, les filtres de lignes et les masques de colonnes s'appliquent par utilisateur. Consultez la section suivante.

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

info

Aperçu

L'autorisation utilisateur est en préversion publique. L'administrateur de votre Workspace doit l'activer avant que vous puissiez 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 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 la portée par outil pour chaque type d'outil que l'agent utilise :

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

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 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, consultez 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 directement une ressource avec le client utilisateur, vous le transmettez 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 transmis à 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 de l'application. Si le jeton transmis 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. Accordez à 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