Verbinden von KI-Agent-Tools mit externen Diensten

Artikel
02/18/2025

Wichtig

Dieses Feature befindet sich in der öffentlichen Vorschauversion.

Erfahren Sie, wie Sie KI-Agent-Tools mit externen Anwendungen wie Slack, Google Kalender oder einem beliebigen Dienst mit einer API mithilfe von HTTP-Anforderungen verbinden. Agents können extern verbundene Tools verwenden, um Aufgaben zu automatisieren, Nachrichten zu senden und Daten von Drittanbieterplattformen abzurufen.

Weitere Informationen zu Agent-Tools finden Sie unter KI-Agent-Tools.

Anforderungen

Um Agent-Tools mit externen Diensten zu verbinden, müssen Sie die folgenden Anforderungen erfüllen:

Richten Sie die Authentifizierung für den externen Dienst mit einer der folgenden Methoden ein:
- Bearertoken: Rufen Sie ein Bearertoken für die einfache tokenbasierte Authentifizierung ab.
- OAuth 2.0 Machine-to-Machine: Erstellen und Konfigurieren einer App zum Aktivieren der Computer-zu-Computer-Authentifizierung.
- OAuth 2.0 U2M-Freigabe (User-to-Machine): Authentifizieren Sie sich mit Benutzerinteraktion, um den Zugang zwischen Dienstidentität und Maschine freizugeben.
Ihr Arbeitsbereich muss für den Unity-Katalog aktiviert sein.
Sie müssen über eine Netzwerkverbindung von einer Databricks-Computerressource zum externen Dienst verfügen. Weitere Informationen finden Sie unter Netzwerkempfehlungen für Lakehouse Federation.
Sie müssen eine Computeressource mit Einzelbenutzerzugriffsmodus auf Databricks Runtime 15.4 und höher verwenden.
Sie müssen über ein SQL-Warehouse vom Typ „Pro“ oder „Serverlos“ verfügen. Siehe SQL Warehouse-Typen.

Authentifizierungsmethoden für externe Dienste

Bearertoken: Ein Bearertoken ist ein einfacher tokenbasierter Authentifizierungsmechanismus, bei dem ein Token an einen Client ausgegeben und für den Zugriff auf Ressourcen verwendet wird, ohne dass zusätzliche Anmeldeinformationen erforderlich sind. Das Token ist im Anforderungsheader enthalten und gewährt Zugriff, solange es gültig ist.

OAuth Maschine-zu-Maschine (empfohlen): OAuth Maschine-zu-Maschine (M2M)-Authentifizierung wird verwendet, wenn zwei Systeme oder Anwendungen ohne direkte Benutzerbeteiligung kommunizieren. Token werden an einen registrierten Clientcomputer ausgegeben, der seine eigenen Anmeldeinformationen zur Authentifizierung verwendet. Dies ist ideal für die Server-zu-Server-Kommunikation, Microservices und Automatisierungsaufgaben, bei denen kein Benutzerkontext erforderlich ist. Databricks empfiehlt die Verwendung von OAuth Machine-to-Machine, wenn sie verfügbar ist.

OAuth U2M-Freigabe (User-to-Machine): Die freigegebene OAuth-Authentifizierung ermöglicht es einer einzelnen Benutzeridentität, sich zu authentifizieren und denselben Satz Anmeldeinformationen über mehrere Clients oder Benutzer hinweg freizugeben. Alle Benutzer verwenden dasselbe Zugriffstoken. Dieser Ansatz eignet sich für freigegebene Geräte oder Umgebungen, in denen eine konsistente Benutzeridentität ausreichend ist. Die Verantwortlichkeit und Nachverfolgung von Einzelpersonen werden jedoch damit reduziert. Wählen Sie in Fällen, in denen die Anmeldung über Identitäten erforderlich ist, die Option „User to Machine Shared" aus.

Erstellen einer Verbindung mit dem externen Dienst

Erstellen Sie zunächst eine Unity Catalog-Verbindung mit dem externen Dienst, die einen Pfad und Anmeldeinformationen für den Zugriff auf den Dienst angibt.

Folgende Vorteile ergeben sich aus der Verwendung einer Unity Catalog-Verbindung:

Sichere Verwaltung von Anmeldeinformationen: Geheime Schlüssel und Token werden sicher im Unity-Katalog gespeichert und verwaltet, um sicherzustellen, dass sie nie für Benutzer verfügbar gemacht werden.
Präzise Zugriffssteuerung: Unity Catalog ermöglicht eine differenzierte Steuerung der Verbindungsverwendung oder -verwaltung mit den Berechtigungen „USE_CONNECTION“ und „MANAGE_CONNECTION“.
Hostspezifische Tokenerzwingung: Token sind auf die während der Verbindungserstellung angegebenen host_name-Werte beschränkt, um sicherzustellen, dass sie nicht mit nicht autorisierten Hosts verwendet werden können.

