Connettere gli strumenti dell'agente di intelligenza artificiale ai servizi esterni

Articolo
01/31/2025

Importante

Questa funzionalità è in Anteprima Pubblica.

Informazioni su come connettere gli strumenti dell'agente di intelligenza artificiale ad applicazioni esterne come Slack, Google Calendar o qualsiasi servizio con un'API usando le richieste HTTP. Gli agenti possono usare strumenti connessi esternamente per automatizzare le attività, inviare messaggi e recuperare dati da piattaforme di terze parti.

Per altre informazioni sugli strumenti dell'agente, vedere strumenti dell'agente di intelligenza artificiale.

Requisiti

Per connettere gli strumenti agente a servizi esterni, è necessario soddisfare i requisiti seguenti:

Configurare l'autenticazione per il servizio esterno usando uno dei metodi seguenti:
- Token portatore: Ottieni un token portatore per un'autenticazione semplice basata su token.
- OAuth 2.0 Da computer a computer: creare un'app e configurarla per abilitare l'autenticazione da computer a computer.
- OAuth 2.0 Da utente a macchina condivisa: Autenticarsi tramite l'interazione dell'utente per condividere l'accesso tra identità del servizio e macchina.
L'area di lavoro deve essere abilitata per Unity Catalog.
È necessario disporre della connettività di rete da una risorsa di calcolo databricks al servizio esterno. Vedi Raccomandazioni sulla rete per Lakehouse Federation.
È necessario usare un ambiente di calcolo con modalità di accesso utente singolo in Databricks Runtime 15.4 e versioni successive.
È necessario disporre di un sql warehouse pro o serverless. Vedere tipi di magazzino SQL.

Metodi di autenticazione per i servizi esterni

token portatore: un token portatore è un semplice meccanismo di autenticazione basato su token in cui un token viene rilasciato a un client e usato per accedere alle risorse senza richiedere credenziali aggiuntive. Il token è incluso nell'intestazione della richiesta e concede l'accesso purché sia valido.

OAuth macchina a macchina: l'autenticazione macchina a macchina (M2M) OAuth viene usata quando due sistemi o applicazioni devono comunicare senza coinvolgimento diretto dell'utente. I token vengono rilasciati a un client di computer registrato, che usa le proprie credenziali per l'autenticazione. Questa opzione è ideale per le attività di comunicazione da server a server, microservizi e automazione in cui non è necessario alcun contesto utente.

OAuth Utente a Macchina Condiviso: L'autenticazione OAuth Utente-a-Macchina Condiviso consente a un'unica identità utente di autenticarsi e condividere lo stesso set di credenziali tra più client o utenti. Tutti gli utenti condividono lo stesso token di accesso. Questo approccio è adatto per dispositivi o ambienti condivisi in cui un'identità utente coerente è sufficiente, ma riduce la responsabilità e il rilevamento dei singoli utenti.

Creare una connessione al servizio esterno

Creare prima di tutto una connessione del catalogo Unity al servizio esterno che specifica un percorso e le credenziali per accedere al servizio.

I vantaggi dell'uso di una connessione al catalogo Unity includono quanto segue:

la gestione sicura delle credenziali: segreti e token vengono archiviati e gestiti in modo sicuro all'interno del catalogo unity, assicurandosi che non siano mai esposti agli utenti.
controllo di accesso granulare: Catalogo unity consente un controllo granulare su chi può usare o gestire le connessioni con i privilegi di USE_CONNECTION e MANAGE_CONNECTION.
applicazione di token specifici per host: i token sono limitati agli host_name specificati durante la creazione della connessione, assicurandosi che non possano essere usati con host non autorizzati.

Autorizzazioni necessarie: amministratore Metastore o utente con il privilegio di CREATE CONNECTION.

Creare una connessione usando uno dei metodi seguenti:

Usare l'interfaccia utente dell'Esplora Catalogo.
Eseguire il comando SQL CREATE CONNECTION in un notebook di Azure Databricks o nell'editor di query SQL di Databricks.
Usare l'API REST di Databricks o l'interfaccia della riga di comando di Databricks per creare una connessione. Consultare POST /api/2.1/unity-catalog/connections e comandi di Unity Catalog.

Esploratore di Cataloghi

Usare l'interfaccia utente di Esplora cataloghi per creare una connessione.

Nell'area di lavoro di Azure Databricks fare clic sull'icona Catalogo.
Nella parte superiore del riquadro Catalogo , fare clic sull'icona Aggiungi o "+" icona Aggiungi e selezionare Aggiungi una connessione dal menu.

In alternativa, nella pagina Accesso rapido fare clic sul pulsante Dati esterni >, passare alla scheda Connessioni e fare clic su Crea connessione.
Fare clic su Crea connessione.
Immettere un nome di connessione descrittivo.
Selezionare un Tipo di connessione di HTTP.
Selezionare un tipo di autenticazione tra le opzioni seguenti:
- token di autorizzazione
- OAuth da macchina a macchina
- Utente OAuth per Macchina Condivisa
Nella pagina Autenticazione immettere le proprietà di connessione seguenti per la connessione HTTP.

