Łączenie narzędzi agenta sztucznej inteligencji z usługami zewnętrznymi

Artykuł
02/04/2025

Ważny

Ta funkcja jest dostępna w publicznej wersji zapoznawczej.

Dowiedz się, jak połączyć narzędzia agenta sztucznej inteligencji z aplikacjami zewnętrznymi, takimi jak Slack, Google Calendar lub dowolna usługa z interfejsem API przy użyciu żądań HTTP. Agenci mogą używać zewnętrznych narzędzi do automatyzowania zadań, wysyłania komunikatów i pobierania danych z platform innych firm.

Aby dowiedzieć się więcej o narzędziach agentów AI, zobacz narzędzia agenta sztucznej inteligencji.

Wymagania

Aby połączyć narzędzia agenta z usługami zewnętrznymi, musisz spełnić następujące wymagania:

Skonfiguruj uwierzytelnianie w usłudze zewnętrznej przy użyciu jednej z następujących metod:
- Token elementu nośnego: uzyskaj token elementu nośnego na potrzeby prostego uwierzytelniania opartego na tokenach.
- OAuth 2.0 Machine-to-Machine: utwórz aplikację i skonfiguruj ją w celu włączenia uwierzytelniania maszyny na maszynę.
- Protokół OAuth 2.0 Współdzielony między Użytkownikiem a Maszyną: uwierzytelnianie z interakcją użytkownika w celu udostępnienia dostępu między tożsamością usługi a maszyną.
Obszar roboczy musi obsługiwać Unity Catalog.
Musisz mieć łączność sieciową z zasobu obliczeniowego usługi Databricks z usługą zewnętrzną. Zobacz Zalecenia dotyczące sieci dla Lakehouse Federation.
W środowisku Databricks Runtime w wersji 15.4 lub nowszej należy użyć środowiska obliczeniowego z trybem dostępu pojedynczego użytkownika.
Musisz mieć usługę SQL Warehouse pro lub bezserwerową. Zobacz typy magazynów SQL.

Metody uwierzytelniania dla usług zewnętrznych

Token uwierzytelniający: Token uwierzytelniający to prosty mechanizm uwierzytelniania oparty na tokenach, w którym token jest wystawiany klientowi i używany do uzyskiwania dostępu do zasobów bez konieczności stosowania dodatkowych poświadczeń. Token jest dołączany do nagłówka żądania i przyznaje dostęp tak długo, jak jest prawidłowy.

OAuth maszyna-do-maszyny: Uwerytelnienie maszyna-do-maszyny OAuth (M2M) jest używane, kiedy dwa systemy lub aplikacje muszą się komunikować bez bezpośredniego zaangażowania użytkownika. Tokeny są wystawiane dla zarejestrowanego klienta maszynowego, który używa własnych danych uwierzytelniających do uwierzytelniania. Jest to idealne rozwiązanie w przypadku zadań komunikacji między serwerami, mikrousług i automatyzacji, w których nie jest potrzebny kontekst użytkownika.

Współdzielony OAuth użytkownika na maszynę: Uwierzytelnianie OAuth użytkownika na maszynę umożliwia jedną tożsamość użytkownika na uwierzytelnianie i współdzielenie tego samego zestawu poświadczeń między wieloma klientami. Wszyscy użytkownicy mają ten sam token dostępu. Takie podejście jest odpowiednie dla urządzeń udostępnionych lub środowisk, w których wystarczająca jest spójna tożsamość użytkownika, ale zmniejsza odpowiedzialność i śledzenie poszczególnych osób.

Tworzenie połączenia z usługą zewnętrzną

Najpierw utwórz połączenie Unity Catalog z usługą zewnętrzną, zawierające ścieżkę oraz dane uwierzytelniające do uzyskania dostępu do usługi.

Zalety korzystania z połączenia z katalogiem Unity obejmują następujące elementy:

Bezpieczne zarządzanie poświadczeniami: Sekrety i tokeny są bezpiecznie przechowywane i zarządzane w Unity Catalog, dzięki czemu nigdy nie są ujawniane użytkownikom.
Szczegółowa kontrola dostępu: Katalog Unity umożliwia precyzyjną kontrolę nad tym, kto może używać połączeń z uprawnieniami USE_CONNECTION i MANAGE_CONNECTION lub zarządzać nimi.
Wymuszanie tokenu przypisanego do hosta: tokeny są ograniczone do host_name określonych podczas tworzenia połączenia, co zapewnia, że nie mogą być używane z nieautoryzowanymi hostami.

Wymagane uprawnienia: administrator magazynu metadanych lub użytkownik z uprawnieniami CREATE CONNECTION.

Utwórz połączenie przy użyciu jednej z następujących metod:

Użyj interfejsu użytkownika Eksploratora katalogu.
Wykonaj polecenie CREATE CONNECTION SQL w notesie usługi Azure Databricks lub edytorze zapytań SQL usługi Databricks.
Użyj interfejsu API REST usługi Databricks lub interfejsu wiersza polecenia usługi Databricks, aby utworzyć połączenie. Zobacz POST /api/2.1/unity-catalog/connections oraz polecenia Unity Catalog.

Eksplorator wykazu

Użyj interfejsu użytkownika Eksploratora katalogu, aby utworzyć połączenie.

W obszarze roboczym usługi Azure Databricks kliknij ikonę katalogu Catalog.
W górnej części okienka katalogu kliknij ikonę Ikona Dodaj i wybierz pozycję Dodaj połączenie z menu.

Alternatywnie na stronie szybki dostęp do kliknij przycisk Zewnętrzne dane >, przejdź do karty połączenia, a następnie kliknij przycisk Utwórz połączenie.
Kliknij pozycję Utwórz połączenie.
Wprowadź przyjazną dla użytkownika nazwę połączenia .
Wybierz typ połączenia HTTP.
Wybierz typ uwierzytelniania z następujących opcji:
- token elementu nośnego
- OAuth maszynowo-maszynowy
- Udostępnianie OAuth użytkownika dla maszyny
Na stronie Authentication wprowadź następujące właściwości połączenia dla połączenia HTTP.

Dla tokenu elementu nośnego:
- gospodarz: na przykład https://databricks.com
- port: na przykład 443
- token elementu nośnego: na przykład bearer-token
- ścieżka podstawowa: na przykład /api/
W przypadku tokenu OAuth między maszynami:
- identyfikator klienta: unikatowy identyfikator utworzonej aplikacji.
- klucz tajny klienta: wpis tajny lub hasło wygenerowane dla utworzonej aplikacji.
- zakres OAuth: zakres, który ma być udzielany podczas autoryzacji użytkownika. Parametr 'zakres' jest wyrażony jako lista ciągów rozdzielanych spacjami, z uwzględnieniem wielkości liter. Na przykład channels:read channels:history chat:write
- punkt końcowy tokenu: używany przez klienta do uzyskania tokenu dostępu przez przedstawienie tokenu udzielania autoryzacji lub tokenu odświeżania. Zazwyczaj w formacie https://authorization-server.com/oauth/token
Dla tokenu współdzielonego użytkownika OAuth i maszyny:
- identyfikator klienta: unikatowy identyfikator utworzonej aplikacji.
- klucz tajny klienta: wpis tajny lub hasło wygenerowane dla utworzonej aplikacji.
- zakres OAuth: zakres, który ma być udzielany podczas autoryzacji użytkownika. Parametr 'zakres' jest wyrażony jako lista ciągów rozdzielanych spacjami, z uwzględnieniem wielkości liter. Na przykład channels:read channels:history chat:write
- punkt końcowy autoryzacji: aby uwierzytelnić się przy użyciu właściciela zasobu za pośrednictwem przekierowania agenta użytkownika, zazwyczaj w formacie https://authorization-server.com/oauth/authorize
- punkt końcowy tokenu: używany przez klienta do uzyskania tokenu dostępu przez przedstawienie tokenu udzielania autoryzacji lub tokenu odświeżania. Zazwyczaj w formacie https://authorization-server.com/oauth/token
Notatka

