Connettere gli agenti agli strumenti

La connessione degli agenti agli strumenti offre funzionalità pratiche oltre la generazione di testo, ad esempio la ricerca di documenti, l'esecuzione di query su tabelle, la chiamata di API esterne o l'esecuzione di codice personalizzato.

Il codice dell'agente, creato con framework come LangGraph o l'SDK di OpenAI, e gli assistenti alla programmazione come Claude Code e Cursor richiamano strumenti tramite MCP attraverso tre percorsi governati in Databricks: MCP Services per strumenti di terze parti come GitHub e Slack, il proprio server MCP ospitato in Databricks Apps per strumenti personalizzati e server MCP gestiti per i dati e il codice di Databricks, tutti governati in Unity Catalog con autorizzazioni, criteri e audit.

Il diagramma mostra la route MCP, che Azure Databricks consiglia per la maggior parte delle integrazioni. MCP è uno dei diversi modi per connettere gli agenti a servizi esterni. Insieme ai servizi MCP, è possibile chiamare le API REST direttamente tramite una connessione HTTP del catalogo Unity. Selezionare Managed OAuth per l'autenticazione per utente, il proxy delle connessioni di Unity Catalog per chiamare le API dal codice dell'agente, oppure gli strumenti funzione di Unity Catalog che eseguono il wrapping di http_request(). La tabella seguente riepiloga ogni modo per connettersi, dai dati Azure Databricks ai servizi esterni:

Avvicinarsi Caso d'uso consigliato
Server MCP gestiti per i dati di Azure Databricks Utilizza questo approccio per interrogare i dati di Azure Databricks ed eseguire funzioni governate con i server MCP Genie pronto all'uso, Databricks AI Search, Databricks SQL e Unity Catalog Function.
Server MCP esterni Usare questo approccio per i servizi che pubblicano un server MCP. Offre l'individuazione automatica degli strumenti e l'accesso regolamentato tramite Unity AI Gateway.
OAuth gestito Usa questo approccio per le integrazioni di Google Drive o SharePoint. Azure Databricks gestisce le credenziali OAuth, quindi non è necessaria alcuna registrazione dell'app.
Proxy delle connessioni di Unity Catalog Usare questo approccio per effettuare chiamate dirette all'API REST dal codice dell'agente usando l'SDK client del servizio esterno.
Strumenti per le funzioni del catalogo Unity Usare questo approccio per le definizioni di strumenti basate su SQL che avvolgono la funzione http_request().

Server MCP gestiti per i dati di Azure Databricks

Azure Databricks offre server MCP gestiti pronti all'uso che forniscono agli agenti l'accesso ai dati e alle funzioni nell'area di lavoro, senza server da compilare o ospitare. Ogni server ha un URL dedicato e un ambito OAuth e il catalogo Unity regola l'accesso:

  • Genie: eseguire query sui dati strutturati nelle tabelle Genie Agents e Unity Catalog con il linguaggio naturale.
  • Ricerca di intelligenza artificiale di Databricks (ricerca vettoriale): eseguire ricerche nei documenti negli indici di ricerca vettoriali.
  • Databricks SQL: eseguire query SQL sulle tabelle del catalogo Unity.
  • Funzioni del catalogo Unity: chiamare funzioni sql e Python personalizzate registrate nel catalogo unity.

Per gli URL dei server, gli ambiti di OAuth e il catalogo completo, consulta server MCP gestiti di Azure Databricks. Per chiamare questi server dal codice dell'agente, vedere Usare i server MCP negli agenti.

Server MCP esterni

Connettere gli agenti ad applicazioni esterne come Slack, Google Calendar o qualsiasi servizio con un'API. Azure Databricks offre diversi approcci a seconda che il servizio esterno disponga di un server MCP, sia che sia necessaria l'autenticazione per utente o se si preferisce chiamare le API direttamente dal codice dell'agente. Tutti gli approcci si basano su una connessione HTTP del catalogo Unity, che fornisce la gestione sicura e regolamentata delle credenziali e supporta più metodi di autenticazione, tra cui l'autenticazione da utente a computer (U2M) OAuth 2.0 e l'autenticazione da computer a computer (M2M).

