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.

L'API Superviseur simplifie la création d'agents personnalisés sur Azure Databricks avec prise en charge du mode en arrière-plan pour les tâches de longue durée. Vous définissez le modèle, les outils et les instructions d’une requête à un point de terminaison compatible OpenResponses compatible (POST /mlflow/v1/responses), et Azure Databricks exécute la boucle de l’agent pour vous : appeler à plusieurs reprises le modèle, sélectionner et exécuter des outils et synthétiser une réponse finale.

Il existe trois approches pour créer un agent d’appel d’outils personnalisé sur Azure Databricks :

  • Agent Bricks Supervisor Agent (recommandé) : entièrement déclaratif avec optimisation des commentaires humains pour la meilleure qualité.
  • API de supervision : Créez un agent personnalisé par programmation : choisissez des modèles au moment de l’exécution, contrôlez les outils à utiliser par requête ou itérer pendant le développement. Également le bon choix lorsque vous avez besoin de choisir le modèle tout en déléguant la gestion des boucles de l’agent à Azure Databricks.
  • API unifiées ou natives de la passerelle IA : écrivez votre propre boucle d’agent. Azure Databricks fournit uniquement la couche d’inférence LLM. Utilisez les API unifiées si possible pour activer le basculement de modèles ou les API natives spécifiques au fournisseur (/openai, /anthropic, /gemini) lors du portage du code existant vers Azure Databricks ou à l’aide de fonctionnalités spécifiques au fournisseur.

Exigences

Étape 1 : Créer un appel LLM à un seul tour

Commencez par un appel de base sans outils. Le DatabricksOpenAI client configure automatiquement l’URL de base et l’authentification pour votre espace de travail :

from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  stream=False
)

print(response.output_text)

Étape 2 : Ajouter des outils hébergés pour exécuter la boucle de l’agent

Lorsque vous incluez des outils dans la requête, Azure Databricks gère une boucle à plusieurs tour en votre nom : le modèle décide des outils à appeler, Azure Databricks les exécute, alimente les résultats vers le modèle et se répète jusqu’à ce que le modèle produise une réponse finale.

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Summarize recent customer reviews and flag any urgent issues."}],
  tools=[
    {
      "type": "genie_space",
      "genie_space": {
        "id": "<genie-space-id>",
        "description": "Answers customer review questions using SQL"
      }
    },
    {
      "type": "uc_function",
      "uc_function": {
        "name": "<catalog>.<schema>.<function_name>",
        "description": "Flags a review as requiring urgent attention"
      }
    },
    {
      "type": "knowledge_assistant",
      "knowledge_assistant": {
        "knowledge_assistant_id": "<knowledge-assistant-id>",
        "description": "Answers questions from internal documentation"
      }
    },
    {
      "type": "app",
      "app": {
        "name": "<app-name>",
        "description": "Custom application endpoint"
      }
    },
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "<uc-connection-name>",
        "description": "Searches the web for current information"
      }
    },
  ],
  stream=True
)

for event in response:
  print(event)

Étape 3 (Facultatif) : Se connecter à des services tiers avec des connexions gérées par le système

Azure Databricks fournit des connexions gérées par le système pour les services tiers populaires tels que Google Drive, GitHub, Atlassian et SharePoint. Ces connexions constituent une alternative rapide à la configuration de votre propre serveur MCP externe . Vous pouvez toujours utiliser le uc_connection type d’outil pour vous connecter à n’importe quel serveur MCP externe que vous avez configuré vous-même.

Les connexions gérées par le système nécessitent que les connecteurs tiers pour les agents bêta soient activés dans votre espace de travail. Consultez Gérer les préversions d’Azure Databricks.

Les connecteurs suivants sont pris en charge :

Connecteur Description
system_ai_agent_google_drive Recherchez et lisez des fichiers à partir de Google Drive.
system_ai_agent_github_mcp Accédez aux repositories, problèmes et requêtes de tirage (pull requests) GitHub.
system_ai_agent_atlassian_mcp Rechercher et gérer des ressources Atlassian (Jira, Confluence).
system_ai_agent_sharepoint Recherchez et lisez des fichiers à partir de SharePoint.

