Ligue agentes a serviços externos

Ligue os seus agentes de IA a aplicações externas como Slack, Google Calendar ou qualquer serviço com API. O Azure Databricks oferece várias abordagens dependendo se o serviço externo tem um servidor MCP, se precisa de autenticação por utilizador, ou se prefere chamar APIs diretamente a partir do código do agente. Todas as abordagens dependem de uma ligação HTTP do Unity Catalog para gerir as credenciais de forma segura e governar o acesso a serviços externos.

Requirements

• Uma ligação HTTP do Unity Catalog para a sua aplicação externa. As ligações Unity Catalog proporcionam uma gestão segura e governada de credenciais e permitem múltiplos métodos de autenticação, incluindo autenticação OAuth 2.0 utilizador-para-máquina e máquina para máquina.

Servidores MCP externos

Se o serviço externo tiver um servidor MCP disponível, Azure Databricks recomenda ligar através de servidores MCP externos. Os servidores MCP fornecem descoberta automática de ferramentas, integração simplificada e autenticação por utilizador. Consulte Utilizar servidores MCP externos para métodos de instalação, uso programático e detalhes de autenticação.

Adicione um servidor MCP externo ao seu agente

Depois de registar o servidor MCP externo como uma ligação ao Unity Catalog, ligue o seu agente a ele usando a URL MCP gerida: https://<workspace-hostname>/api/2.0/mcp/external/{connection_name}. Substitui <connection-name> pelo nome da tua ligação ao Unity Catalog.

SDK de Agentes OpenAI (Aplicações)

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)

Conceda à aplicação acesso à ligação do Unity Catalog em 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 (Aplicações)

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)

Conceda à aplicação acesso à ligação do Unity Catalog em databricks.yml:

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

Serviço de Modelos

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(),
)

Para implementar o agente, veja Implementar um agente para aplicações de IA generativa (Model Serving). Para detalhes sobre agentes de registo com recursos MCP, veja Utilizar servidores MCP geridos pela Databricks.

OAuth Gerido

O Azure Databricks oferece fluxos OAuth geridos para fornecedores selecionados de ferramentas API. Não precisas de registar a tua própria aplicação OAuth nem de gerir credenciais. O Azure Databricks recomenda o Managed OAuth para desenvolvimento e testes. Se casos de uso em produção exigirem a geração de credenciais OAuth personalizadas, consulte a documentação dos fornecedores para mais informações.

As seguintes integrações utilizam credenciais OAuth geridas pelo Azure Databricks, armazenadas de forma segura no backend.

Para configurar o OAuth gerido, crie uma ligação HTTP com o tipo de autenticação OAuth User to Machine Per User e selecione o seu fornecedor no menu suspenso de OAuth Provider. Para passos detalhados, consulte Instalar um servidor MCP externo.

Cada utilizador é solicitado a autorizar junto do fornecedor na primeira utilização.

Se necessário, permita listar os seguintes URIs de redirecionamento usados pelo OAuth gerido:

Proxy de endpoint para conexões UC

Utilize o endpoint proxy de ligações do Unity Catalog com o SDK de cliente do serviço externo para chamar diretamente as APIs REST a partir do código do agente. Aponte o URL base do SDK para o endpoint do proxy e use o seu token do Azure Databricks como a chave de API. O Azure Databricks autentica o pedido e injeta automaticamente as credenciais do serviço externo a partir da ligação ao Unity Catalog. O teu código nunca lida diretamente com os tokens do serviço externo.

Permissões necessárias:USE CONNECTION no objeto de conexão.

OpenAI

Uso DatabricksOpenAI para encaminhar chamadas para OpenAI externo através do proxy de ligações do Unity Catalog. Primeiro, crie uma ligação HTTP ao Unity Catalog usando a sua chave API OpenAI armazenada como segredo Databricks:

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

Depois instala o pacote databricks-openai e usa a URL do proxy e o cliente de espaço de trabalho no código do seu 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

Configure o Slack SDK para fazer o encaminhamento através do proxy de conexões do Unity Catalog. Crie uma ligação HTTP do Unity Catalog com o anfitrião https://slack.com e o caminho base /api, depois use a URL do proxy como URL base do 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 genérico

Para serviços sem SDK dedicado, use a biblioteca requests com o URL proxy diretamente.

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"},
)

Ferramentas de função UC com ligações HTTP

Pode criar uma função do Unity Catalog que encapsula http_request() para efetuar chamadas a serviços externos. Esta abordagem é útil para definições de ferramentas baseadas em SQL. Consulte Criar ferramentas de agentes de IA usando funções do Unity Catalog para detalhes sobre como criar ferramentas para funções UC.

O exemplo seguinte cria uma ferramenta de função Unity Catalog que publica uma mensagem no 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

Veja CREATE FUNCTION (SQL e Python).

Exemplos de cadernos

Conectar um agente ao Slack

Consulte Conectar um agente de IA ao Slack.

Ligue um agente ao Microsoft Teams

Veja Conecte um agente de IA a Microsoft Teams.

Ferramentas de conexão externa

Os cadernos seguintes demonstram como criar ferramentas de agentes de IA que se ligam ao Slack, OpenAI e Azure AI Search.

Ferramenta de agente de mensagens do Slack

Obter caderno

Ferramenta de Agente para Microsoft Graph API

Obter caderno

Azure ferramenta de agente de pesquisa AI

Obter caderno