使用监督器 API 生成自定义代理（Beta 版）

Important

此功能在 Beta 版中。 帐户管理员可以从 “预览 ”页控制对此功能的访问。 请参阅 Manage Azure Databricks 预览版。

可以生成Azure Databricks应用代理，该代理使用 Supervisor API （Beta）进行业务流程，而不是在自己的代码中管理代理循环。 结果与 创作自定义代理相同：具有聊天 UI、 /invocations 终结点和身份验证的已部署应用。 区别在于，Azure Databricks为你运行代理循环。 您的 agent.py 进行单个 API 调用，Azure Databricks 处理工具选择、执行和响应合成。

监督器 API 适用于任何 受支持的基础模型。 更改 model 字段即可切换提供程序，无需更改工具定义或处理程序逻辑。

何时使用监督程序 API

当代理仅使用Azure Databricks托管的工具并且不需要工具调用之间的自定义逻辑时，监督程序 API 可正常工作。 如果代理需要以下任一项，请改用 自定义代理循环 ：

  • 客户端函数工具（监督程序 API 不能在一个请求中混合托管和客户端工具）
  • 除了Agent Bricks Knowledge Assistant的终结点以外的其他代理终结点
  • 自定义检索器、自定义输入/输出或精细流控制
  • 工具调用之间的自定义Python逻辑，例如条件分支或状态管理
  • 控制推理参数，例如 temperature

有关完整的 API 参考和支持的参数，请参阅监督 API （Beta）。

Requirements

使用监督程序 API 生成自定义代理

建议的起点是从最新的 Databricks 应用模板创建新应用。 最新的模板包括 AI 编码助手的内置 use-supervisor-api 技能，以及 add-tools 用于添加托管工具的技能。

若要从模板创建新应用，请参阅 创作 AI 代理并将其部署到 Databricks 应用。

从最新模板设置应用后，在 AI 编码助手中打开项目并运行：

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

技能更新您的 agent_server/agent.py 以使用托管工具调用 DatabricksOpenAI().responses.create() ，从而替换手动代理循环。 它还会添加 databricks-openai 依赖项并记下 beta 限制。

结果是相同的已部署应用，具有聊天 UI、身份验证和 /invocations 终结点，但使用更简单的代理代码。 有关完整部署工作流（部署到应用、添加工具、评估），请参阅 创作 AI 代理并将其部署到 Databricks 应用。

支持的工具和参数

有关支持的工具类型、请求参数和代码示例的完整列表，请参阅监督器 API（Beta）。

对于每个您添加的工具，请在databricks.yml中授予相应的资源权限。 请参阅 add-tools 中的 .claude/skills/ 技能以获取示例。

托管工具的授权

当监督程序 API 运行代理循环时，它会使用应用的标识或请求用户的标识执行托管工具。 根据应用的所有用户是否应共享对您的工具的相同访问权限，还是每个用户只能访问其自身权限允许的内容来进行选择。

  • 应用授权 （默认值）：工具作为应用的服务主体运行。 向代理使用的每个工具授予服务主体权限。 请参阅 应用授权。
  • 用户授权：工具以发送请求的用户身份运行，因此 Unity 目录权限、行筛选器和列掩码适用于每个用户。 请参阅以下部分。

以请求用户身份运行工具

Important

用户授权为公共预览版。 工作区管理员必须先启用它，然后才能将范围添加到应用。 请参阅 向应用添加范围。

若要代表请求用户运行托管工具，请将用户的令牌转发到 DatabricksOpenAI 客户端，并添加工具所需的用户授权范围。

  1. 添加应用所需的用户授权范围。 访问 Supervisor API 时都需要 ai-gateway。 为代理所使用的每种工具类型添加各工具的作用域：

    工具类型 所需范围
    所有工具 ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    app工具类型不支持用户授权。 若要将应用终结点调用为工具，请改用应用授权。 有关如何通过工作区 UI 或声明性自动化捆绑添加范围的信息，请参阅 用户授权。

  2. 在你的 agent.py 处理程序中，将用户工作区客户端传递给 DatabricksOpenAI。 这是唯一一处 Supervisor 特有的连接方式：不要用用户客户端直接调用资源，而是把资源交给运行代理循环的客户端处理。

    from databricks_openai import DatabricksOpenAI
from agent_server.utils import get_user_workspace_client

# Inside your invoke or stream handler, not at app startup
client = DatabricksOpenAI(
  workspace_client=get_user_workspace_client(),
  use_ai_gateway=True,
)

    get_user_workspace_client() 从请求头中读取转发的用户令牌，而这些请求头仅在查询时才会填充。 请在 invoke 和 stream 处理程序中调用它，切勿在 __init__ 中或在应用启动时调用。 如果缺少转发令牌，则生成的客户端不会作为请求用户进行身份验证。 有关如何验证代理作为调用方而不是应用的服务主体运行，请参阅 用户授权。

  3. 为每个运行该代理的用户授予每个工具所需的权限，例如在 Genie Space 上授予 CAN_RUN 权限，或在知识助理终结点上授予 CAN_QUERY 权限。

其他资源

  • Last updated on