API Superviseur (bêta)

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 ai-gateway/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.

Requirements

• Gouvernance de l’IA avec Unity AI Gateway activé pour votre compte. Consultez Gérer les préversions d’Azure Databricks.
  • Étant donné que l’API Superviseur s’exécute via Unity AI Gateway, les fonctionnalités AI Gateway telles que les tables d’inférence, les limites de débit et les mesures de repli s’appliquent. Le suivi de l’utilisation n’est pas pris en charge dans cette version bêta.
• Le stockage des traces OpenTelemetry dans le catalogue Unity est activé pour votre compte. Consultez Gérer les préversions d’Azure Databricks.
  • Stocke les traces à partir de la boucle de l’agent d’API Superviseur dans les tables du catalogue Unity.
• Espace de travail Azure Databricks dans une région prise en charge.
• Catalogue Unity activé pour votre espace de travail. Consultez Activer un espace de travail pour le Catalogue Unity.
• Les outils que vous transmettez (Genie Spaces, fonctions catalogue Unity, serveurs MCP, assistants de connaissances, applications) doivent déjà être configurés et accessibles.
• Package databricks-openai installé : pip install databricks-openai

É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",
      "name": "Customer reviews",
      "description": "Answers customer review questions using SQL",
      "genie_space": {"space_id": "<genie-space-id>"}
    },
    {
      "type": "dashboard",
      "name": "Customer reviews dashboard",
      "description": "Answers questions about the customer reviews dashboard",
      "dashboard": {"dashboard_id": "<dashboard-id>"}
    },
    {
      "type": "uc_function",
      "name": "Flag urgent review",
      "description": "Flags a review as requiring urgent attention",
      "uc_function": {"name": "<catalog>.<schema>.<function_name>"}
    },
    {
      "type": "table",
      "table": {
        "name": "<catalog>.<schema>.<table_name>",
        "description": "Reads from the customer reviews table"
      }
    },
    {
      "type": "vector_search_index",
      "vector_search_index": {
        "name": "<catalog>.<schema>.<index_name>",
        "description": "Searches the product documentation index for relevant passages"
      }
    },
    {
      "type": "knowledge_assistant",
      "name": "Internal docs",
      "description": "Answers questions from internal documentation",
      "knowledge_assistant": {"knowledge_assistant_id": "<knowledge-assistant-id>"}
    },
    {
      "type": "serving_endpoint",
      "name": "Custom agent",
      "description": "Calls a custom agent served from a Databricks model serving endpoint",
      "serving_endpoint": {"name": "<serving-endpoint-name>"}
    },
    {
      "type": "vector_search_index",
      "name": "Product docs",
      "description": "Looks up product documentation by semantic search",
      "vector_search_index": {
        "name": "<catalog>.<schema>.<index>",
        "columns": ["title", "content"]
      }
    },
    {
      "type": "app",
      "name": "Support agent",
      "description": "Custom application endpoint",
      "app": {"name": "<app-name>"}
    },
    {
      "type": "uc_connection",
      "name": "GitHub",
      "description": "Searches GitHub for issues and pull requests",
      "uc_connection": {"name": "<uc-connection-name>"}
    },
    {
      "type": "web_search",
      "name": "Web search",
      "description": "Searches the public web for current information and returns a synthesized answer with citations",
      "web_search": {}
    },
    {
      "type": "volume",
      "volume": {
        "name": "<catalog>.<schema>.<volume>",
        "description": "Searches files in a Unity Catalog volume"
      }
    },
  ],
  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, SharePoint et Glean. 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 :

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 (facultatif) : Ajouter un outil de fonction côté client

Utilisez function outils lorsque vous souhaitez que votre application exécute une logique personnalisée en même temps que les outils hébergés par Azure Databricks. Déclarez un outil de type fonction avec type: "function", un name, un description facultatif et un objet parameters JSON Schema :

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "<user prompt>"}],
  tools=[
    {
      "type": "function",
      "name": "<client-side-function-name>",
      "description": "<description of what this function does>",
      "parameters": {
        "type": "object",
        "properties": {"<param-name>": {"type": "string"}},
        "required": ["<param-names>"],
        "additionalProperties": False,
      },
    }
  ],
)

L’API Superviseur ne stocke pas l’état de conversation entre les requêtes. Par conséquent, un appel de fonction côté client prend deux tours :

1. Tournez 1. Le modèle retourne un function_call élément (par exemple, « appeler get_weather avec location=Paris») au lieu d’une réponse finale.
2. Votre code exécute la fonction localement et produit un résultat.
3. Tournez 2. Appelez responses.create() à nouveau, en transmettant l’entrée initiale ainsi que le function_call du modèle, plus un nouveau function_call_output avec votre résultat. Le modèle utilise le résultat pour produire la réponse finale.

import json
from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)
MODEL = "databricks-claude-sonnet-4-5"

GET_WEATHER = {
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
        "additionalProperties": False,
    },
}

def run_get_weather(args):
    return json.dumps({
        "location": args["location"],
        "temp_c": 18,
        "condition": "sunny",
    })

CLIENT_TOOLS = {"get_weather": run_get_weather}
TOOLS = [GET_WEATHER]

input_list = [{"role": "user", "content": "What's the weather in Paris?"}]

# Turn 1 — model emits a function_call
resp = client.responses.create(model=MODEL, input=input_list, tools=TOOLS)