Passez un connecteur dans le tableau tools en utilisant un outil de type uc_connection avec le champ name défini sur le nom du connecteur :

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "List my open GitHub pull requests."}],
  tools=[
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "system_ai_agent_github_mcp"
      }
    }
  ],
)

Authentification utilisateur à machine (U2M)

Chaque utilisateur s’authentifie individuellement. Les jetons OAuth ne sont pas partagés entre les utilisateurs. Dans la première requête qui utilise un connecteur que l’utilisateur n’a pas authentifié, la réponse se termine par status: "failed" une oauth erreur contenant une URL de connexion :

{
  "status": "failed",
  "error": {
    "code": "oauth",
    "message": "Failed request to <connector>. Please login first at <login-url>."
  }
}

Ouvrez l’URL dans un navigateur, terminez le flux OAuth, puis réexécutez la même requête.

Étape 4 : Activer le suivi

Incluez un trace_destination dans le corps de la requête pour envoyer des traces de la boucle de l’agent aux tables du catalogue Unity. Chaque requête génère une trace capturant la séquence complète d’appels de modèle et d’exécutions d’outils. Si vous ne définissez trace_destinationpas, aucune trace n’est écrite. Pour plus d’informations sur la configuration, consultez Stocker les traces OpenTelemetry dans le catalogue Unity.

À l’aide du client databricks-openai Python, transmettez-le via extra_body :

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  extra_body={
    "trace_destination": {
      "catalog_name": "<catalog>",
      "schema_name": "<schema>",
      "table_prefix": "<table-prefix>"
    }
  }
)

Pour également retourner la trace directement dans la réponse de l’API, transmettez "databricks_options": {"return_trace": True}extra_body.

Vous pouvez également utiliser le suivi distribué MLflow pour combiner des traces à partir de votre code d’application et de la boucle de l’agent d’API Supervisor en une seule trace de bout en bout. Propagez les en-têtes de contexte de trace en utilisant le champ extra_headers :

import mlflow
from mlflow.tracing import get_tracing_context_headers_for_http_request

with mlflow.start_span("client-root") as root_span:
  root_span.set_inputs({"input": "Tell me about Databricks"})

  trace_headers = get_tracing_context_headers_for_http_request()

  response = client.responses.create(
    model="databricks-claude-sonnet-4-5",
    input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
    tools=[...],
    extra_body={
      "trace_destination": {
        "catalog_name": "<catalog>",
        "schema_name": "<schema>",
        "table_prefix": "<table-prefix>"
      }
    },
    extra_headers=trace_headers,
  )

Mode arrière-plan

Le mode en arrière-plan vous permet d’exécuter des workflows d’agent de longue durée qui impliquent plusieurs appels d’outils et un raisonnement complexe sans attendre qu’ils se terminent de manière synchrone. Envoyez votre demande avec background=True, recevez immédiatement un ID de réponse et interrogez le résultat lorsqu’il est prêt. Cela est particulièrement utile pour les agents qui interrogent plusieurs sources de données ou chaînent plusieurs outils ensemble dans une seule requête.

Créer une demande en arrière-plan

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  background=True,
)

print(response.id)     # Use this ID to poll for the result
print(response.status) # "queued" or "in_progress"

Sondage pour le résultat

Permet responses.retrieve() de vérifier l’état jusqu’à ce qu’il atteigne un état terminal :

from time import sleep

while response.status in {"queued", "in_progress"}:
  sleep(2)
  response = client.responses.retrieve(response.id)

print(response.output_text)

Mode d’arrière-plan avec MCP

Pour la sécurité, l’API Superviseur nécessite une approbation explicite de l’utilisateur avant d’exécuter un appel d’outil MCP en mode en arrière-plan. Lorsque la boucle de l’agent sélectionne un outil MCP, la réponse se termine par un mcp_approval_request. Vous pouvez consulter le nom de l’outil, l’étiquette du serveur et les arguments que le modèle a l’intention de passer :

