Authentifizierung für KI-Agents

KI-Agents müssen sich häufig bei anderen Ressourcen authentifizieren, um Aufgaben auszuführen. Ein bereitgestellter Agent muss z. B. auf einen Vector Search-Index zugreifen, um unstrukturierte Daten abzufragen, einen Endpunkt, der ein Foundation-Modell aufruft, oder Unity-Katalogfunktionen zum Ausführen benutzerdefinierter Logik.

Diese Seite behandelt Authentifizierungsmethoden für Agents, die in Databricks-Apps bereitgestellt werden. Informationen zu Agents, die auf Model Serving-Endpunkten bereitgestellt werden, finden Sie unter Authentifizierung für KI-Agents (Model Serving).

Databricks-Apps bieten zwei Authentifizierungsmethoden für Agents. Jede Methode dient verschiedenen Anwendungsfällen:

Sie können beide Methoden in einem einzigen Agent kombinieren. Verwenden Sie beispielsweise die App-Autorisierung, um auf einen freigegebenen Vektorsuchindex zuzugreifen, während die Benutzerautorisierung zum Abfragen von benutzerspezifischen Tabellen verwendet wird.

Konfigurieren Sie die Authentifizierung mit der Benutzeroberfläche des Arbeitsbereichs oder mit Deklarativen Automatisierungs-Bundles.

Sie können alle Authentifizierungseinstellungen auf zwei Arten konfigurieren:

• Arbeitsbereichsbenutzeroberfläche: Bearbeiten Sie die App, und verwalten Sie Ressourcen und Bereiche aus dem Schritt "Konfigurieren" . Empfohlen, wenn Sie eine einzelne App im Arbeitsbereich durchlaufen.
• Deklarative Automatisierungsbundle: Deklarieren von Ressourcen, Bereichen und Umgebungsvariablen in einer databricks.yml Datei und Bereitstellen mit databricks bundle deploy. Empfohlen, wenn Sie Git-basierte Versionsverwaltung, CI/CD oder denselben Agent für alle Arbeitsbereiche versenden möchten. Alle Agentvorlagen werden mit einer databricks.yml.

Beide Pfade erzeugen dieselbe Laufzeitkonfiguration. Der Rest dieser Seite zeigt jede Anweisung in beiden Formularen an, sodass Sie eine auswählen und in Ihrem Projekt konsistent bleiben können.

Um der App eine Ressource über einen der beiden Pfade hinzuzufügen, müssen Can Manage Sie über die Berechtigung für die Ressource und die App verfügen.

Die vollständige Bündelreferenz finden Sie unter "App-Ressource " und "app.resources". Eine exemplarische Vorgehensweise für ein End-to-End-Bundle finden Sie unter Manage Databricks apps using Declarative Automation Bundles.

App-Autorisierung

Standardmäßig authentifizieren sich Databricks-Apps mithilfe der App-Autorisierung. Databricks erstellt beim Erstellen der App automatisch einen Dienstprinzipal, der als Identität der App fungiert.

Alle Benutzer, die mit der App interagieren, verwenden dieselben Berechtigungen, die für den Dienstprinzipal definiert sind. Dieses Modell eignet sich gut, wenn alle Benutzer dieselben Daten sehen sollen oder wenn die App freigegebene Vorgänge ausführt, die nicht an benutzerspezifische Zugriffssteuerungen gebunden sind.

Ausführliche Informationen zur App-Autorisierung finden Sie unter "App-Autorisierung".

Erteilen von Berechtigungen für das MLflow-Experiment

Ihr Agent benötigt Zugriff auf ein MLflow-Experiment, um Ablaufverfolgungen und Auswertungsergebnisse zu protokollieren. Erteilen Sie dem Dienstprinzipal Can Edit die Berechtigung für das Experiment.

Benutzeroberfläche des Arbeitsbereichs

1. Klicken Sie auf der Startseite Ihrer App auf "Bearbeiten ".
2. Wechseln Sie zum Schritt "Konfigurieren" .
3. Fügen Sie im Abschnitt "App-Ressourcen " die MLflow-Experimentressource mit Can Edit Berechtigungen hinzu.

Siehe Hinzufügen einer MLflow-Experimentressource zu einer Databricks-App.

Deklarative Automatisierungspakete

1. Deklarieren Sie das Experiment unter der App-Liste resources in databricks.yml. Der name, den Sie der Ressource zuweisen, wird später referenziert, wenn Sie Umgebungsvariablen verknüpfen.

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   

2. Bundle neu bereitstellen:

   databricks bundle deploy
   databricks bundle run my_agent
   

