Подключение агентов к внешним службам

Подключите ваших агентов ИИ к внешним приложениям, таким как Slack, Google Calendar, или любой службе, имеющей API. Azure Databricks предоставляет несколько подходов в зависимости от того, имеет ли внешняя служба сервер MCP, требуется ли проверка подлинности на пользователя или требуется ли вызывать API непосредственно из кода агента. Все подходы используют HTTP-подключение каталога Unity для безопасного управления учетными данными и управления доступом к внешним службам.

Requirements

• HTTP-подключение каталога Unity для внешнего приложения. Подключения Unity Catalog обеспечивают безопасное, настраиваемое управление учетными данными и поддерживают несколько методов проверки подлинности, включая OAuth 2.0 для аутентификации от пользователя к машине и от машины к машине.

Внешние серверы MCP

Если у внешней службы есть сервер MCP, Azure Databricks рекомендует подключаться через серверы external MCP. Серверы MCP обеспечивают автоматическое обнаружение инструментов, упрощенную интеграцию и проверку подлинности на пользователя. Смотрите Использование внешних серверов MCP для методов установки, программного использования и проверки подлинности.

Добавьте внешний сервер MCP к вашему агенту

После того как вы зарегистрируете внешний сервер MCP как подключение к Unity Catalog, подключите к нему агента, используя управляемый MCP URL: https://<workspace-hostname>/api/2.0/mcp/external/{connection_name}. Замените <connection-name> именем подключения каталога Unity.

Пакет SDK для агентов OpenAI (приложения)

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)

Предоставьте приложению доступ к подключению каталога Unity в 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 (приложения)

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)

Предоставьте приложению доступ к подключению каталога Unity в databricks.yml:

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

Обслуживание моделей

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

Сведения о развертывании агента см. в статье "Развертывание агента для создания приложений ИИ (обслуживание моделей)". Дополнительные сведения об агентах ведения журнала с ресурсами MCP см. в разделе "Использование управляемых серверов MCP Databricks".

Управляемый OAuth

Azure Databricks предлагает управляемые потоки OAuth для выбора поставщиков инструментов API. Вам не нужно регистрировать собственное приложение OAuth или управлять учетными данными. Azure Databricks рекомендует управляемый OAuth для разработки и тестирования. Если в производственных сценариях требуется создание пользовательских учетных данных OAuth, за дополнительной информацией обратитесь к документации со стороны поставщиков.

Следующие интеграции используют учетные данные OAuth, управляемые Azure Databricks, безопасно хранящиеся в серверной части.

Чтобы настроить управляемый OAuth, создайте HTTP-соединение с подключением OAuth User to Machine Per User и выберите вашего поставщика из списка поставщиков OAuth. Подробные инструкции см. в разделе "Установка внешнего сервера MCP".

Каждому пользователю предлагается авторизоваться поставщиком при первом использовании.

При необходимости разрешите следующие URI перенаправления, используемые управляемым OAuth:

Конечная точка прокси-сервера подключений UC

Используйте прокси-сервер конечной точки соединений Unity Catalog вместе с клиентским SDK внешней службы для вызова REST API непосредственно из кода агента. Наведите базовый URL-адрес пакета SDK на конечную точку прокси-сервера и используйте маркер Azure Databricks в качестве ключа API. Azure Databricks выполняет проверку подлинности запроса и автоматически вводит учетные данные внешней службы из подключения каталога Unity. Ваш код никогда не обрабатывает маркеры внешней службы напрямую.

Необходимые разрешения:USE CONNECTION на объект подключения.

OpenAI

Используйте DatabricksOpenAI для маршрутизации вызовов во внешнюю OpenAI через прокси-сервер подключений каталога Unity. Сначала создайте HTTP-соединение для Каталога Unity, используя ключ API OpenAI, хранящийся в качестве секрета в Databricks:

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

Затем установите databricks-openai пакет и используйте URL-адрес прокси-сервера и клиент рабочей области в коде агента:

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

Настройте SDK Slack для маршрутизации через прокси-сервер подключений Unity Catalog. Создайте HTTP-подключение каталога Unity с узлом https://slack.com и базовым путем /api, а затем используйте URL-адрес прокси-сервера в качестве базового URL-адреса пакета 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-запрос

Для служб без выделенного пакета SDK используйте библиотеку requests с URL-адресом прокси-сервера напрямую:

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

Инструменты функций UC с HTTP-подключениями

Вы можете создать функцию Unity Catalog, оборачивающую http_request(), чтобы вызывать внешние службы. Этот подход полезен для определений инструментов на основе SQL. Дополнительные сведения о создании инструментов функции UC см. в статье "Создание средств агента ИИ с помощью функций каталога Unity ".

В следующем примере создается средство функции каталога Unity, которое отправляет сообщение в 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

См. раздел CREATE FUNCTION (SQL и Python).

Примеры записных книжек

Подключение агента к Slack

См. статью "Подключение агента ИИ к Slack".

Подключение агента к Microsoft Teams

См. раздел Connect an AI agent to Microsoft Teams.

Средства внешнего подключения

В следующих ноутбуках продемонстрировано создание инструментов для агента ИИ, которые подключаются к Slack, OpenAI и Azure AI Search.

Средство агента обмена сообщениями Slack

Получите ноутбук

Инструмент агента Microsoft API Graph

Получите ноутбук

средство поиска Azure AI агент

Получите ноутбук