{
  "type": "mcp_approval_request",
  "id": "<tool-call-id>",
  "arguments": "{\"query\": \"what is Databricks\", \"count\": 5}",
  "name": "you-search",
  "server_label": "<server-label>",
  "status": "completed"
}

Pour approuver l’appel de l’outil et poursuivre le cycle de l’agent, envoyez un mcp_approval_response dans le champ input avec l’historique complet de la conversation :

{
  "type": "mcp_approval_response",
  "id": "<tool-call-id>",
  "approval_request_id": "<tool-call-id>",
  "approve": true
}

Note

Les réponses en mode arrière-plan sont conservées dans la base de données pendant un maximum de 30 jours.

Outils pris en charge

Vous définissez des outils dans le tools tableau de votre requête. Chaque entrée spécifie un type et un objet de configuration avec la même clé. Par exemple, un outil Genie Space a "type": "genie_space" et un "genie_space": {...} objet. L’API prend en charge les types d’outils suivants :

Type d’outil Description Scope
genie_space Interroge un espace Génie pour répondre à des questions sur vos données. Paramètres : id, description. genie
uc_function Appelle une fonction de catalogue Unity en tant qu’outil d’agent. Paramètres : name, description. unity-catalog
uc_connection Se connecte à un serveur MCP externe via une connexion de catalogue Unity. Paramètres : name, description. Pour les connexions système gérées par Azure Databricks, définissez name sur un connecteur system_ai_agent_* (voir Step 3 (facultatif) : Connectez-vous à des services tiers avec des connexions gérées par le système). Remarque : les serveurs MCP personnalisés sur les applications ne sont pas encore pris en charge. unity-catalog
app Appelle un endpoint d'Azure Databricks App. Paramètres : name, description. apps
knowledge_assistant Appelle un point de terminaison de l'Assistant de Connaissance. Paramètres : knowledge_assistant_id, description. model-serving

Paramètres pris en charge

Chaque requête adressée à l’API Superviseur accepte les paramètres suivants.

  • input: messages de conversation à envoyer.
  • tools: définitions d’outils hébergées (genie_space, , uc_functionknowledge_assistant, ). appuc_connection
  • instructions: invite du système destinée à guider le comportement du superviseur.
  • stream: défini sur true le flux de réponses.
  • background : définissez true pour exécuter la requête de manière asynchrone. Retourne un ID de réponse avec lequel vous interrogez responses.retrieve(). Voir le mode Arrière-plan.
  • trace_destination: objet facultatif avec catalog_name, schema_nameet table_prefix champs. Quand elle est définie, l’API Superviseur écrit une trace de la boucle de l’agent complet dans les tables de catalogue Unity spécifiées. Passez par extra_body dans le client Python.

L’API ne prend pas en charge les paramètres d’inférence tels que temperature. Le serveur gère ces éléments en interne.

Limitations

L’API Superviseur présente les limitations suivantes :

  • Runtime en mode arrière-plan : les requêtes en mode arrière-plan ont une durée d’exécution maximale de 30 minutes.
  • Appel de fonction côté client : seuls les outils hébergés sont pris en charge. Vous ne pouvez pas passer de définitions d’outils pour que le client s’exécute, et vous ne pouvez pas combiner d’outils hébergés function avec des outils côté function client dans la même requête.
  • Diffusion en continu en mode arrière-plan : stream et background ne peut pas être true dans la même requête.
  • Exécution durable : la récupération automatique à partir d’échecs ou d’interruptions avec des garanties d’exécution exactement une fois pour la boucle de l’agent n’est pas prise en charge.
  • Azure Databricks Apps OBO non pris en charge : l’autorisation au nom de l'utilisateur n’est pas prise en charge pour l’API du superviseur. Pour utiliser l’API Superviseur dans Azure Databricks Apps, utilisez autorisation du système et accordez des autorisations pour vos outils.

Étapes suivantes

  • Last updated on