Alle Felder finden Sie unter "app.resources.experiment ".

Erteilen von Berechtigungen für andere Databricks-Ressourcen

Wenn Ihr Agent andere Databricks-Ressourcen verwendet, z. B. Genie Spaces, Vector Search-Indizes oder SQL Warehouses, erteilen Sie den Dienstprinzipalberechtigungen für jedes.

Um auf das Eingabeaufforderungsprotokoll zuzugreifen, erteilen Sie CREATE FUNCTION, EXECUTE und MANAGE Berechtigungen für das Unity Katalog-Schema zum Speichern von Eingabeaufforderungen.

Wenn Sie Zugriff auf Unity-Katalogressourcen gewähren, müssen Sie auch Berechtigungen für alle nachgelagerten abhängigen Ressourcen erteilen. Wenn Sie beispielsweise Zugriff auf einen Genie Space gewähren, müssen Sie auch den Zugriff auf die zugrunde liegenden Tabellen, SQL-Lagerhäuser und Unity-Katalogfunktionen gewähren.

Benutzeroberfläche des Arbeitsbereichs

Fügen Sie der App Ressourcen über den Abschnitt "App-Ressourcen " hinzu, wenn Sie die App im Databricks-Arbeitsbereich erstellen oder bearbeiten.

1. Klicken Sie auf der Startseite Ihrer App auf "Bearbeiten ".
2. Wechseln Sie zum Schritt "Konfigurieren" .
3. Klicken Sie in App-Ressourcen auf +Ressource hinzufügen für jede Ressource, die der Agent verwendet, und legen Sie die Berechtigung fest.

Eine vollständige Liste der unterstützten Ressourcen und Screenshots finden Sie unter Hinzufügen von Ressourcen zu einer Databricks-App .

Deklarative Automatisierungspakete

1. Deklarieren Sie jede Ressource, die der Agent in der resources Liste unter Ihrer App databricks.ymlverwendet. Das folgende Beispiel zeigt einen Agent, der ein MLflow-Experiment, einen dienenden Endpunkt, einen Genie Space, ein SQL Warehouse, einen Vector Search-Index, eine Unity Catalog-Funktion und eine Lakebase-Instanz verwendet. Auf jede Ressource name wird von config.env über value_from verwiesen, sodass der Agent zur Laufzeit den aufgelösten Bezeichner erhält.

   bundle:
     name: my_agent
   
   resources:
     apps:
       my_agent:
         name: 'my-agent'
         description: 'Custom agent deployed on Databricks Apps'
         source_code_path: ./
         config:
           command: ['uv', 'run', 'start-app']
           env:
             - name: MLFLOW_EXPERIMENT_ID
               value_from: 'experiment'
             - name: LAKEBASE_INSTANCE_NAME
               value_from: 'database'
   
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   
           - name: 'llm'
             serving_endpoint:
               name: 'databricks-claude-sonnet-4-5'
               permission: 'CAN_QUERY'
   
           - name: 'sales-genie'
             genie_space:
               space_id: '<genie-space-id>'
               permission: 'CAN_RUN'
   
           - name: 'warehouse'
             sql_warehouse:
               id: '<warehouse-id>'
               permission: 'CAN_USE'
   
           - name: 'docs-index'
             uc_securable:
               securable_full_name: 'main.docs.chunks_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'lookup-function'
             uc_securable:
               securable_full_name: 'main.tools.order_lookup'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'
   
           - name: 'database'
             database:
               instance_name: '<lakebase-instance-name>'
               database_name: 'databricks_postgres'
               permission: 'CAN_CONNECT_AND_CREATE'
   
   targets:
     dev:
       mode: development
       default: true
   

   Von Bedeutung

   Jeder value_from Wert in config.env muss mit einem name Feld in der resources Liste übereinstimmen. Nichtübereinstimmungen führen dazu, dass die Umgebungsvariable in der bereitgestellten App zu None aufgelöst wird.

2. Bereitstellen und Starten des Bundles:

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent
   

   bundle deploy lädt die Quelle hoch und konfiguriert Ressourcen. bundle run startet oder startet neu die App mit dem neuesten Quellcode. Das Argument bundle run ist der YAML-Schlüssel unter resources.apps (hier my_agent) und nicht das name-Feld der App, die bereitgestellt wurde.

Das vollständige Schema jedes Ressourcenuntertyps finden Sie unter "app.resources".

In der folgenden Tabelle sind die mindestberechtigungen aufgeführt, die in den obigen Beispielen verwendet werden, und der entsprechende Deklarative Automation Bundles-Wert für jeden Ressourcentyp:

