将 AI 代理工具连接到外部服务

项目
02/18/2025

重要说明

此功能目前以公共预览版提供。

了解如何使用 HTTP 请求将 AI 代理工具连接到诸如 Slack、Google Calendar 或任何具有 API 的服务等外部应用程序。代理可以使用外部连接的工具自动执行任务、发送消息以及从第三方平台检索数据。

若要详细了解代理工具，请参阅 AI 代理工具。

要求

若要将代理工具连接到外部服务，必须满足以下要求：

使用以下方法之一设置外部服务的身份验证：
- 持有者令牌：获取持有者令牌以进行基于令牌的简单身份验证。
- OAuth 2.0 计算机到计算机：创建和配置应用以启用计算机到计算机身份验证。
- OAuth 2.0 用户到计算机共享：通过用户交互进行身份验证，以便在服务标识和计算机之间共享访问权限。
工作区必须已启用 Unity 目录。
必须有从 Databricks 计算资源到外部服务的网络连接。请参阅 Lakehouse Federation 的网络建议。
必须在 Databricks Runtime 15.4 及更高版本上使用具有单用户访问模式的计算。
必须有专业版或无服务器 SQL 仓库。请参阅 SQL 仓库类型。

外部服务的身份验证方法

持有者令牌：持有者令牌是一种简单的基于令牌的身份验证机制：令牌颁发给客户端，用于访问资源，无需其他凭据。令牌包含在请求头中，只要令牌有效，就授予访问权限。

OAuth 计算机到计算机（建议）：当两个系统或应用程序在没有直接用户参与的情况下通信时，将使用 OAuth 计算机到计算机（M2M）身份验证。令牌颁发给已注册的计算机客户端，该客户端使用自己的凭据进行身份验证。这非常适合不需要用户上下文的服务器到服务器通信、微服务和自动化任务。 Databricks 建议在可用时使用 OAuth 机器对机器。

OAuth 用户到计算机共享：OAuth 用户到计算机共享身份验证允许单个用户标识在多个客户端或用户之间进行身份验证和共享同一组凭据。所有用户共享相同的访问令牌。此方法适用于只需使用一致用户标识的共享设备或环境，但会降低个人责任和减少跟踪。如果需要身份登录，请选择“用户与机器共享”。

创建与外部服务的连接

首先，创建与外部服务的 Unity Catalog 连接，该连接指定用于访问服务的路径和凭据。

使用 Unity Catalog 连接的好处包括：

安全凭据管理： 机密和令牌安全地存储在 Unity 目录中和管理，确保它们永远不会向用户公开。
精细访问控制：Unity Catalog 允许精细控制谁可以使用或管理与和 USE_CONNECTION 特权的连接。MANAGE_CONNECTION
特定于主机的令牌强制实施：令牌仅限于在创建连接期间指定的 host_name，确保这些令牌不能用于未经授权的主机。

所需的权限：元存储管理员或者拥有 CREATE CONNECTION 权限的用户。

使用以下方法之一创建连接：

使用目录资源管理器用户界面。
在 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中执行 CREATE CONNECTION SQL 命令。
使用 Databricks REST API 或 Databricks CLI 来创建连接。请参阅 POST /api/2.1/unity-catalog/connections 和 Unity Catalog 命令。

目录资源管理器

使用 Catalog Explorer UI 创建连接。

在 Azure Databricks 工作区中，单击 “目录”。
在“目录”窗格顶部，单击“添加”图标，然后从菜单中选择“添加连接”。

也可以在“快速访问”页中单击“外部数据”>按钮，转到“连接”选项卡，然后单击“创建连接”。
单击“创建连接”。
输入用户友好的连接名称。
选择“HTTP”作为“连接类型”。
从以下选项中选择一种“身份验证类型”：
- 持有者令牌
- OAuth 计算机到计算机
- OAuth 用户到计算机共享
在“身份验证”页上，输入 HTTP 连接的以下连接属性。