Erforderliche Berechtigungen: Metastore-Administrator oder Benutzer mit der Berechtigung „CREATE CONNECTION“.

Erstellen Sie eine Verbindung mit einer der folgenden Methoden:

Verwenden Sie die Benutzeroberfläche des Katalog-Explorers.
Führen Sie den SQL-Befehl CREATE CONNECTION in einem Azure Databricks-Notebook oder im SQL-Abfrage-Editor für Databricks aus.
Verwenden Sie die Databricks-REST-API oder die Databricks CLI, um eine Verbindung zu erstellen. Weitere Informationen finden Sie unter POST /api/2.1/unity-catalog/connections und Unity Catalog-Befehle.

Katalog-Explorer

Verwenden Sie die Benutzeroberfläche des Katalog-Explorers, um eine Verbindung zu erstellen.

Klicken Sie in Ihrem Azure Databricks-Arbeitsbereich auf Katalog.
Klicken Sie oben im Bereich Katalog auf das Symbol Hinzufügen, und wählen Sie im Menü Verbindung hinzufügen aus.

Klicken Sie alternativ auf der Seite Schnellzugriff auf die Schaltfläche Externe Daten >, navigieren Sie zur Registerkarte Verbindungen, und klicken Sie auf Verbindung erstellen.
Klicken Sie auf Neue Verbindung erstellen.
Geben Sie einen benutzerfreundlichen Verbindungsnamen ein.
Wählen Sie als Verbindungstyp die Option HTTP aus.
Wählen Sie einen Authentifizierungstyp aus den folgenden Optionen aus:
- Bearertoken
- OAuth Machine to Machine
- OAuth U2M-Freigabe (User-to-Machine)
Geben Sie auf der Seite Authentifizierung die folgenden Verbindungseigenschaften für die HTTP-Verbindung ein.

Für ein Bearertoken:
- Host: Beispiel: https://databricks.com
- Port: Beispiel: 443
- Bearertoken: z. B. bearer-token
- Basispfad: z. B. /api/
Für OAuth-Maschine-zu-Maschine-Token:
- Client-ID: Eindeutiger Bezeichner für die von Ihnen erstellte Anwendung.
- Client-Geheimnis: Geheimer Schlüssel oder Kennwort, das für Ihre erstellte Anwendung generiert wurde.
- OAuth scope: Bereich, der während der Benutzerautorisierung zugewiesen werden soll. Der Bereichsparameter wird als Liste mit durch Leerzeichen getrennten Zeichenfolgen ausgedrückt, bei denen die Groß-/Kleinschreibung beachtet wird. Beispiel: channels:read channels:history chat:write.
- Tokenendpunkt: Wird vom Client verwendet, um ein Zugriffstoken zu erhalten, indem die Autorisierungsgenehmigung oder das Aktualisierungstoken vorgewiesen werden. Das Format lautet in der Regel wie folgt: https://authorization-server.com/oauth/token.
Für ein von Benutzer zu Maschine gemeinsam genutztes OAuth-Token:
- Client-ID: Eindeutiger Bezeichner für die von Ihnen erstellte Anwendung.
- Client-Geheimnis: Geheimer Schlüssel oder Kennwort, das für Ihre erstellte Anwendung generiert wurde.
- OAuth scope: Bereich, der während der Benutzerautorisierung zugewiesen werden soll. Der Bereichsparameter wird als Liste mit durch Leerzeichen getrennten Zeichenfolgen ausgedrückt, bei denen die Groß-/Kleinschreibung beachtet wird. Zum Beispiel, channels:read channels:history chat:write
- Autorisierungsendpunkt: zur Authentifizierung beim Ressourcenbesitzer durch die Benutzer-Agent-Umleitung, üblicherweise im Format https://authorization-server.com/oauth/authorize.
- Tokenendpunkt: Wird vom Client verwendet, um ein Zugriffstoken zu erhalten, indem die Autorisierungsgenehmigung oder das Aktualisierungstoken vorgewiesen werden. Das Format lautet in der Regel wie folgt: https://authorization-server.com/oauth/token.
Hinweis

Für die gemeinsam genutzte OAuth-Authentifizierung zwischen Benutzer und Maschine werden Sie aufgefordert, sich mit HTTP einloggen, indem Sie Ihre OAuth-Anmeldeinformationen verwenden.
Klicken Sie auf Neue Verbindung erstellen.

SQL

Verwenden Sie den SQL-Befehl CREATE CONNECTION, um eine Verbindung zu erstellen.

Hinweis

Sie können den SQL-Befehl nicht verwenden, um eine Verbindung zu erstellen, die OAuth Machine to User Sharedverwendet. Lesen Sie stattdessen die Anweisungen auf der Benutzeroberfläche des Katalog-Explorers.

Um eine neue Verbindung mit einem Bearertoken zu erstellen, führen Sie den folgenden Befehl in einem Notebook oder dem SQL-Abfrage-Editor für Databricks aus:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token '<bearer-token>'
);

