Ansluta AI-agentverktyg till externa tjänster

Artikel
02/14/2025

Viktig

Den här funktionen finns i offentlig förhandsversion.

Lär dig hur du ansluter AI-agentverktyg till externa program som Slack, Google Calendar eller någon tjänst med ett API med HJÄLP av HTTP-begäranden. Agenter kan använda externt anslutna verktyg för att automatisera uppgifter, skicka meddelanden och hämta data från plattformar från tredje part.

Mer information om agentverktyg finns i AI-agentverktyg.

Krav

Om du vill ansluta agentverktyg till externa tjänster måste du uppfylla följande krav:

Konfigurera autentisering till den externa tjänsten med någon av följande metoder:
- Ägartoken: Hämta en ägartoken för enkel tokenbaserad autentisering.
- OAuth 2.0 Machine-to-Machine: Skapa och konfigurera en app för att aktivera maskin-till-dator-autentisering.
- OAuth 2.0 Användare-till-dator delad: Autentisera med användarinteraktion för att dela åtkomst mellan tjänstidentitet och dator.
Din arbetsyta måste vara aktiverad för Unity Catalog.
Du måste ha nätverksanslutning från en Databricks-beräkningsresurs till den externa tjänsten. Se Nätverksrekommendationer för Lakehouse Federation.
Du måste använda en beräkning med dedikerat åtkomstläge (tidigare åtkomstläge för en enskild användare) på Databricks Runtime 15.4 och senare.
Du måste ha ett proffs- eller serverlöst SQL-lager. Se SQL-lagertyper.

Autentiseringsmetoder för externa tjänster

Bearer-token: En ägartoken är en enkel tokenbaserad autentiseringsmekanism där en token utfärdas till en klient och används för att komma åt resurser utan ytterligare autentiseringsuppgifter. Token ingår i begärandehuvudet och ger åtkomst så länge den är giltig.

OAuth Machine to Machine (rekommenderas): M2M-autentisering (OAuth Machine-to-Machine) används när två system eller program kommunicerar utan direkt användarengagemang. Token utfärdas till en registrerad datorklient som använder sina egna autentiseringsuppgifter för att autentisera. Detta är idealiskt för kommunikation mellan servrar, mikrotjänster och automatiseringsuppgifter där ingen användarkontext behövs. Databricks rekommenderar att du använder OAuth Machine-to-Machine när det är tillgängligt.

OAuth User to Machine Shared: OAuth Användar-till-dator delad autentisering tillåter en enskild användaridentitet att autentisera och dela samma uppsättning autentiseringsuppgifter mellan flera klienter eller användare. Alla användare delar samma åtkomsttoken. Den här metoden är lämplig för delade enheter eller miljöer där en konsekvent användaridentitet räcker, men den minskar individuell ansvarsskyldighet och spårning. När identitetsinloggning krävs, väljer du Användare till dator delad.

Skapa en anslutning till den externa tjänsten

Skapa först en Unity-kataloganslutning till den externa tjänsten som anger en sökväg och autentiseringsuppgifter för att få åtkomst till tjänsten.

Fördelarna med att använda en Anslutning till Unity-katalogen är följande:

Säker hantering av autentiseringsuppgifter: Hemligheter och token lagras och hanteras på ett säkert sätt i Unity Catalog, vilket säkerställer att de aldrig exponeras för användare.
detaljerad åtkomstkontroll: Unity Catalog ger detaljerad kontroll över vem som kan använda eller hantera anslutningar med USE_CONNECTION och MANAGE_CONNECTION privilegier.
Värdspecifik tokenhantering: Tokens är begränsade till de host_name som angavs när anslutningen skapades, vilket säkerställer att de inte kan användas med obehöriga värdar.

Behörigheter som krävs: metaarkivadministratör eller användare med CREATE CONNECTION behörighet.

Skapa en anslutning med någon av följande metoder:

Använd katalogutforskarens användargränssnitt.
Kör CREATE CONNECTION SQL-kommandot i en Azure Databricks-notebook-fil eller Databricks SQL-frågeredigeraren.
Använd Databricks REST API eller Databricks CLI för att skapa en anslutning. Se kommandona POST /api/2.1/unity-catalog/connections och Unity Catalog.

Katalogutforskaren

Använd katalogutforskarens användargränssnitt för att skapa en anslutning.

På din Azure Databricks-arbetsyta klickar du på ikonen Catalog.
Längst upp i fönstret Catalog klickar du på ikonen Ikonen Lägg till och väljer Lägg till en anslutning på menyn.

Från sidan Snabbåtkomst klickar du på knappen Externa data >, går till fliken Anslutningar och klickar på Skapa anslutning.
Klicka på Skapa anslutning.
Ange ett användarvänligt Anslutningsnamn.
Välj en anslutningstyp för HTTP.
Välj en autentiseringstyp från följande alternativ:
- Bearer-token
- OAuth Machine to Machine
- OAuth-användare till datordelade
På sidan Authentication anger du följande anslutningsegenskaper för HTTP-anslutningen.