Se il servizio esterno dispone di un server MCP disponibile, Azure Databricks consiglia di registrarlo come servizio MCP nel catalogo unity. I servizi MCP offrono l'individuazione automatica degli strumenti, l'autenticazione per utente e la governance tramite Unity AI Gateway con concessioni, selezione degli strumenti e criteri di servizio.

Per strumenti SaaS (Software-as-a-Service) comuni, ad esempio Slack, GitHub e Google Drive, Azure Databricks fornisce servizi MCP pronti all'uso senza configurazione. Vedere Servizi MCP forniti da Databricks.

OAuth gestito

Azure Databricks offre flussi OAuth gestiti per i provider di strumenti API selezionati. Non è necessario registrare l'app OAuth o gestire le credenziali. Azure Databricks consiglia OAuth gestito per lo sviluppo e il test. Se i casi d'uso di produzione richiedono la generazione di credenziali OAuth personalizzate, vedere la documentazione dei provider per altre informazioni.

Le integrazioni seguenti usano le credenziali OAuth che Azure Databricks gestisce e archivia in modo sicuro nel back-end.

Provider Note di configurazione Ambiti supportati Description
Google Drive API Nessuno https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/documents.readonly https://www.googleapis.com/auth/spreadsheets.readonly offline_access Accesso in sola lettura ai file di Google Drive, inclusi Google Docs e Google Sheets.
Gmail API Nessuno https://www.googleapis.com/auth/gmail.readonly offline_access Accesso in sola lettura a messaggi, thread, bozze ed etichette gmail.
Google Calendar API Nessuno https://www.googleapis.com/auth/calendar.readonly offline_access Accesso in sola lettura agli eventi di Google Calendar, ai calendari e alle informazioni sulla disponibilità.
API SharePoint Nessuno https://graph.microsoft.com/User.Read https://graph.microsoft.com/User.ReadBasic.All https://graph.microsoft.com/Sites.Read.All https://graph.microsoft.com/Files.Read https://graph.microsoft.com/Files.Read.All https://graph.microsoft.com/Mail.Read https://graph.microsoft.com/Mail.ReadBasic https://graph.microsoft.com/Mail.Read.Shared https://graph.microsoft.com/MailboxFolder.Read https://graph.microsoft.com/MailboxItem.Read https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Calendars.Read.Shared https://graph.microsoft.com/Chat.Read https://graph.microsoft.com/Chat.ReadBasic https://graph.microsoft.com/ChatMember.Read https://graph.microsoft.com/ChatMessage.Read https://graph.microsoft.com/Channel.ReadBasic.All https://graph.microsoft.com/ChannelMessage.Read.All https://graph.microsoft.com/OnlineMeetings.Read https://graph.microsoft.com/OnlineMeetingTranscript.Read.All https://graph.microsoft.com/OnlineMeetingAiInsight.Read https://graph.microsoft.com/OnlineMeetingArtifact.Read.All https://graph.microsoft.com/OnlineMeetingRecording.Read.All offline_access openid profile email Accesso di sola lettura tramite Microsoft Graph a file di SharePoint e OneDrive, Outlook posta e calendario e Microsoft Teams chat, canali e riunioni.

Per configurare OAuth gestito, creare una connessione HTTP con il tipo di autenticazione OAuth Utente a Macchina per Utente e selezionare il provider dal menu a discesa OAuth Provider. Per i passaggi dettagliati, vedere Creare una connessione al servizio esterno.

Il provider richiede a ogni utente di autorizzare il primo utilizzo.

Se necessario, aggiungere all’elenco degli elementi consentiti i seguenti URI di reindirizzamento utilizzati da OAuth gestito:

Cloud URI di reindirizzamento
AWS https://oregon.cloud.databricks.com/api/2.0/http/oauth/redirect
Azure https://westus.azuredatabricks.net/api/2.0/http/oauth/redirect
GCP https://us-central1.gcp.databricks.com/api/2.0/http/oauth/redirect

