AI 代理身份验证

AI 代理通常需要向其他资源进行身份验证才能完成任务。例如，部署的代理可能需要访问矢量搜索索引来查询非结构化数据、用于调用基础模型的服务终结点或 Unity 目录函数来执行自定义逻辑。

本页介绍 Databricks Apps 上部署的代理的身份验证方法。有关在模型服务终结点上部署的代理，请参阅 AI 代理的身份验证（模型服务）。

Databricks Apps 为代理提供了两种身份验证方法。每个方法提供不同的用例：

方法	Description	何时使用
应用授权	代理使用具有一致权限的自动创建的服务主体进行身份验证。以前称为服务主体身份验证。	最常见的用例。当所有用户应具有相同的资源访问权限时使用。
用户授权	代理使用发出请求的用户标识进行身份验证。以前称为 On-Behalf-Of （OBO）身份验证。	当您需要为用户指定权限、审核追踪或通过 Unity Catalog 实现精细的访问控制时使用。

可以在单个代理中合并这两种方法。例如，使用应用授权访问共享矢量搜索索引，同时使用用户授权查询用户特定的表。

使用工作区用户界面或声明式自动化包配置身份验证

可以通过两种方式配置所有身份验证设置：

工作区 UI：从 “配置 ”步骤编辑应用并管理资源和范围。建议在工作区内对单个应用进行反复迭代时使用。
声明自动化捆绑包：在databricks.yml文件中声明资源、范围和环境变量，并通过databricks bundle deploy进行部署。建议在需要基于 Git 的版本控制、CI/CD 或跨工作区交付同一代理时使用。所有代理模板都配备了databricks.yml。

这两个路径都生成相同的运行时配置。本页的其余部分展示每个指令的两种形式，你可以选择一种，并在项目中保持一致。

若要通过任一路径将资源添加到应用，必须具有 Can Manage 对资源和应用的权限。

有关完整的捆绑包参考，请参阅应用资源和 app.resources。有关端到端捆绑包演练，请参阅使用声明性自动化捆绑包管理 Databricks 应用。

应用授权

默认情况下，Databricks 应用使用应用授权进行身份验证。创建应用时，Databricks 会自动创建服务主体，并充当应用的标识。

与应用交互的所有用户共享为服务主体定义的相同权限。如果希望所有用户看到相同的数据，或者当应用执行不绑定到用户特定访问控制的共享作时，此模型可以正常工作。

有关应用授权的详细信息，请参阅应用授权。

向 MLflow 试验授予权限

代理需要访问 MLflow 实验，以便记录日志和评估结果。授予服务主体 Can Edit 对实验的权限。

工作区 UI

单击应用主页上的 “编辑 ”。
转到 “配置 ”步骤。
在 “应用资源 ”部分中，添加具有 Can Edit 权限的 MLflow 试验资源。

请参阅将 MLflow 试验资源添加到 Databricks 应用。

声明性自动化捆绑包

在resources应用的databricks.yml列表中声明试验。在连接环境变量时，会引用此前分配给资源的name。

resources:
  apps:
    my_agent:
      name: 'my-agent'
      source_code_path: ./
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

重新部署软件包：

databricks bundle deploy
databricks bundle run my_agent

有关所有字段的信息，请参阅 app.resources.experiment。

向其他 Databricks 资源授予权限

如果代理使用其他 Databricks 资源（例如 Genie 空格、矢量搜索索引或 SQL 仓库），请为每个资源授予服务主体权限。

若要访问提示注册表，请在 Unity 目录架构上授予CREATE FUNCTIONEXECUTE和MANAGE权限以存储提示。

授予对 Unity 目录资源的访问权限时，还必须向所有下游依赖资源授予权限。例如，如果授予对 Genie 空间的访问权限，则还必须向其基础表、SQL 仓库和 Unity 目录函数授予访问权限。

工作区 UI

在 Databricks 工作区中创建或编辑应用时，通过 “应用资源 ”部分将资源添加到应用。

单击应用主页上的 “编辑 ”。
转到 “配置 ”步骤。
在 应用资源中，对于代理使用的每个资源，单击 +添加资源 并设置权限。

有关受支持的资源和屏幕截图的完整列表，请参阅将资源添加到 Databricks 应用。

声明性自动化捆绑包