För en bärare-token:
- Host: Till exempel https://databricks.com
- Port: Till exempel 443
- Bearer Token: Till exempel bearer-token
- Grundväg: Till exempel /api/
För OAuth-maskin-till-maskin-token:
- Klient-ID: Unik identifierare för programmet du skapade.
- Klienthemlighet: Hemlighet eller lösenord som genererats för programmet som du skapade.
- OAuth-omfång: Omfång att bevilja under användarauktorisering. Omfångsparametern uttrycks som en lista av mellanslagsavgränsade, skiftlägeskänsliga strängar. Till exempel channels:read channels:history chat:write
- Token-slutpunkt: Används av klienten för att hämta en åtkomsttoken genom att presentera sitt auktoriseringsbevis eller uppdateringstoken. Vanligtvis i formatet https://authorization-server.com/oauth/token
För OAuth-användare till maskindelad token:
- Klient-ID: Unik identifierare för programmet du skapade.
- Klienthemlighet: Hemlighet eller lösenord som genererats för programmet som du skapade.
- OAuth-omfång: Omfång att bevilja under användarauktorisering. Räckviddsparametern uttrycks som en lista med mellanslagsavgränsade, skiftlägeskänsliga strängar. Till exempel channels:read channels:history chat:write
- auktoriseringsslutpunkt: Autentisera med resursägaren via omdirigering av användaragenten, vanligtvis i formatet https://authorization-server.com/oauth/authorize
- Token-slutpunkt: Används av klienten för att hämta en åtkomsttoken genom att presentera sitt auktoriseringsbevis eller uppdateringstoken. Vanligtvis i formatet https://authorization-server.com/oauth/token
Not

För OAuth-användare till delad dator uppmanas du att logga in med HTTP med dina OAuth-autentiseringsuppgifter.
Klicka på Skapa anslutning.

SQL

Använd kommandot CREATE CONNECTION SQL för att skapa en anslutning.

Notera

Du kan inte använda SQL-kommandot för att skapa en anslutning som använder OAuth-dator till användardelade. Se i stället användargränssnittsinstruktionerna för Katalogutforskaren.

Om du vill skapa en ny anslutning med en Bearer-tokenkör du följande kommando i en notebook-fil eller Databricks SQL-frågeredigeraren:

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

Databricks rekommenderar att du använder säkerhetsuppgifter i stället för klartextsträngar för känsliga värden som autentiseringsuppgifter. Till exempel:

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

Om du vill skapa en ny anslutning med hjälp av OAuth Machine to Machinekör du följande kommando i en notebook-fil eller Databricks SQL-frågeredigeraren:

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

Skicka en HTTP-begäran till det externa systemet

Nu när du har en anslutning får du lära dig hur du skickar HTTP-begäranden till tjänsten med hjälp av den http_request inbyggda SQL-funktionen.

Behörigheter som krävs:USE CONNECTION på anslutningsobjektet.

Kör följande SQL-kommando i en notebook-fil eller Databricks SQL-redigeraren. Ersätt platshållarvärdena:

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: Det anslutningsobjektet som anger värd, port, base_path och åtkomstuppgifter.
http-method: Den HTTP-begärandemetod som används för att göra anropet. Till exempel: GET, POST, PUT, DELETE
path: Sökvägen som ska sammanfogas efter base_path för att anropa resursen för tjänsten.
json: JSON-texten som ska skickas med förfrågan.
headers: En karta för att ange begärandehuvuden.

Skapa ett funktionsverktyg för Unity Catalog

När du har verifierat att anslutningen fungerar korrekt skapar du en Unity Catalog-funktion som använder anslutningen. I följande exempel skapas ett funktionsverktyg för Unity Catalog som en agent kan använda för att skicka ett meddelande till 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

Skapa ett verktyg i agentkoden

Om du vill skicka HTTP-begäranden till externa tjänster med Python använder du funktionen http_request från databricks-sdk-biblioteket. Den här funktionen skickar en HTTP-begäran till en extern tjänst med en Unity Catalog-anslutning för att autentisera.

Behörigheter som krävs:USE CONNECTION på anslutningsobjektet.

I följande exempel görs en extern HTTP-begäran inifrån agentkoden.

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: Anslutningsobjektet som specificerar värd, port, base_path och åtkomstuppgifter.
method: Den HTTP-begärandemetod som används för att göra anropet. Till exempel: GET, POST, PUT, DELETE
path: Sökvägen som ska sammanfogas efter base_path för att anropa tjänstresursen.
json: JSON-texten som ska skickas med förfrågan.
headers: En karta för att ange begäranderubrikerna.

Exempelnotebooks

Följande notebook-filer visar hur du skapar AI-agentverktyg som ansluter till Slack, OpenAI och Azure AI-sökning.

Dela via

Ansluta AI-agentverktyg till externa tjänster

Krav

Autentiseringsmetoder för externa tjänster

Skapa en anslutning till den externa tjänsten

Katalogutforskaren

SQL

Skicka en HTTP-begäran till det externa systemet

Skapa ett funktionsverktyg för Unity Catalog

Skapa ett verktyg i agentkoden

Exempelnotebooks

Verktyg för Slack-meddelandeagent

Microsoft Graph API-agentverktyg

Azure AI Search-agentverktyg

Feedback

Ytterligare resurser