适用于持有者令牌：
- 主机：例如 https://databricks.com
- 端口：例如 443
- 持有者令牌：例如 bearer-token
- 基路径：例如 /api/
对于 OAuth 计算机到计算机令牌：
- 客户端 ID：所创建应用程序的唯一标识符。
- 客户端密码：为创建的应用程序生成的机密或密码。
- OAuth 范围：要在用户授权期间授予的范围。范围参数表示为以空格分隔的、区分大小写的字符串的列表。例如 channels:read channels:history chat:write
- 令牌终结点：客户端可以通过提供其授权或刷新令牌，使用该终结点来获取访问令牌。通常采用 https://authorization-server.com/oauth/token 格式
对于 OAuth 用户到计算机共享令牌：
- 客户端 ID：所创建应用程序的唯一标识符。
- 客户端密码：为创建的应用程序生成的机密或密码。
- OAuth 范围：要在用户授权期间授予的范围。范围参数表示为以空格分隔的、区分大小写的字符串的列表。例如 channels:read channels:history chat:write
- 授权终结点：若要通过用户代理重定向的方式向资源所有者验证身份，通常采用 https://authorization-server.com/oauth/authorize 格式
- 令牌终结点：客户端可以通过提供其授权或刷新令牌，使用该终结点来获取访问令牌。通常采用格式 https://authorization-server.com/oauth/token
注释

对于 OAuth 用户与机器共享，系统会提示您使用 OAuth 凭据通过 HTTP 登录。
单击“创建连接”。

SQL

使用 CREATE CONNECTION SQL 命令创建连接。

注释

不能使用 SQL 命令创建使用“OAuth 计算机到用户共享”的连接。请参阅目录资源管理器用户界面说明。

若要使用持有者令牌创建新连接，请在笔记本或 Databricks SQL 查询编辑器中运行以下命令：

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

Databricks 建议对凭据之类的敏感值使用机密，而不是纯文本字符串。例如：

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

若要使用“OAuth 计算机到计算机”创建新连接，请在笔记本或 Databricks SQL 查询编辑器中运行以下命令：

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>'
)

将 HTTP 请求发送到外部系统

有了连接后，即可了解如何使用 http_request 内置 SQL 函数将 HTTP 请求发送到服务。

所需的权限：连接对象上的 USE CONNECTION。

在笔记本或 Databricks SQL 编辑器中运行以下 SQL 命令。替换占位符值：

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：连接对象，用于指定主机、端口、base_path 和访问凭据。
http-method：用于进行调用的 HTTP 请求方法。例如 GET、POST、PUT、DELETE
path：用于在 base_path 后连接以调用服务资源的路径。
json：与请求一起发送的 JSON 正文。
headers：用于指定请求头的映射。

创建 Unity Catalog 函数工具

验证连接可以正常使用后，创建使用连接的 Unity Catalog 函数。以下示例创建一个 Unity Catalog 函数工具，该工具可供代理用于将消息发布到 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

在代理代码中创建工具

若要使用 Python 将 HTTP 请求发送到外部服务，请使用 databricks-sdk 库中的 http_request 函数。此函数使用 Unity Catalog 连接向外部服务发送进行身份验证的 HTTP 请求。

所需的权限：连接对象上的 USE CONNECTION。

以下示例从代理代码内部发出外部 HTTP 请求。

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：连接对象，用于指定主机、端口、base_path 和访问凭据。
method：用于进行调用的 HTTP 请求方法。例如 GET、POST、PUT、DELETE
path：用于在 base_path 后连接以调用服务资源的路径。
json：与请求一起发送的 JSON 正文。
headers：用于指定请求头的映射。

示例笔记本

以下笔记本演示如何创建连接到 Slack、OpenAI 和 Azure AI 搜索的 AI 代理工具。

通过

将 AI 代理工具连接到外部服务

要求

外部服务的身份验证方法

创建与外部服务的连接

目录资源管理器

SQL

将 HTTP 请求发送到外部系统

创建 Unity Catalog 函数工具

在代理代码中创建工具

示例笔记本

Slack 消息传送代理工具

Microsoft Graph API 代理工具

Azure AI 搜索代理工具

反馈

其他资源