Supervisor-API (Beta)

Important

Dieses Feature befindet sich in der Betaversion. Arbeitsbereichsadministratoren und -administratorinnen können dieses Feature über die Seite Vorschau aktivieren. Siehe Manage Azure Databricks Previews.

Die Supervisor-API vereinfacht die Erstellung benutzerdefinierter Agents auf Azure Databricks mit Unterstützung für den Hintergrundmodus bei lang andauernden Aufgaben. Sie definieren das Modell, die Tools und Anweisungen in einer Anforderung an eine OpenResponses-kompatiblen Endpunkt (POST /mlflow/v1/responses), und Azure Databricks führt die Agentschleife für Sie aus: wiederholtes Aufrufen des Modells, Auswählen und Ausführen von Tools und Synthesizing einer endgültigen Antwort.

Es gibt drei Ansätze zum Erstellen eines benutzerdefinierten Toolanruf-Agents auf Azure Databricks:

  • Agent Bricks Supervisor Agent (empfohlen): Vollständig deklarativ mit menschlicher Feedback-Optimierung für höchste Qualität.
  • Supervisor-API: Programmieren eines benutzerdefinierten Agents – Wählen Sie Modelle zur Laufzeit aus, steuern Sie, welche Tools pro Anfrage verwendet werden sollen, oder iterieren Sie während der Entwicklung. Auch die richtige Wahl, wenn Sie die Kontrolle über die Modellauswahl benötigen, während sie die Agentschleifenverwaltung auf Azure Databricks auslagern.
  • KI-Gateway einheitliche oder systemeigene APIs: Schreiben Sie Ihre eigene Agent-Schleife. Azure Databricks stellt nur die LLM-Ableitungsebene bereit. Verwenden Sie, wenn möglich, einheitliche APIs, um das Umschalten zwischen Modellen zu ermöglichen, oder nutzen Sie anbieterspezifische native APIs (/openai, /anthropic, /gemini), wenn Sie vorhandenen Code zu Azure Databricks portieren oder anbieterspezifische Funktionen nutzen.

Anforderungen

Schritt 1: Erstellen eines Einzelgesprächs mit einem LLM

Beginnen Sie mit einem einfachen Anruf ohne Tools. Der DatabricksOpenAI Client konfiguriert automatisch die Basis-URL und Authentifizierung für Ihren Arbeitsbereich:

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)

Schritt 2: Hinzufügen gehosteter Tools zum Ausführen der Agentschleife

Wenn Sie Tools in die Anforderung einschließen, verwaltet Azure Databricks eine Multi-Turn-Schleife in Ihrem Auftrag: Das Modell entscheidet, welche Tools aufgerufen werden sollen, Azure Databricks diese ausführen, leitet die Ergebnisse wieder in das Modell ein und wiederholt, bis das Modell eine endgültige Antwort erzeugt.

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": {
        "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)

Schritt 3 (Optional): Herstellen einer Verbindung mit Drittanbieterdiensten mit vom System verwalteten Verbindungen

Azure Databricks bietet vom System verwaltete Verbindungen für beliebte Drittanbieterdienste wie Google Drive, GitHub, Atlassian, SharePoint und Glean. Diese Verbindungen sind eine schnelle Alternative zum Einrichten Ihres eigenen externen MCP-Servers . Sie können den uc_connection Tooltyp weiterhin verwenden, um eine Verbindung mit jedem externen MCP-Server herzustellen, den Sie selbst konfiguriert haben.

Für vom System verwaltete Verbindungen müssen die Drittanbieter-Connectors für Agenten Beta in Ihrem Arbeitsbereich aktiviert sein. Siehe Manage Azure Databricks Previews.

Die folgenden Connectors werden unterstützt:

Steckverbinder Description
system_ai_agent_google_drive Suchen und Lesen von Dateien von Google Drive.
system_ai_agent_github_mcp Zugreifen auf GitHub Repositorys, Probleme und Pullanforderungen.
system_ai_agent_atlassian_mcp Suchen und verwalten Sie Atlassian-Ressourcen (Jira, Confluence).
system_ai_agent_sharepoint Suchen und Lesen von Dateien aus SharePoint.
system_ai_agent_glean_mcp Durchsuchen Sie unternehmensweite Inhalte, die von Glean indiziert werden.