Befolgen Sie das Prinzip der geringsten Rechte. Erteilen Sie dem Dienstprinzipal nur die Berechtigungen, die der Agent benötigt, und verwenden Sie einen dedizierten Dienstprinzipal pro App. Die vollständige Liste finden Sie unter "Bewährte Methoden für Sicherheit".

Benutzerautorisierung

Die Benutzerautorisierung ermöglicht es einem Agent, mit der Identität des Benutzers zu handeln, der die Anforderung vornimmt. Dies bietet Folgendes:

• Benutzerspezifischer Zugriff auf vertrauliche Daten
• Feinkörnige Datensteuerelemente, die durch den Unity Catalog durchgesetzt werden
• Benutzerspezifische Prüfprotokolle
• Automatisches Erzwingen von zeilenbasierten Filtern und Spaltenmasken.

Verwenden Sie die Benutzerautorisierung, wenn Ihr Agent auf Ressourcen zugreifen muss, indem Sie die Identität des anfordernden Benutzers anstelle des Dienstprinzipals der App verwenden.

Funktionsweise der Benutzerautorisierung

Wenn Sie die Benutzerautorisierung für Ihren Agent konfigurieren:

1. Fügen Sie Ihrer App API-Bereiche hinzu: Definieren Sie, auf welche Databricks-APIs die App im Auftrag von Benutzern zugreifen kann. Siehe Hinzufügen von Bereichen zu einer App.
2. Benutzeranmeldeinformationen sind eingeschränkt: Databricks verwendet die Anmeldeinformationen des Benutzers und beschränkt sie nur auf die von Ihnen definierten API-Bereiche.
3. Tokenweiterleitung: Das Downscoped-Token wird Ihrer App über den x-forwarded-access-token HTTP-Header zur Verfügung gestellt.
4. MLflow AgentServer speichert das Token: Der Agentserver speichert dieses Token automatisch pro Anforderung für den bequemen Zugriff im Agentcode.

Konfigurieren Sie die Benutzerautorisierung, indem Sie Bereiche in der Benutzeroberfläche von Databricks Apps hinzufügen, wenn Sie Ihre App erstellen oder bearbeiten oder die API programmgesteuert verwenden. Ausführliche Anweisungen finden Sie unter Hinzufügen von Bereichen zu einer App .

Agents mit Benutzerautorisierung können auf die folgenden Databricks-Ressourcen zugreifen:

• SQL Warehouse
• Genie Space
• Dateien und Verzeichnisse
• Modellbereitstellungs-Endpunkt
• Vektorsuchindex
• Unity-Katalogverbindungen
• Unity-Katalogtabellen

Implementieren der Benutzerautorisierung

Um die Benutzerautorisierung zu implementieren, müssen Sie Ihrer App Autorisierungsbereiche hinzufügen. Bereiche beschränken, was die App im Namen des Benutzers tun kann. Eine Liste der verfügbaren Bereiche und Bereichsemantik finden Sie unter Bereichsbasierte Sicherheits- und Berechtigungseskalation.

Benutzeroberfläche des Arbeitsbereichs

1. Wechseln Sie auf der Benutzeroberfläche von Databricks zu den Autorisierungseinstellungen Ihrer App.
2. Klicken Sie unter "Benutzerautorisierung" auf "+ Bereich hinzufügen ", und wählen Sie die Bereiche aus, die die App für den Zugriff auf Ressourcen im Namen des Benutzers benötigt.
3. Speichern Sie die Änderungen, und starten Sie die App neu.

Deklarative Automatisierungspakete

1. Deklarieren Sie Bereiche unter user_api_scopes der App-Ressource in databricks.yml:

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         user_api_scopes:
           - sql
           - dashboards.genie
           - serving.serving-endpoints
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   

2. Erneutes Bereitstellen des Bundles und Neustarten der App:

   databricks bundle deploy
   databricks bundle run my_agent
   

   Note

   Nachdem Sie die Benutzerautorisierung für einen Arbeitsbereich zum ersten Mal aktiviert haben, müssen Sie vorhandene Apps neu starten, bevor sie Bereiche verwenden können. Siehe Hinzufügen von Bereichen zu einer App.

Um die Benutzerautorisierung in Ihrem Agentcode zu konfigurieren, rufen Sie den Header für diese Anforderung vom AgentServer ab, und erstellen Sie einen Arbeitsbereichsclient mit diesen Anmeldeinformationen.