Per un token portatore:
- host: ad esempio, https://databricks.com
- porta: ad esempio, 443
- Bearer Token: ad esempio, bearer-token
- percorso di base: ad esempio, /api/
Per il token OAuth da Macchina a Macchina:
- ID client: identificatore univoco per l'applicazione creata.
- Segreto Client: segreto o password generato per l'applicazione che hai creato.
- ambito OAuth: ambito da concedere durante l'autorizzazione dell'utente. Il parametro scope è espresso come un elenco di stringhe sensibili al maiuscolo/minuscolo delimitate da spazi. Ad esempio, channels:read channels:history chat:write
- Endpoint token: utilizzato dal client per ottenere un token di accesso presentando il grant di autorizzazione o il token di aggiornamento. In genere nel formato https://authorization-server.com/oauth/token
Per il token condiviso da parte dell'utente a macchina OAuth:
- ID client: identificatore univoco per l'applicazione creata.
- Segreto Client: segreto o password generato per l'applicazione che hai creato.
- ambito OAuth: ambito da concedere durante l'autorizzazione dell'utente. Il parametro scope è espresso come un elenco di stringhe sensibili al maiuscolo/minuscolo delimitate da spazi. Ad esempio, channels:read channels:history chat:write
- endpoint di autorizzazione: per effettuare l'autenticazione con il proprietario della risorsa tramite reindirizzamento del user-agent, in genere nel formato https://authorization-server.com/oauth/authorize
- Endpoint token: utilizzato dal client per ottenere un token di accesso presentando il grant di autorizzazione o il token di aggiornamento. In genere nel formato https://authorization-server.com/oauth/token
Nota

Per OAuth User to Machine Shared, ti viene richiesto di accedere con HTTP utilizzando le tue credenziali OAuth.
Fare clic su Crea connessione.

SQL

Usare il comando SQL CREATE CONNECTION per creare una connessione.

Nota

Non è possibile usare il comando SQL per creare una connessione che utilizza OAuth da macchina a utente condiviso. Vedere invece le istruzioni dell'interfaccia utente di Esplora cataloghi.

Per creare una nuova connessione usando un token Bearer , eseguire il comando seguente in un notebook o nell'editor di query SQL di Databricks.

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

Databricks consiglia di usare segreti anziché stringhe di testo non crittografato per valori sensibili come le credenziali. Per esempio:

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

Per creare una nuova connessione utilizzando OAuth Machine to Machine, eseguire il comando seguente in un notebook o nell'editor di query SQL di 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>'
)

Inviare una richiesta HTTP al sistema esterno

Ora che si dispone di una connessione, scopri come inviare richieste HTTP al servizio con la funzione SQL predefinita http_request.

Autorizzazioni necessarie:USE CONNECTION sull'oggetto connessione.

Eseguire il comando SQL seguente in un notebook o nell'editor SQL di Databricks. Sostituisci i valori segnaposto:

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: l'oggetto di connessione che specifica l'host, la porta, base_path e le credenziali di accesso.
http-method: metodo di richiesta HTTP usato per effettuare la chiamata. Ad esempio: GET, POST, PUT, DELETE
path: percorso da concatenare dopo il base_path per richiamare la risorsa del servizio.
json: corpo JSON da inviare con la richiesta.
headers: Una mappa per specificare le intestazioni della richiesta.

Creare uno strumento per le funzioni del catalogo Unity

Dopo aver verificato il corretto funzionamento della connessione, creare una funzione di Catalogo Unity che usa la connessione. L'esempio seguente crea uno strumento funzione catalogo Unity che un agente può usare per pubblicare un messaggio in 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

Creare uno strumento nel codice dell'agente

Per inviare richieste HTTP a servizi esterni con Python, usare la funzione http_request dalla libreria di databricks-sdk. Questa funzione invia una richiesta HTTP a un servizio esterno usando una connessione del catalogo Unity per l'autenticazione.

Autorizzazioni necessarie:USE CONNECTION sull'oggetto connessione.

Nell'esempio seguente viene eseguita una richiesta HTTP esterna dall'interno del codice dell'agente.

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: oggetto connessione che specifica l'host, la porta, base_path e le credenziali di accesso.
method: metodo di richiesta HTTP usato per effettuare la chiamata. Ad esempio: GET, POST, PUT, DELETE
path: percorso da concatenare dopo il base_path per richiamare la risorsa del servizio.
json: corpo JSON da inviare con la richiesta.
headers: mappa per specificare le intestazioni della richiesta.

Notebook di esempio

I seguenti notebook illustrano come creare strumenti per agenti di intelligenza artificiale che si connettono a Slack, OpenAI e Azure AI Search.

Strumento agente di messaggistica Slack

Ottieni notebook

Strumento openAI per l'agente di intelligenza artificiale

Ottieni notebook

Agente di ricerca AI di Azure

Ottieni notebook

Condividi tramite

Connettere gli strumenti dell'agente di intelligenza artificiale ai servizi esterni

Requisiti

Metodi di autenticazione per i servizi esterni

Creare una connessione al servizio esterno

Esploratore di Cataloghi

SQL

Inviare una richiesta HTTP al sistema esterno

Creare uno strumento per le funzioni del catalogo Unity

Creare uno strumento nel codice dell'agente

Notebook di esempio

Strumento agente di messaggistica Slack

Strumento openAI per l'agente di intelligenza artificiale

Agente di ricerca AI di Azure

Commenti e suggerimenti

Risorse aggiuntive