Übergeben Sie einen Konnektor im tools-Array mithilfe des Werkzeugtyps uc_connection, wobei das name-Feld auf den Konnektornamen festgelegt ist:

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"
      }
    }
  ],
)

Benutzer-zu-Computer-Authentifizierung (U2M)

Jeder Benutzer authentifiziert sich einzeln. OAuth-Token werden nicht zwischen Benutzern geteilt. Bei der ersten Anforderung, die einen Connector verwendet, den der Benutzer noch nicht authentifiziert hat, wird die Antwort mit einem status: "failed"-Fehler abgeschlossen, der eine Anmelde-URL enthält:

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

Öffnen Sie die URL in einem Browser, schließen Sie den OAuth-Fluss ab, und führen Sie dann dieselbe Anforderung erneut aus.

Schritt 4 (Optional): Hinzufügen eines clientseitigen Funktionstools

Verwenden Sie function Tools, wenn Ihre Anwendung benutzerdefinierte Logik zusammen mit Azure Databricks gehosteten Tools ausführen soll. Deklarieren Sie ein Funktions-Tool mit type: "function", einem name, einem optionalen description und einem JSON-Schema-Objekt parameters:

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,
      },
    }
  ],
)

Die Supervisor-API speichert den Konversationsstatus nicht zwischen Anfragen, sodass ein clientseitiger Funktionsaufruf zwei Schritte erfordert:

  1. Runde 1. Das Modell gibt ein function_call Element (z. B. "Call get_weather with location=Paris") anstelle einer endgültigen Antwort zurück.
  2. Ihr Code führt die Funktion lokal aus und erzeugt ein Ergebnis.
  3. Zug 2. Rufen Sie responses.create() erneut auf, wobei Sie die ursprüngliche Eingabe, die function_call des Modells sowie ein neues function_call_output mit Ihrem Ergebnis übergeben. Das Modell verwendet das Ergebnis, um die endgültige Antwort zu erzeugen.
Beispiel für ein clientseitiges Funktionstool 
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)

Weitere Muster (Streaming, gehostete Umgebungen und Clienttools, MCP-Freigabe, Problembehandlung) finden Sie unter clientseitige Fähigkeit zum Funktionsaufruf der Supervisor-API.

Schritt 5: Ablaufverfolgung aktivieren

Geben Sie ein trace_destination im Anforderungskörper an, um Ablaufverfolgungen aus der Agentschleife an Unity Catalog-Tabellen zu senden. Jede Anforderung generiert eine Ablaufverfolgung, die die vollständige Sequenz von Modellaufrufen und Toolausführungen erfasst. Wenn Sie trace_destination nicht festlegen, werden keine Protokolle geschrieben. Details zur Einrichtung finden Sie unter OpenTelemetry-Ablaufverfolgungen im Unity-Katalog speichern.

Übergeben Sie ihn mithilfe des databricks-openai Python-Clients über 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>"
    }
  }
)

Um die Ablaufverfolgung ebenfalls direkt in der API-Antwort zurückzugeben, übergeben Sie "databricks_options": {"return_trace": True} in extra_body.

Sie können auch die verteilte Ablaufverfolgung von MLflow verwenden, um Ablaufverfolgungen aus Ihrem Anwendungscode und dem Supervisor-API-Agent in einer einzelnen End-to-End-Ablaufverfolgung zu kombinieren. Verteilen von Trace-Kontext-Headern mithilfe von dem extra_headers Feld:

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,
  )

Hintergrundmodus

Im Hintergrundmodus können Sie lange ausgeführte Agent-Workflows ausführen, die mehrere Toolaufrufe und komplexe Gründe umfassen, ohne darauf zu warten, dass sie synchron abgeschlossen werden. Senden Sie Ihre Anforderung mit background=True, empfangen Sie sofort eine Antwort-ID, und fragen Sie das Ergebnis ab, wenn es bereit ist. Dies ist besonders nützlich für Agents, die mehrere Datenquellen abfragen oder mehrere Tools in einer einzigen Anforderung miteinander verketten.

Erstellen einer Hintergrundanforderung

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"

Abstimmung über das Ergebnis

Wird responses.retrieve() verwendet, um den Status zu überprüfen, bis er einen Terminalzustand erreicht:

from time import sleep

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

print(response.output_text)

Hintergrundmodus mit MCP