W przypadku udostępnionej autoryzacji OAuth użytkownika do maszyny zostanie wyświetlony monit o zalogowanie się przy użyciu protokołu HTTP, korzystając z poświadczeń OAuth.
Kliknij pozycję Utwórz połączenie.

SQL

Użyj polecenia CREATE CONNECTION SQL, aby utworzyć połączenie.

Notatka

Nie można użyć polecenia SQL do utworzenia połączenia, które używa maszyny OAuth do udostępnionejużytkownika. Zamiast tego zobacz instrukcje interfejsu użytkownika Eksploratora wykazu.

Aby utworzyć nowe połączenie przy użyciu tokenu elementu nośnego , uruchom następujące polecenie w notesie lub edytorze zapytań SQL usługi Databricks:

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

Usługa Databricks zaleca używanie sekretów zamiast ciągów w postaci tekstu nieszyfrowanego dla poufnych wartości, takich jak poświadczenia. Na przykład:

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

Aby utworzyć nowe połączenie przy użyciu maszyny OAuth na maszynie, uruchom następujące polecenie w notesie lub edytorze zapytań SQL usługi Databricks:

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

Wysyłanie żądania HTTP do systemu zewnętrznego

Teraz, gdy masz połączenie, dowiedz się, jak wysyłać żądania HTTP do usługi przy użyciu wbudowanej funkcji SQL http_request.

Wymagane uprawnienia:USE CONNECTION na obiekcie połączenia.

Uruchom następujące polecenie SQL w notesie lub edytorze SQL usługi Databricks. Zastąp wartości symboli zastępczych:

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: obiekt połączenia określający hosta, port, base_path i poświadczenia dostępu.
http-method: metoda żądania HTTP użyta do wykonania wywołania. Na przykład: GET, POST, PUT, DELETE
path: ścieżka do połączenia po base_path w celu wywołania zasobu usługi.
json: Treść JSON do wysłania z żądaniem.
headers: mapa określająca nagłówki żądań.

Tworzenie narzędzia funkcji katalogu Unity

Po zweryfikowaniu, czy połączenie działa prawidłowo, utwórz funkcję katalogu Unity korzystającą z połączenia. Poniższy przykład tworzy narzędzie funkcji katalogu Unity, którego agent może użyć do zamieszczenia wiadomości w usłudze Slack.

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

Stwórz narzędzie w kodzie agenta

Aby wysyłać żądania HTTP do usług zewnętrznych za pomocą języka Python, użyj funkcji http_request z biblioteki databricks-sdk. Ta funkcja wysyła żądanie HTTP do usługi zewnętrznej przy użyciu połączenia Unity Catalog do uwierzytelnienia.

Wymagane uprawnienia:USE CONNECTION na obiekcie połączenia.

Poniższy przykład tworzy zewnętrzne żądanie HTTP z poziomu kodu agenta.

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: obiekt połączenia określający hosta, port, base_path i poświadczenia dostępu.
method: metoda żądania HTTP użyta do wykonania wywołania. Na przykład: GET, POST, PUT, DELETE
path: ścieżka do połączenia po base_path w celu wywołania zasobu usługi.
json: Treść JSON do wysłania z żądaniem.
headers: Mapa określająca nagłówki żądań.

Przykładowe notesy

W poniższych notesach przedstawiono sposób tworzenia narzędzi agenta sztucznej inteligencji łączących się z usługami Slack, OpenAI i Azure AI search.

Udostępnij za pośrednictwem

Łączenie narzędzi agenta sztucznej inteligencji z usługami zewnętrznymi

Wymagania

Metody uwierzytelniania dla usług zewnętrznych

Tworzenie połączenia z usługą zewnętrzną

Eksplorator wykazu

SQL

Wysyłanie żądania HTTP do systemu zewnętrznego

Tworzenie narzędzia funkcji katalogu Unity

Stwórz narzędzie w kodzie agenta

Przykładowe notesy

Narzędzie agenta obsługi komunikatów usługi Slack

Narzędzie agenta openAI AI

Narzędzie agenta usługi Azure AI Search

Opinia

Dodatkowe zasoby