Erstellen eines benutzerdefinierten Agents mithilfe der 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.

Sie können einen Azure Databricks Apps-Agent erstellen, der die Supervisor-API (Beta) für die Orchestrierung verwendet, anstatt die Agentschleife in Ihrem eigenen Code zu verwalten. Das Ergebnis entspricht dem Erstellen eines benutzerdefinierten Agents: einer bereitgestellten App mit einer Chat-UI, einem Endpunkt und einer /invocations Authentifizierung. Der Unterschied besteht darin, dass Azure Databricks die Agentschleife für Sie ausführt. Ihre agent.py führt einen einzelnen API-Aufruf durch und Azure Databricks behandelt die Toolauswahl, Ausführung und Antwortsynthese.

Die Supervisor-API funktioniert mit einem der unterstützten Foundation-Modelle. Ändern Sie das model Feld, um Anbieter zu wechseln, ohne ihre Tooldefinitionen oder Handlerlogik zu berühren.

Wann sollte die Supervisor-API verwendet werden?

Die Supervisor-API funktioniert gut, wenn Ihr Agent nur Azure Databricks gehostete Tools verwendet und keine benutzerdefinierte Logik zwischen Toolaufrufen benötigt. Verwenden Sie stattdessen eine benutzerdefinierte Agent-Schleife , wenn Ihr Agent eine der folgenden Aktionen erfordert:

  • Clientseitige Funktionstools (die Supervisor-API kann gehostete und clientseitige Tools in einer Anforderung nicht kombinieren)
  • Andere Agent-Endpunkte als Agent Bricks Knowledge Assistant-Endpunkte
  • Benutzerdefinierte Retriever, benutzerdefinierte Eingaben/Ausgaben oder feingranulierte Streaming-Steuerung
  • Benutzerdefinierte Python Logik zwischen Toolaufrufen, z. B. bedingte Verzweigung oder Zustandsverwaltung
  • Steuern von Rückschlussparametern wie temperature

Die vollständige API-Referenz und die unterstützten Parameter finden Sie unter Supervisor-API (Beta).

Anforderungen

Erstellen eines benutzerdefinierten Agents mithilfe der Supervisor-API

Der empfohlene Ausgangspunkt ist das Erstellen einer neuen App aus der neuesten Databricks-App-Vorlage. Die neuesten Vorlagen umfassen eine integrierte Fähigkeit für KI-Codierungsassistenten use-supervisor-api sowie eine add-tools Fähigkeit zum Hinzufügen von gehosteten Tools.

Um eine neue App aus einer Vorlage zu erstellen, lesen Sie im Abschnitt "Einen KI-Agenten erstellen und auf Databricks Apps bereitstellen".

Nachdem Ihre App über die neueste Vorlage eingerichtet wurde, öffnen Sie das Projekt in Ihrem KI-Codierungs-Assistenten, und führen Sie Folgendes aus:

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

Mit dieser Fähigkeit können Sie Ihren agent_server/agent.py aktualisieren, um DatabricksOpenAI().responses.create() mit gehosteten Tools zu kontaktieren und die manuelle Agent-Schleife zu ersetzen. Außerdem werden die databricks-openai Abhängigkeiten hinzugefügt und die Betabeschränkungen notiert.

Das Ergebnis ist die gleiche bereitgestellte App mit einer Chat-UI, Authentifizierung und einem /invocations Endpunkt, aber mit einfacherem Agent-Code. Den vollständigen Bereitstellungsworkflow (Bereitstellen in Apps, Hinzufügen von Tools, Auswerten) finden Sie unter Erstellen eines KI-Agents und Bereitstellen in Databricks-Apps.

Unterstützte Tools und Parameter

Eine vollständige Liste der unterstützten Tooltypen, Anforderungsparameter und Codebeispiele finden Sie unter Supervisor-API (Beta).

Erteilen Sie für jedes tool, das Sie hinzufügen, auch die entsprechende Ressourcenberechtigung in databricks.yml. Beispiele finden Sie in den add-tools Fähigkeiten in .claude/skills/.

Autorisierung für gehostete Tools

Wenn die Supervisor-API die Agentschleife ausführt, werden gehostete Tools entweder mithilfe der Identität der App oder der anfordernden Benutzeridentität ausgeführt. Wählen Sie basierend darauf, ob alle Benutzer der App denselben Zugriff auf Ihre Tools nutzen sollen, oder jeder Benutzer sollte nur auf die berechtigungen zugreifen, die ihre eigenen Berechtigungen zulassen.

  • App-Autorisierung (Standard): Tools werden als Dienstprinzipal der App ausgeführt. Erteilen Sie dem Dienstprinzipal für jedes vom Agent verwendete Tool die entsprechende Berechtigung. Siehe App-Autorisierung.
  • Benutzerautorisierung: Tools werden als der Benutzer ausgeführt, der die Anforderung gesendet hat, sodass Unity-Katalogberechtigungen, Zeilenfilter und Spaltenmasken pro Benutzer gelten. Weitere Informationen finden Sie im folgenden Abschnitt.

Tools als der anfordernde Benutzer ausführen

Important

Die Benutzerautorisierung befindet sich in der öffentlichen Vorschau. Ihr Arbeitsbereichsadministrator muss sie aktivieren, bevor Sie Ihrer App Bereiche hinzufügen können. Siehe Hinzufügen von Bereichen zu einer App.

Um gehostete Tools im Namen des anfordernden Benutzers auszuführen, leiten Sie das Token des Benutzers an den DatabricksOpenAI Client weiter, und fügen Sie die benötigten Benutzerautorisierungsbereiche hinzu.

  1. Fügen Sie die Benutzerautorisierungsbereiche hinzu, die Ihre App benötigt. ai-gateway ist für den Zugriff auf die Supervisor-API erforderlich. Fügen Sie den Toolbereich für jeden Tooltyp hinzu, den der Agent verwendet:

    Tooltyp Erforderlicher Umfang
    Alle Tools ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    Der app Tooltyp wird mit der Benutzerautorisierung nicht unterstützt. Um einen App-Endpunkt als Tool aufzurufen, verwenden Sie stattdessen die App-Autorisierung. Informationen zum Hinzufügen von Bereichen über die Arbeitsbereichs-UI oder deklarative Automatisierungsbündel finden Sie unter Benutzerautorisierung.

  2. Übergeben Sie in Ihrem agent.py-Handler einen Workspace-Client eines Benutzers an DatabricksOpenAI. Dies ist die einzige Supervisor-spezifische Verkabelung: Anstatt eine Ressource direkt mit dem Benutzerclient aufzurufen, übergeben Sie sie an den Client, der die Agentschleife ausführt.

    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() liest das weitergeleitete Benutzertoken aus den Anforderungsheadern, die nur zur Abfragezeit aufgefüllt werden. Rufen Sie sie innerhalb der Handler invoke und stream auf, niemals in __init__ oder beim App-Start. Wenn das weitergeleitete Token fehlt, wird der resultierende Client nicht als anfordernden Benutzer authentifiziert. Wie Sie überprüfen, ob der Agent als Aufrufer und nicht als Serviceprinzipal der App ausgeführt wird, finden Sie unter Benutzerautorisierung.

  3. Erteilen Sie jedem Benutzer, der den Agenten ausführt, für jedes Tool die erforderliche Berechtigung, z. B. CAN_RUN für einen Genie Space oder CAN_QUERY für einen Endpunkt eines Wissensassistenten.

Weitere Ressourcen

  • Last updated on