Zur Sicherheit erfordert die Supervisor-API eine explizite Benutzergenehmigung, bevor ein MCP-Toolaufruf im Hintergrundmodus ausgeführt wird. Wenn die Agentenschleife ein MCP-Tool auswählt, wird die Antwort mit einem mcp_approval_request abgeschlossen. Sie können den Toolnamen, die Serverbezeichnung und die Argumente überprüfen, die das Modell übergeben soll:

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

Um den Toolaufruf zu genehmigen und die Agentschleife fortzusetzen, übergeben Sie einen mcp_approval_response Rücklauf in das input Feld mit dem vollständigen Unterhaltungsverlauf:

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

Note

Antworten im Hintergrundmodus werden maximal 30 Tage lang in der Datenbank aufbewahrt.

Unterstützte Tools

Sie definieren Tools im tools Array Ihrer Anforderung. Jeder Eintrag gibt ein type Und ein Konfigurationsobjekt mit demselben Schlüssel an. Ein Genie Space-Tool hat beispielsweise "type": "genie_space" und ein "genie_space": {...} Objekt. Die API unterstützt die folgenden Tooltypen:

Tooltyp Description Geltungsbereich
genie_space Ein Genie Space wird abgefragt, um Fragen zu Ihren Daten zu beantworten. Parameter: space_id, description. genie
uc_function Ruft eine Unity-Katalogfunktion als Agenttool auf. Parameter: name, description. unity-catalog
uc_connection Stellt über eine Verbindung mit dem Unity-Katalog eine Verbindung zu einem externen MCP-Server her. Parameter: name, description. Legen Sie für Azure Databricks verwaltete Systemverbindungen name auf einen system_ai_agent_* Connector fest (siehe Step 3 (Optional): Herstellen einer Verbindung mit Diensten von Drittanbietern mit vom System verwalteten Verbindungen). Hinweis: Benutzerdefinierte MCP-Server auf Apps werden noch nicht unterstützt. unity-catalog
app Ruft einen Azure Databricks App-Endpunkt auf. Parameter: name, description. apps
knowledge_assistant Ruft einen Knowledge Assistant-Endpunkt auf. Parameter: knowledge_assistant_id, description. model-serving
function Ruft ein clientseitiges Funktionstool auf, das im Anwendungscode ausgeführt wird. Parameter: name, description, parameters. None

Unterstützte Parameter

Jede Anforderung an die Supervisor-API akzeptiert die folgenden Parameter.

  • input: die zu sendenden Unterhaltungsnachrichten.
  • tools: Gehostete Tooldefinitionen (genie_space, uc_function, knowledge_assistant, appuc_connection) und clientseitige Funktionstools (function). Siehe Schritt 4 (Optional): Hinzufügen eines clientseitigen Funktionstools.
  • instructions: eine Systemaufforderung, um das Verhalten des Vorgesetzten zu leiten.
  • stream: Auf true eingestellt, um Antworten zu streamen.
  • background: Auf true festlegen, um die Anforderung asynchron auszuführen. Gibt eine Antwort-ID zurück, mit der Sie responses.retrieve() abfragen. Siehe Hintergrundmodus.
  • trace_destination: optionales Objekt mit catalog_name, schema_name, und table_prefix Feldern. Bei Festlegung schreibt die Supervisor-API eine Ablaufverfolgung der vollständigen Agentschleife in die angegebenen Unity-Katalogtabellen. Übergeben Sie extra_body über den Python-Client.

Die API unterstützt keine Ableitungsparameter wie temperature. Der Server verwaltet diese intern.

Einschränkungen

Die Supervisor-API hat die folgenden Einschränkungen:

  • Laufzeit des Hintergrundmodus: Anforderungen im Hintergrundmodus haben eine maximale Ausführungszeit von 30 Minuten.
  • Streaming im Hintergrundmodus: stream und background können nicht beide true in derselben Anforderung sein.
  • Dauerhafte Ausführung: Automatische Wiederherstellung von Fehlern oder Unterbrechungen mit Garantien für eine genau einmalige Ausführung der Agentschleife wird nicht unterstützt.
  • Azure Databricks Apps OBO wird nicht unterstützt: Die Autorisierung im Auftrag des Benutzers wird für die Supervisor-API nicht unterstützt. Um die Supervisor-API in Azure Databricks Apps zu verwenden, verwenden Sie systemautorisierung und erteilen Sie Berechtigungen für Ihre Tools.

Nächste Schritte

  • Last updated on