AI 代理程式的驗證

AI 代理程式通常需要向其他資源進行驗證，才能完成工作。例如，部署中的代理可能需要存取向量搜尋索引來查詢非結構化資料，呼叫服務端點以呼叫基礎模型，或使用 Unity 目錄函式來執行自訂邏輯。

本頁介紹部署於 Databricks 應用程式中的代理程式的認證方法。關於部署於模型服務端點的代理，請參見 AI 代理認證（模型服務）。

Databricks Apps 提供兩種代理認證方式。每種方法都有不同的應用情境：

方法	Description	使用時機
應用程式授權	代理程式使用自動建立且權限一致的服務主體來驗證。之前稱為服務主體認證。	最常見的使用情境。當所有使用者都應該擁有相同的資源存取權時，才會使用。
使用者授權	代理會利用提出請求的使用者身份來進行認證。過去稱為 On-Behalf-Of（OBO）認證。	當你需要使用者專屬權限、稽核追蹤或 Unity Catalog 的細緻存取控制時，請使用。

你可以將兩種方法合併在單一藥劑中。例如，使用應用程式授權存取共享的向量搜尋索引，同時使用使用者授權查詢使用者專屬資料表。

應用程式授權

預設情況下，Databricks Apps 的驗證是透過應用程式授權進行的。 Azure Databricks 在你建立應用程式時會自動建立服務主體，並作為應用程式的身份。

所有與應用程式互動的使用者都擁有為服務主體定義的相同權限。這種模式在你希望所有使用者都能看到相同資料，或應用程式執行不依賴使用者專屬存取控制的共享操作時，表現良好。

有關應用程式授權的詳細資訊，請參閱應用程式授權。

授予 MLflow 實驗權限

你的代理需要存取 MLflow 實驗來記錄追蹤和評估結果。

授予服務主體 Can Edit 對 MLflow 的實驗權限：

在你的應用程式首頁點擊編輯。
進入設定步驟。
在 應用程式資源 區塊，新增 MLflow 實驗資源。

請參見「將 MLflow 實驗資源加入 Databricks 應用程式」。

授予其他 Databricks 資源權限

如果你的代理使用其他 Databricks 資源，例如 Genie 空間、向量搜尋索引或 SQL 倉庫，請透過 Databricks 應用程式介面授予服務主體權限。完整支援資源清單及設定說明，請參閱「新增資源至Databricks應用程式」。

若要存取提示註冊表，請授予 CREATE FUNCTION、EXECUTE 和 MANAGE Unity Catalog 結構的許可權來儲存提示。

下表列出代理存取共用 Databricks 資源所需的最低權限：

資源類型	權限
SQL 資料倉儲	`Can Use`
模型服務端點	`Can Query`
Unity 目錄功能	`CAN Execute`
精靈空間	`Can Run`
向量搜尋索引	`Can Select`
Unity 目錄數據表	`SELECT`
Unity Catalog 連線	`Use Connection`
Unity 目錄卷	`Can Read` 或 `Can Read and Write`
Lakebase	`Can Connect and Create`

在授權存取 Unity 目錄資源時，你也必須同時授予所有下游相關資源的權限。例如，如果您授權存取 Genie 空間，也必須同時授權其底層資料表、SQL 倉庫及 Unity 目錄函式的存取權。

新增資源的使用者必須同時擁有 Can Manage 資源和應用程式的權限。欲了解完整的支援資源清單及所有可用權限，請參見支援資源類型。

關於安全管理應用程式授權的最佳實務，包括憑證管理與最小權限原則，請參見應用程式授權。

使用者授權

這很重要

使用者授權處於公開預覽狀態。你的工作區管理員必須先啟用它，才能使用使用者授權。

使用者授權允許代理以提出請求的使用者身份進行行動。這提供了：

每位使用者的敏感資料存取權限
Unity 目錄強制執行的精細資料控制項
使用者專屬稽核追蹤
自動強制執行行級篩選器與欄位遮罩

當你的代理需要使用請求使用者的身份而非應用程式的服務主體存取資源時，請使用使用者授權。

使用者授權的運作方式

當你為代理程式設定使用者授權時：

為您的應用程式新增 API 範圍：定義應用程式可以代表使用者存取哪些 Databricks API。請參見「新增瞄準鏡到應用程式」。
使用者憑證會被縮減範圍：Azure Databricks 會取得使用者的憑證，並限制它們只能使用你定義的 API 範圍。
令牌轉發：範圍縮小的令牌將透過 x-forwarded-access-token HTTP 標頭傳遞給您的應用程式。
MLflow AgentServer 儲存令牌：Agent Server 會根據每個請求自動儲存此令牌，方便存取代理程式碼。

在建立或編輯應用程式時，或使用 API 程式化方式，在 Databricks Apps UI 中加入權限來設定使用者授權。詳見「新增內窺鏡到應用程式」以獲得詳細說明。

擁有使用者授權的代理程式可存取以下 Databricks 資源：

SQL 資料倉儲
精靈空間
檔案與目錄
模型服務端點
向量搜尋索引
Unity 目錄連結
Unity Catalog 資料表

實作使用者授權

要實作使用者授權，你必須在應用程式中新增授權範圍。權限範圍限制應用程式可以代表使用者執行的操作。

在 Databricks 介面中，前往你的 Databricks 應用程式授權設定。
點選 +新增範圍 ，選擇你想代表使用者存取資源的範圍。
儲存變更。

要在代理程式中設定使用者授權，請從 AgentServer 取得此請求的標頭，並用該憑證建構一個工作空間用戶端。

在你的代理代碼中，匯入認證工具：

如果使用 databricks/app-template 提供的範本，請匯入提供的工具：
```
from databricks_app.utils import get_user_workspace_client
```
否則，請從代理伺服器工具檔匯入：
```
from agent_server.utils import get_user_workspace_client
```
該 get_user_workspace_client() 函式使用 Agent Server 擷取 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 伺服器，請在你的 databricks.yaml 檔案中指定代理所需的所有資源。授權應用程式的服務主體（或使用使用者授權時的使用者）存取所有下游資源。

例如，如果您的代理使用下列列出的 MCP 伺服器網址，您必須授權存取prod.customer_support和prod.billing schemas中的所有向量搜尋索引，也必須授權prod.billing中的 Unity Catalog 所有函式。

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

使用宣告式自動化套件來配置認證

你可以用宣告式自動化套件（Declarative Automation Bundles）程式化設定所有認證設定，而不是用 Databricks Apps 的介面。此頁面展示基於 UI 的設定，說明所需的資源與權限，但同樣的設定也可以在你的 YAML 檔案中定義。完整的套件組態參考請參見 Apps in bundles 。

後續步驟

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-02-14