Per i provider OAuth gestiti con un server MCP pubblicato, ad esempio Glean, GitHub, Atlassian e Slack, Azure Databricks possono gestire le credenziali OAuth quando si registra il server come servizio MCP. Vedere Provider OAuth gestiti.

Endpoint proxy per le connessioni di Unity Catalog

Utilizzare l'endpoint proxy delle connessioni del catalogo Unity con l'SDK client del servizio esterno per invocare direttamente le API REST dal codice dell'agente. Puntare l'URL di base dell'SDK all'endpoint proxy e usare il token Azure Databricks come chiave API. Azure Databricks autentica la richiesta e inserisce automaticamente le credenziali del servizio esterno dalla connessione di Unity Catalog. Il codice non gestisce direttamente i token del servizio esterno.

Autorizzazioni necessarie:USE CONNECTION sull'oggetto connessione.

OpenAI

Usare DatabricksOpenAI per instradare le chiamate esterne a OpenAI tramite il proxy di connessioni di Unity Catalog. Creare prima di tutto una connessione HTTP di Unity Catalog usando la chiave API OpenAI archiviata come segreto databricks:

CREATE CONNECTION openai_connection TYPE HTTP
OPTIONS (
  host 'https://api.openai.com',
  base_path '/v1',
  bearer_token secret ('<secret-scope>', '<secret-key>')
);

Installare quindi il databricks-openai pacchetto e usare l'URL proxy e il client dell'area di lavoro nel codice dell'agente:

pip install databricks-openai

from databricks_openai import DatabricksOpenAI
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

client = DatabricksOpenAI(
    workspace_client=w,
    base_url=f"{w.config.host}/api/2.0/unity-catalog/connections/openai_connection/proxy/",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

Slack

Configurare lo Slack SDK per instradare tramite il proxy delle connessioni di Unity Catalog. Creare una connessione HTTP del catalogo Unity con host https://slack.com e percorso /apidi base, quindi usare l'URL proxy come URL di base dell'SDK:

from slack_sdk import WebClient
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

client = WebClient(
    token=w.config.authenticate()["Authorization"].split(" ")[1],
    base_url=f"{w.config.host}/api/2.0/unity-catalog/connections/slack_connection/proxy/",
)

result = client.chat_postMessage(channel="C123456", text="Hello from Databricks!")
print(result["message"]["text"])

HTTP generico

Per i servizi senza un SDK dedicato, usare direttamente la requests libreria con l'URL del proxy:

import requests
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

response = requests.post(
    f"{w.config.host}/api/2.0/unity-catalog/connections/my_connection/proxy/api/v1/resource",
    headers={
        **w.config.authenticate(),
        "Content-Type": "application/json",
    },
    json={"key": "value"},
)

Per informazioni dettagliate sull'endpoint proxy, sui metodi di autenticazione supportati e sulla configurazione della connessione, vedere Inoltrare le richieste tramite il proxy di connessione HTTP.

Strumenti per le funzioni del catalogo Unity

Note

Azure Databricks consiglia di usare i servizi MCP o il proxy di connessioni del catalogo Unity per le nuove integrazioni. Gli strumenti per le funzioni del catalogo Unity con http_request rimangono supportati, ma non sono più l'approccio consigliato.

È possibile creare una funzione di Unity Catalog che incapsula http_request() per chiamare servizi esterni. Questo approccio è utile per le definizioni di strumenti basate su SQL, ad esempio una funzione che invia un messaggio a Slack. Per la procedura dettagliata completa, inclusi l'esempio SQL e le limitazioni del tipo di connessione, vedere Chiamare API esterne con http_request (legacy).

Notebook di esempio

I seguenti notebook mostrano come creare strumenti per agenti di IA che si collegano a Slack, OpenAI e Azure AI Search.

Strumento agente di messaggistica Slack

Ottieni il notebook

Strumento di gestione dell'API Microsoft Graph

Ottieni il notebook

Agente di ricerca AI di Azure

Ottieni il notebook

Per una procedura dettagliata sulla connessione di un agente a Microsoft Teams, vedere Connettere un agente di intelligenza artificiale a Microsoft Teams.

Risorse aggiuntive

  • Last updated on