Připojení nástrojů agenta AI k externím službám

Článek
02/21/2025

Důležitý

Tato funkce je ve verzi Public Preview.

Zjistěte, jak připojit nástroje agenta AI k externím aplikacím, jako je Slack, Google Calendar nebo jakákoli služba s rozhraním API pomocí požadavků HTTP. Agenti můžou používat externě připojené nástroje k automatizaci úloh, odesílání zpráv a načítání dat z platforem třetích stran.

Další informace o nástrojích agenta najdete v tématu nástroje agenta AI.

Požadavky

Pokud chcete připojit nástroje agenta k externím službám, musíte splnit následující požadavky:

Nastavte ověřování pro externí službu pomocí jedné z následujících metod:
- Nosný token: Získejte nosný token pro jednoduché ověřování na základě tokenu.
- OAuth 2.0 Machine-to-Machine: Vytvoření a konfigurace aplikace pro povolení ověřování mezi počítači
- OAuth 2.0 sdílení mezi uživatelem a strojem: Ověření prostřednictvím interakce uživatele pro sdílení přístupu mezi identitou služby a strojem.
Váš pracovní prostor musí mít povolen katalog Unity.
Musíte mít síťové připojení z výpočetního prostředku Databricks k externí službě. Podívejte se na doporučení pro síťování pro Lakehouse Federation.
Ve službě Databricks Runtime 15.4 a vyšší musíte použít výpočetní prostředky s režimem přístupu s jedním uživatelem.
Musíte mít profesionální nebo serverless SQL úložiště. Viz typy SQL Warehouse.

Metody ověřování pro externí služby

nosný token: nosný token je jednoduchý ověřovací mechanismus založený na tokenech, kdy se token vydává klientovi a používá se pro přístup k prostředkům bez nutnosti dalších přihlašovacích údajů. Token je součástí hlavičky požadavku a uděluje přístup, pokud je platný.

OAuth Machine-to-Machine (doporučeno): Ověřování OAuth Machine-to-Machine (M2M) se používá, když dva systémy nebo aplikace komunikují bez přímého zapojení uživatele. Tokeny se vydávají registrovanému klientovi počítače, který k ověření používá vlastní přihlašovací údaje. To je ideální pro úlohy komunikace mezi servery, mikroslužby a automatizace, kde není potřeba žádný kontext uživatele. Databricks doporučuje používat OAuth Machine-to-Machine, pokud je k dispozici.

Sdílení OAuth mezi uživateli a stroji: Sdílená autentizace OAuth typu uživatel-stroj umožňuje jedné identitě uživatele ověřit se a sdílet stejnou sadu přihlašovacích údajů mezi více klienty nebo uživateli. Všichni uživatelé sdílejí stejný přístupový token. Tento přístup je vhodný pro sdílená zařízení nebo prostředí, kde je dostatečná konzistentní identita uživatele, ale snižuje individuální odpovědnost a sledování. V případech, kdy je vyžadováno přihlášení identity, vyberte Uživatele ke sdílenému počítači.

Vytvoření připojení k externí službě

Nejprve vytvořte připojení katalogu Unity k externí službě, která určuje cestu a přihlašovací údaje pro přístup ke službě.

Mezi výhody použití připojení ke katalogu Unity patří:

zabezpečená správa přihlašovacích údajů: tajné kódy a tokeny se bezpečně ukládají a spravují v katalogu Unity a zajišťují, že se nikdy nezpřístupní uživatelům.
podrobné řízení přístupu: Katalog Unity umožňuje jemně odstupňovanou kontrolu nad tím, kdo může používat nebo spravovat připojení s oprávněními USE_CONNECTION a MANAGE_CONNECTION.
vynucování tokenu specifického pro hostitele: tokeny jsou omezené na host_name zadané při vytváření připojení, takže je nelze použít s neautorizovanými hostiteli.

Požadovaná oprávnění : správce metastoru nebo uživatel s oprávněním CREATE CONNECTION.

Vytvořte připojení pomocí jedné z následujících metod:

Použijte uživatelské rozhraní Průzkumníka katalogů.
Spusťte příkaz CREATE CONNECTION SQL v poznámkovém bloku Azure Databricks nebo v editoru dotazů SQL Databricks.
K vytvoření připojení použijte rozhraní REST API databricks nebo rozhraní příkazového řádku Databricks. Viz POST /api/2.1/unity-catalog/connections a příkazy Unity Catalog .

Průzkumník katalogu

K vytvoření připojení použijte uživatelské rozhraní Průzkumníka katalogu.

V pracovním prostoru Azure Databricks klikněte na ikonu Katalog .
V horní části podokna katalogu klikněte na ikonu Ikona Přidat a v nabídce vyberte Přidat připojení.

Případně na stránce Rychlý přístup klikněte na tlačítko Externí data >, přejděte na kartu Připojení a klikněte na Vytvořit připojení.
Klikněte na Vytvořit připojení.
Zadejte uživatelsky přívětivý název připojení.
Vyberte typ připojení http.
V následujících možnostech vyberte typ ověřování :
- nosný token
- OAuth stroj ke stroji
- OAuth uživatel k zařízení s sdíleným přístupem
Na stránce Ověřování zadejte následující vlastnosti připojení pro HTTP.