Databricks empfiehlt die Verwendung von Geheimnissen anstelle von Klartextzeichenfolgen für vertrauliche Werte wie Anmeldeinformationen. Beispiel:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token secret ('<secret-scope>','<secret-key-password>')
)

Um eine neue Verbindung mit der Methode OAuth Machine to Machine zu erstellen, führen Sie den folgenden Befehl in einem Notebook oder dem SQL-Abfrage-Editor für Databricks aus:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  client_id '<client-id>'
  client_secret '<client-secret>'
  oauth_scope '<oauth-scope1> <oauth-scope-2>'
  token_endpoint '<token-endpoint>'
)

Senden einer HTTP-Anforderung an das externe System

Nachdem Sie nun über eine Verbindung verfügen, senden Sie HTTP-Anforderungen mithilfe der integrierten SQL-Funktion http_request an den Dienst.

Erforderliche Berechtigungen: USE CONNECTION für das Verbindungsobjekt.

Führen Sie den folgenden SQL-Befehl in einem Notebook oder im Databricks-SQL-Editor aus. Ersetzen Sie die folgenden Platzhalterwerte:

SELECT http_request(
  conn => <connection-name>,
  method => <http-method>,
  path => <path>,
  json => to_json(named_struct(
    'text', text
  )),
  headers => map(
    'Accept', "application/vnd.github+json"
  )
);

connection-name: Das Verbindungsobjekt, das den Host, Port, base_path und Zugangsdaten angibt.
http-method: Die HTTP-Anforderungsmethode, die zum Ausführen des Aufrufs verwendet wird. Beispiel: GET, POST, PUT, DELETE
path: Der Pfad, der nach dem base_path verkettet werden soll, um die Dienstressource aufzurufen.
json: Der JSON-Text, der mit der Anforderung gesendet werden soll.
headers: Eine Zuordnung zum Angeben der Anforderungsheader.

Erstellen eines Unity Catalog-Funktionstools

Erstellen Sie nach der Überprüfung, dass die Verbindung ordnungsgemäß funktioniert, eine Unity Catalog-Funktion, die die Verbindung verwendet. Im folgenden Beispiel wird ein Unity Catalog-Funktionstool erstellt, mit dem ein Agent eine Nachricht an Slack bereitstellen kann:

CREATE OR REPLACE FUNCTION main.default.slack_post_message(
  text STRING COMMENT 'message content'
)
RETURNS STRING
COMMENT 'Sends a Slack message by passing in the message and returns the response received from the external service.'
RETURN (http_request(
  conn => 'test_sql_slack',
  method => 'POST',
  path => '/api/chat.postMessage',
  json => to_json(named_struct(
    'channel', "C032G2DAH3",
    'text', text
  ))
)).text

Ein Tool im Code eines Agenten erstellen

Um HTTP-Anforderungen an externe Dienste mit Python zu senden, verwenden Sie die http_request-Funktion aus der databricks-sdk-Bibliothek. Diese Funktion sendet eine HTTP-Anforderung an einen externen Dienst mithilfe einer Unity Catalog-Verbindung zur Authentifizierung.

Erforderliche Berechtigungen: USE CONNECTION für das Verbindungsobjekt.

Im folgenden Beispiel wird eine externe HTTP-Anforderung aus dem Agent-Code erstellt.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod

WorkspaceClient().serving_endpoints.http_request(
  conn="connection_name",
  method=ExternalFunctionRequestHttpMethod.POST,
  path="/api/v1/resource",
  json={"key": "value"},
  headers={"extra_header_key": "extra_header_value"},
)

conn: Das Verbindungsobjekt, das den Host, Port, base_path und die Zugriffsanmeldeinformationen angibt.
method: Die HTTP-Anforderungsmethode, die zum Ausführen des Aufrufs verwendet wird. Beispiel: GET, POST, PUT, DELETE
path: Der Pfad, der nach dem base_path verkettet werden soll, um die Dienstressource aufzurufen.
json: Der JSON-Text, der mit der Anforderung gesendet werden soll.
headers: Eine Zuordnung zum Angeben der Anforderungsheader.

Beispielnotebooks

Die folgenden Notizbücher veranschaulichen das Erstellen von KI-Agent-Tools, die eine Verbindung mit der Slack-, OpenAI- und Azure AI-Suche herstellen.

Teilen über

Verbinden von KI-Agent-Tools mit externen Diensten

Anforderungen

Authentifizierungsmethoden für externe Dienste

Erstellen einer Verbindung mit dem externen Dienst

Katalog-Explorer

SQL

Senden einer HTTP-Anforderung an das externe System

Erstellen eines Unity Catalog-Funktionstools

Ein Tool im Code eines Agenten erstellen

Beispielnotebooks

Messagingagententool von Slack

Microsoft Graph-API-Agent-Tool

KI-Agent-Tool für Azure KI-Suche

Feedback

Zusätzliche Ressourcen