Supervisor-API (Beta)

Important

Dieses Feature befindet sich in der Betaversion. Kontoadministratoren können den Zugriff auf dieses Feature über die Vorschauseite steuern. 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": {
        "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 und SharePoint. 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.

Ü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 oauth-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: Aktivieren der Ablaufverfolgung

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: 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

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, app, uc_connection).
  • 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.
  • Clientseitige Funktionsaufrufe: Nur gehostete Tools werden unterstützt. Sie können keine Tooldefinitionen function übergeben, damit sie vom Client ausgeführt werden, und Sie können gehostete Tools nicht mit clientseitigen function-Tools in derselben Anforderung kombinieren.
  • 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