声明代理在应用resources下的databricks.yml列表中使用的每个资源。以下示例显示了使用 MLflow 试验、服务终结点、Genie 空间、SQL 仓库、矢量搜索索引、Unity 目录函数和 Lakebase 实例的代理。资源name通过config.env从value_from引用，从而代理在运行时接收已解析的标识符。

bundle:
  name: my_agent

resources:
  apps:
    my_agent:
      name: 'my-agent'
      description: 'Custom agent deployed on Databricks Apps'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
          - name: LAKEBASE_INSTANCE_NAME
            value_from: 'database'

      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

        - name: 'sales-genie'
          genie_space:
            space_id: '<genie-space-id>'
            permission: 'CAN_RUN'

        - name: 'warehouse'
          sql_warehouse:
            id: '<warehouse-id>'
            permission: 'CAN_USE'

        - name: 'docs-index'
          uc_securable:
            securable_full_name: 'main.docs.chunks_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'lookup-function'
          uc_securable:
            securable_full_name: 'main.tools.order_lookup'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

        - name: 'database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'databricks_postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

targets:
  dev:
    mode: development
    default: true

重要

每个value_from中的config.env值都必须与resources列表中的name字段匹配。不匹配会导致环境变量在部署的应用中解析为 None。

部署并启动捆绑包：
```
databricks bundle validate
databricks bundle deploy
databricks bundle run my_agent
```
bundle deploy 上传源并配置资源。 bundle run 使用最新源启动或重启应用。 ** bundle run 参数是 resources.apps（在此为 my_agent）下的 YAML 密钥，而不是已部署应用的 name 字段。

有关每个资源子类型的完整架构，请参阅 app.resources。

下表列出了上述示例中使用的最小权限，以及每种资源类型的等效声明性自动化捆绑包值：

资源类型	工作区 UI 权限	声明式自动化包资源和权限
SQL 仓库	`Can Use`	将 `sql_warehouse` 替换为 `CAN_USE`
模型服务终结点	`Can Query`	将 `serving_endpoint` 替换为 `CAN_QUERY`
Unity 目录函数	`Can Execute`	使用 `uc_securable` 和 `securable_type: FUNCTION` 的 `EXECUTE`
精灵空间	`Can Run`	将 `genie_space` 替换为 `CAN_RUN`
矢量搜索索引	`Can Select`	使用 `uc_securable` 和 `securable_type: TABLE` 的 `SELECT`
Unity Catalog 表	`SELECT`	使用 `uc_securable` 和 `securable_type: TABLE` 的 `SELECT`
Unity 目录连接	`Use Connection`	使用 `uc_securable` 和 `securable_type: CONNECTION` 的 `USE_CONNECTION`
Unity 目录卷	`Can Read` 或 `Can Read and Write`	`uc_securable`与`securable_type: VOLUME`和`READ_VOLUME`或`WRITE_VOLUME`
Lakebase （已预配）	`Can Connect and Create`	将 `database` 替换为 `CAN_CONNECT_AND_CREATE`
Lakebase （自动缩放）	`Can Connect and Create`	将 `postgres` 替换为 `CAN_CONNECT_AND_CREATE`

遵循最小特权原则。仅向服务主体授予代理所需的权限，并为每个应用使用专用服务主体。有关完整列表，请参阅安全最佳做法。

用户授权

重要

用户授权为公共预览版。工作区管理员必须先启用它，然后才能使用用户授权。

用户授权允许代理使用发出请求的用户的标识进行作。这提供：

对敏感数据的按用户访问
Unity Catalog 强制执行的细粒度数据控制
用户特定的审计轨迹
自动强制实施行级筛选器和列掩码

当代理需要使用请求的用户标识（而不是应用的服务主体）访问资源时，请使用用户授权。

用户授权的工作原理

为代理配置用户授权时：

将 API 范围添加到应用：定义应用可以代表用户访问的 Databricks API。请参阅向应用添加范围。
用户凭证范围被限定：Databricks 使用用户的凭证，并将其限定在您所定义的 API 范围之内。
令牌转发：通过 HTTP 标头将范围缩小的令牌提供给您的应用 x-forwarded-access-token。
MLflow AgentServer 存储令牌：代理服务器会自动为每个请求存储此令牌，以便在代理代码中方便访问。

通过在创建或编辑应用或以编程方式使用 API 时在 Databricks 应用 UI 中添加范围来配置用户授权。有关详细说明，请参阅向应用添加范围。