# Echo the model's turn into history, then execute pending client function_calls
input_list += [item.model_dump() for item in resp.output]
for item in resp.output:
    if item.type == "function_call" and item.name in CLIENT_TOOLS:
        args = json.loads(item.arguments)
        # Execute the client-side function with the model's arguments
        # and append the result so the model can use it on the next turn.
        tool_output = CLIENT_TOOLS[item.name](args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": tool_output,
        })

# Turn 2 — model produces the final answer using the tool result
final = client.responses.create(model=MODEL, input=input_list, tools=TOOLS)
print(final.output_text)

Pour plus de modèles (diffusion en continu, hébergement, outils clients, approbation MCP, résolution des problèmes), consultez la compétence d’appel de fonction côté client de l’API Superviseur.

Étape 5 : 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
}

Outils pris en charge

Vous définissez des outils dans le tools tableau de votre requête. Chaque objet outil partage trois champs de niveau supérieur :

• type (chaîne, obligatoire) : le discriminateur qui sélectionne le type d’outil.
• name (chaîne, facultatif) : nom d’affichage affiché au modèle.
• description (chaîne, facultatif) : indicateur du modèle sur le moment où appeler cet outil.

En outre, chaque objet outil comporte un objet de configuration imbriqué dont la clé correspond à la type valeur. Le tableau ci-dessous documente la configuration imbriquée pour chaque type d’outil pris en charge.

Pour serving_endpoint, seuls les points de terminaison ResponseAgent, ChatCompletions et ChatAgent sont pris en charge.

Pour apples applications MCP uniquement (avec le mcp- préfixe) et les applications ResponseAgent personnalisées (avec le agent- préfixe) sont prises en charge.

Pour uc_connection, utilisez le nom de connexion que vous avez créé pour un serveur MCP externe ou un system_ai_agent_* connecteur géré par le système (voir l’étape 3 (facultatif) : Connectez-vous à des services tiers avec des connexions gérées par le système). Les serveurs MCP personnalisés sur les applications ne sont pas pris en charge.

Exécution du code

Lorsqu’une requête a besoin d’un calcul, le superviseur exécute du code généré par modèle dans une session de calcul serverless en bac à sable (sandbox) pour analyser des données, transformer des fichiers ou exécuter des calculs. Il prend en charge les commandes Python (par défaut), SQL et shell. Le superviseur écrit et exécute le code lui-même si nécessaire, de sorte que vous n’activez pas, configurez ou fournissez le code.

L’exécution du code s’exécute dans un bac à sable verrouillé avec :

• Pas d’accès à Internet. Il bloque toutes les sorties réseau sortantes, quelle que soit la stratégie réseau de votre espace de travail, de sorte que le code s’exécutant dans le bac à sable ne peut pas atteindre les points de terminaison externes.
• Accès limité à Azure Databricks uniquement. Il n’a pas d’accès aux données qui lui soit propre. Il peut lire les tables de catalogue Unity que vous déclarez avec l’outil table dans la même requête.

Paramètres pris en charge

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

• model: l’un des modèles pris en charge suivants. Modifiez ce champ pour changer de fournisseur sans modifier le reste de votre code.
  • Claude-Haiku-4.5 (databricks-claude-haiku-4-5)
  • Claude-Opus-4.1 (databricks-claude-opus-4-1)
  • Claude-Opus-4.5 (databricks-claude-opus-4-5)
  • Claude-Opus-4.6 (databricks-claude-opus-4-6)
  • Claude-Sonnet-4 (databricks-claude-sonnet-4)
  • Claude-Sonnet-4.5 (databricks-claude-sonnet-4-5)
  • Claude-Sonnet-4.6 (databricks-claude-sonnet-4-6)

• input: messages de conversation à envoyer.
• tools: définitions d’outils hébergés (genie_space, dashboard, uc_function, table, knowledge_assistant, serving_endpoint, web_search, vector_search_index, volume, app, uc_connection) et outils de fonction côté client (function). Voir l’étape 4 (facultatif) : Ajouter un outil de fonction côté client.
• 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.

Authorization

L’API Superviseur exécute la boucle de l’agent avec les informations d’identification de l’appelant, de sorte que les outils qu’il appelle respectent les autorisations du catalogue Unity de l’appelant. Lorsque vous appelez directement l’API, le DatabricksOpenAI client s’authentifie en tant que vous.

Lorsque vous appelez l'API Superviseur à partir d'une application Azure Databricks, vous pouvez exécuter des outils en tant que principal de service de l'application (autorisation d'application) ou en tant qu'utilisateur demandeur (autorisation utilisateur). Pour l’autorisation de l’application, accordez au principal de service de l’application les autorisations nécessaires pour chaque outil. Pour l’autorisation utilisateur, transférez le jeton de l’utilisateur au DatabricksOpenAI client et ajoutez les étendues d’autorisation utilisateur requises. Consultez Exécuter des outils en tant qu’utilisateur demandeur.

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.
• 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.
• Éligibilité de l’espace de travail de recherche web : l’outil web_search n’est pas disponible sur les espaces de travail avec la conformité HIPAA/BAA activée. Il est disponible uniquement dans les régions avec un modèle natif compatible avec la recherche web ou un traitement inter-géographie activé. Les demandes qui incluent web_search provenant d’espaces de travail non éligibles sont rejetées.

Ressources supplémentaires

• Créer un agent personnalisé à l’aide de l’API Superviseur (bêta)
• Utiliser l’agent de superviseur pour créer un système multi-agent coordonné
• Services de modèle de requête
• Gouvernance de l’IA avec Unity AI Gateway