1. Importieren Sie im Agentcode das Authentifizierungshilfsprogramm:

   Wenn Sie eine der bereitgestellten Vorlagen aus databricks/app-templates verwenden, importieren Sie das bereitgestellte Hilfsprogramm:

   from databricks_app.utils import get_user_workspace_client
   

   Andernfalls importieren Sie aus den Agent-Server-Dienstprogrammen:

   from agent_server.utils import get_user_workspace_client
   

   Die get_user_workspace_client() Funktion verwendet den Agent-Server, um den x-forwarded-access-token Header zu erfassen und einen Arbeitsbereichsclient mit diesen Benutzeranmeldeinformationen zu erstellen und die Authentifizierung zwischen Dem Benutzer, der App und dem Agentserver zu verarbeiten.

2. Initialisieren Sie den Arbeitsbereichsclient zur Abfragezeit, nicht während des App-Starts:

   Von Bedeutung

   Rufen Sie get_user_workspace_client() innerhalb der invoke und stream Handler auf, nicht in __init__ oder beim App-Start. Benutzeranmeldeinformationen sind nur zur Abfragezeit verfügbar, wenn ein Benutzer eine Anforderung sendet. Beim Initialisieren während des App-Starts tritt ein Fehler auf, da noch kein Benutzerkontext vorhanden ist.

   # In your agent code (inside invoke or stream handler)
   user_client = get_user_workspace_client()
   
   
   # Use user_client to access Databricks resources with user permissions
   response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)
   

Eine vollständige Anleitung zum Hinzufügen von Bereichen und Grundlegendes zur bereichsbasierten Sicherheit finden Sie unter Bereichsbasierte Sicherheits- und Berechtigungseskalation. Fordern Sie nur die Mindestbereiche an, die Ihr Agent benötigt, und protokollieren Sie jede Aktion, die im Auftrag eines Benutzers ausgeführt wird; weitere Informationen finden Sie unter Bewährte Methoden für die Benutzerautorisierung.

Authentifizieren bei den Databricks MCP-Servern

Von Databricks verwaltete MCP-Server machen Vektorsuchindizes und Unity-Katalogfunktionen als Tools über URLs des Formulars https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> und https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>verfügbar. Eine Liste der verfügbaren Server und deren URL-Muster finden Sie unter Use Databricks managed MCP servers.

Um sich zu authentifizieren, gewähren Sie dem Dienstprinzipal des Agents (oder dem Benutzer bei Verwendung der Benutzerautorisierung) Zugriff auf jede nachgeschaltete Ressource in diesen Schemas.

Wenn Ihr Agent beispielsweise die folgenden MCP-Server-URLs verwendet:

• https://<your-workspace>/api/2.0/mcp/vector-search/prod/customer_support
• https://<your-workspace>/api/2.0/mcp/vector-search/prod/billing
• https://<your-workspace>/api/2.0/mcp/functions/prod/billing

Sie müssen Zugriff auf jeden Vektorsuchindex in prod.customer_support und prod.billing und jede Unity Catalog-Funktion in prod.billing gewähren.

Benutzeroberfläche des Arbeitsbereichs

Fügen Sie jeden Index und jede Funktion als Ressource unter App-Ressourcen hinzu. Führen Sie dieselben Schritte wie das Erteilen von Berechtigungen für andere Databricks-Ressourcen aus.

Deklarative Automatisierungspakete

1. Fügen Sie einen uc_securable Eintrag pro Index und pro Funktion unter der Liste Ihrer App resources hinzu:

   resources:
     apps:
       my_agent:
         resources:
           - name: 'support-index'
             uc_securable:
               securable_full_name: 'prod.customer_support.tickets_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'billing-index'
             uc_securable:
               securable_full_name: 'prod.billing.invoices_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'refund-function'
             uc_securable:
               securable_full_name: 'prod.billing.process_refund'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'
   

2. Bundle neu bereitstellen:

   databricks bundle deploy
   databricks bundle run my_agent
   

Benutzerdefinierte MCP-Server, die als eigene Databricks-Apps gehostet werden (App-Namen mit Präfix mcp-) werden noch nicht als Bundleressourcen unterstützt. Gewähren Sie dem Dienstprinzipal Can Use des Agents manuell Rechte auf der MCP-Server-App mit dem databricks apps update-permissions. Sehen Sie sich die Benutzerdefinierten Mcp-Server-Fähigkeiten im Agentvorlagen-Repository an.

Nächste Schritte

• Erstellen eines KI-Agents und Bereitstellen auf Databricks-Apps
• Verwalten von Databricks-Apps mit deklarativen Automatisierungspaketen
• Konfigurieren der Autorisierung in einer Databricks-App
• Hinzufügen von Ressourcen zu einer Databricks-App
• App-Ressourcenreferenz