具有用户授权的代理可以访问以下 Databricks 资源：

SQL 仓库
Genie Space
文件和目录
模型服务终结点
矢量搜索索引
Unity 目录连接
Unity 目录表

实现用户授权

若要实现用户授权，必须将授权范围添加到应用。授权范围限制应用可以代表用户执行的操作。有关可用作用域及其语义的列表，请参阅基于作用域的安全与权限提升。

工作区 UI

在 Databricks UI 中，转到应用的授权设置。
在 “用户授权”下，单击“ + 添加范围 ”，然后选择应用代表用户访问资源所需的范围。
保存更改并重启应用。

声明性自动化捆绑包

在databricks.yml的应用资源中的user_api_scopes下声明范围：

resources:
  apps:
    my_agent:
      name: 'my-agent'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

重新部署捆绑包并重启应用：
```
databricks bundle deploy
databricks bundle run my_agent
```
Note

首次在工作区启用用户授权后，您必须重新启动现有应用才能使用权限范围。请参阅向应用添加范围。

若要在代理代码中配置用户授权，请从 AgentServer 检索此请求的标头，并使用这些凭据构造工作区客户端。

在代理代码中，导入身份验证实用工具：

如果使用 databricks/app-templates 提供的模板之一，请导入提供的实用工具：
```
from databricks_app.utils import get_user_workspace_client
```
否则，请从代理服务器实用工具导入：
```
from agent_server.utils import get_user_workspace_client
```
该 get_user_workspace_client() 函数使用代理服务器捕获 x-forwarded-access-token 标头，并使用这些用户凭据构造工作区客户端，处理用户、应用和代理服务器之间的身份验证。
在查询时初始化工作区客户端，而不是在应用启动期间：

重要

在get_user_workspace_client()和invoke处理程序内部调用stream，而不是在__init__或应用启动时调用。用户凭据仅在用户发出请求时可用。在应用启动期间初始化将失败，因为尚不存在用户上下文。
```
# In your agent code (inside invoke or stream handler)
user_client = get_user_workspace_client()


# Use user_client to access Databricks resources with user permissions
response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)
```

有关添加范围和了解基于作用域的安全性的完整指南，请参阅基于作用域的安全性和特权提升。仅请求代理所需的最低范围，并记录代表用户执行的每个操作;请参阅有关用户授权的最佳做法。

向 Databricks MCP 服务器进行身份验证

Databricks 托管的 MCP 服务器通过形式为 https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> 和 https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema> 的 URL 将矢量搜索索引和 Unity Catalog 函数作为工具公开。有关可用服务器及其 URL 模式的列表，请参阅使用 Databricks 托管 MCP 服务器。

若要进行身份验证，请授予代理的服务主体（或使用用户授权）对这些架构中的每个下游资源的访问权限。

例如，如果代理使用以下 MCP 服务器 URL：

https://<your-workspace>/api/2.0/mcp/vector-search/prod/customer_support
https://<your-workspace>/api/2.0/mcp/vector-search/prod/billing
https://<your-workspace>/api/2.0/mcp/functions/prod/billing

必须授予对prod.customer_support和prod.billing中每个矢量搜索索引，以及prod.billing中每个 Unity Catalog 函数的访问权限。

工作区 UI

将每个索引和函数添加为 应用资源下的资源。遵循与其他 Databricks 资源授予权限相同的步骤。

声明性自动化捆绑包

在应用uc_securable列表下为每个索引和每个函数添加一个resources条目：

resources:
  apps:
    my_agent:
      resources:
        - name: 'support-index'
          uc_securable:
            securable_full_name: 'prod.customer_support.tickets_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'billing-index'
          uc_securable:
            securable_full_name: 'prod.billing.invoices_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'refund-function'
          uc_securable:
            securable_full_name: 'prod.billing.process_refund'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

重新部署组件包：

databricks bundle deploy
databricks bundle run my_agent

尚不支持作为自己的 Databricks 应用（带有前缀 mcp-的应用名称）托管的自定义 MCP 服务器作为捆绑资源。手动使用 Can Use 授予代理的服务主体databricks apps update-permissions，以在 MCP 服务器应用上执行。请参阅代理模板库中的 custom-mcp-server 技能。

后续步骤

反馈

此页面是否有帮助？

Last updated on 2026-04-25