Connettere gli agenti a servizi esterni

Connettere gli agenti di intelligenza artificiale 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 per gestire in modo sicuro le credenziali e gestire l'accesso ai servizi esterni.

Requirements

• Connessione HTTP dello Unity Catalog per l'applicazione esterna. Le connessioni del catalogo unity forniscono la gestione sicura e regolamentata delle credenziali e abilitano più metodi di autenticazione, tra cui OAuth 2.0 da utente a computer e autenticazione da computer a computer.

Server MCP esterni

Se il servizio esterno dispone di un server MCP disponibile, Azure Databricks consiglia di connettersi tramite server MCP esterni. I server MCP forniscono l'individuazione automatica degli strumenti, l'integrazione semplificata e l'autenticazione per utente. Vedere Usare server MCP esterni per i metodi di installazione, l'utilizzo a livello di codice e i dettagli di autenticazione.

Aggiungi un server MCP esterno all'agente

Dopo aver registrato il server MCP esterno come connessione al catalogo Unity, connettere l'agente a esso usando l'URL MCP gestito: https://<workspace-hostname>/api/2.0/mcp/external/{connection_name}. Sostituire <connection-name> con il nome della connessione al catalogo Unity.

OpenAI Agents SDK (Apps)

from agents import Agent, Runner
from databricks.sdk import WorkspaceClient
from databricks_openai.agents import McpServer

workspace_client = WorkspaceClient()
host = workspace_client.config.host

async with McpServer(
    url=f"{host}/api/2.0/mcp/external/<connection-name>",
    name="external-service",
    workspace_client=workspace_client,
) as external_server:
    agent = Agent(
        name="Connected agent",
        instructions="You are a helpful assistant with access to external services.",
        model="databricks-claude-sonnet-4-5",
        mcp_servers=[external_server],
    )
    result = await Runner.run(agent, "Send a Slack message to the team about the deployment")
    print(result.final_output)

Concedere all'app l'accesso alla connessione a Unity Catalog in databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_connection'
          uc_securable:
            securable_full_name: '<connection-name>'
            securable_type: 'CONNECTION'
            permission: 'USE_CONNECTION'

LangGraph (App)

from databricks.sdk import WorkspaceClient
from databricks_langchain import ChatDatabricks, DatabricksMCPServer, DatabricksMultiServerMCPClient
from langgraph.prebuilt import create_react_agent

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMultiServerMCPClient([
    DatabricksMCPServer(
        name="external-service",
        url=f"{host}/api/2.0/mcp/external/<connection-name>",
        workspace_client=workspace_client,
    ),
])

async with mcp_client:
    tools = await mcp_client.get_tools()
    agent = create_react_agent(
        ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
        tools=tools,
    )
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "Send a Slack message to the team about the deployment"}]}
    )
    print(result["messages"][-1].content)

Concedere all'app l'accesso alla connessione al catalogo Unity in databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_connection'
          uc_securable:
            securable_full_name: '<connection-name>'
            securable_type: 'CONNECTION'
            permission: 'USE_CONNECTION'

Gestione dei modelli

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient
import mlflow

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/external/<connection-name>",
    workspace_client=workspace_client,
)

tools = mcp_client.list_tools()

mlflow.pyfunc.log_model(
    "agent",
    python_model=my_agent,
    resources=mcp_client.get_databricks_resources(),
)

Per distribuire l'agente, vedere Distribuire un agente per le applicazioni di intelligenza artificiale generative (Model Serving). Per informazioni dettagliate sulla registrazione degli agenti con risorse MCP, vedere Usare server MCP gestiti di 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 gestite Azure Databricks archiviate in modo sicuro nel back-end.

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 Installare un server MCP esterno.

A ogni utente viene richiesto di autorizzare con il provider al primo utilizzo.

Se necessario, includere nella lista di autorizzazione i seguenti URI di reindirizzamento utilizzati da OAuth gestito:

Proxy di connessione UC

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 al catalogo Unity. Il codice non gestisce mai 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"},
)

Strumenti per le funzioni UC con connessioni HTTP

È possibile creare una funzione di Unity Catalog che incapsula http_request() per chiamare servizi esterni. Questo approccio è utile per le definizioni degli strumenti basate su SQL. Per informazioni dettagliate sulla creazione di strumenti per agenti AI usando le funzioni del Unity Catalog, consultare Creare strumenti per agenti AI usando le funzioni del Unity Catalog.

L'esempio seguente crea uno strumento funzione catalogo Unity che invia un messaggio a 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

Vedere CREATE FUNCTION (SQL e Python).

Notebook di esempio

Connettere un agente a Slack

Vedere Connettere un agente di intelligenza artificiale a Slack.

Connettere un agente a Microsoft Teams

Vedere Connettere un agente di intelligenza artificiale a Microsoft Teams.

Strumenti di connessione esterna

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

Strumento agente di messaggistica Slack

Ottieni il notebook

Strumento Microsoft API Graph Agente

Ottieni il notebook

strumento agente Azure AI Search

Ottieni il notebook