Token nosiče:
- Hostitel: Například https://databricks.com
- Port: Například 443
- nosný token: Například bearer-token
- základní cesta: například /api/
Pro strojový token OAuth pro komunikaci mezi stroji:
- ID klienta: Jedinečný identifikátor aplikace, kterou jste vytvořili.
- tajný klíč klienta: Tajný kód nebo heslo vygenerované pro aplikaci, kterou jste vytvořili.
- rozsah OAuth: Rozsah, který se má udělit během autorizace uživatele. Parametr rozsahu je vyjádřen jako seznam řetězců, které jsou odděleny mezerami a rozlišují malá a velká písmena. Například channels:read channels:history chat:write
- koncový bod tokenu: Klient ho používá k získání přístupového tokenu tím, že předkládá svůj autorizační grant nebo obnovovací token. Obvykle ve formátu https://authorization-server.com/oauth/token
Pro sdílený token mezi uživatelem OAuth a počítačem:
- ID klienta: Jedinečný identifikátor aplikace, kterou jste vytvořili.
- tajný klíč klienta: Tajný kód nebo heslo vygenerované pro aplikaci, kterou jste vytvořili.
- rozsah OAuth: Rozsah, který se má udělit během autorizace uživatele. Parametr rozsahu je vyjádřen jako seznam řetězců, které jsou odděleny mezerami a rozlišují malá a velká písmena. Například channels:read channels:history chat:write
- Koncový bod autorizace: Autentizovat se u vlastníka prostředku pomocí přesměrování uživatelského agenta, obvykle ve specifickém formátu https://authorization-server.com/oauth/authorize
- koncový bod tokenu: Klient ho používá k získání přístupového tokenu tím, že předkládá svůj autorizační grant nebo obnovovací token. Obvykle ve formátu https://authorization-server.com/oauth/token
Poznámka

U uživatele OAuth ke sdílenému počítači se zobrazí výzva k přihlášení pomocí protokolu HTTP pomocí přihlašovacích údajů OAuth.
Klikněte na Vytvořit připojení.

SQL

K vytvoření připojení použijte příkaz CREATE CONNECTION SQL.

Poznámka

Nelze použít příkaz SQL k vytvoření připojení, které používá OAuth stroj ke sdílení s uživatelem . Místo toho se podívejte na pokyny k uživatelskému rozhraní Průzkumníka katalogů.

Pokud chcete vytvořit nové připojení pomocí Bearer tokenu, spusťte následující příkaz v poznámkovém bloku nebo v Databricks SQL editoru dotazů:

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

Databricks doporučuje používat tajných kódů místo řetězců prostého textu pro citlivé hodnoty, jako jsou přihlašovací údaje. Například:

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

Pokud chcete vytvořit nové připojení pomocí OAuth Machine k počítači, spusťte v poznámkovém bloku nebo editoru dotazů SQL Databricks následující příkaz:

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

Odeslání požadavku HTTP do externího systému

Teď, když máte připojení, zjistěte, jak odesílat požadavky HTTP službě pomocí integrované funkce SQL http_request.

Požadovaná oprávnění:USE CONNECTION na objektu připojení.

V poznámkovém bloku nebo editoru SQL Databricks spusťte následující příkaz SQL. Nahraďte zástupné hodnoty:

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: Objekt připojení , který určuje hostitele, port, base_path a přístupové přihlašovací údaje.
http-method: Metoda požadavku HTTP použitá k volání. Příklad: GET, POST, PUT, DELETE
path: Cesta k připojení za base_path k vyvolání prostředku služby.
json: Text JSON, který se má odeslat s požadavkem.
headers: Mapa určující hlavičky požadavku.

Vytvořte nástroj pro funkce Katalogu Unity

Po ověření, že připojení funguje správně, vytvořte funkci Katalogu Unity, která používá připojení. Následující příklad vytvoří nástroj funkce Katalogu Unity, který může agent použít k publikování zprávy do Slacku:

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

Vytvoření nástroje v kódu agenta

Pokud chcete odesílat požadavky HTTP externím službám pomocí Pythonu, použijte funkci http_request z knihovny databricks-sdk. Tato funkce odešle HTTP požadavek externí službě prostřednictvím připojení Unity Catalog pro autentizaci.

Požadovaná oprávnění:USE CONNECTION na objektu připojení.

Následující příklad vytvoří externí požadavek HTTP z kódu 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: Objekt připojení, který určuje hostitele, port, base_path a přihlašovací údaje pro přístup.
method: Metoda požadavku HTTP použitá k volání. Příklad: GET, POST, PUT, DELETE
path: Cesta k připojení za base_path k vyvolání prostředku služby.
json: Text JSON, který se má odeslat s požadavkem.
headers: Mapa určující hlavičky požadavku.

Příklady poznámkových bloků

Následující poznámkové bloky ukazují, jak vytvořit nástroje agenta AI, které se připojují ke službám Slack, OpenAI a vyhledávání Azure AI.

Nástroj agenta zasílání zpráv Slack

Získejte poznámkový blok

Nástroj agenta rozhraní Microsoft Graph API

Získejte poznámkový blok

Nástroj agenta Azure AI Search

Získejte poznámkový blok

Sdílet prostřednictvím

Připojení nástrojů agenta AI k externím službám

Požadavky

Metody ověřování pro externí služby

Vytvoření připojení k externí službě

Průzkumník katalogu

SQL

Odeslání požadavku HTTP do externího systému

Vytvořte nástroj pro funkce Katalogu Unity

Vytvoření nástroje v kódu agenta

Příklady poznámkových bloků

Nástroj agenta zasílání zpráv Slack

Nástroj agenta rozhraní Microsoft Graph API

Nástroj agenta Azure AI Search

Váš názor

Další materiály