代理人的驗證

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

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

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

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

透過工作區介面或宣告式自動化套件來設定認證

你可以用兩種方式配置所有認證設定：

• Workspace UI：從 配置 步驟編輯應用程式並管理資源與範圍。 建議在工作區中迭代單一應用程式時使用。
• 宣告式自動化套件：在databricks.yml檔案中宣告資源、範圍與環境變數，然後以databricks bundle deploy部署。 建議當你想要基於 Git 的版本管理、CI/CD，或是跨工作空間提供相同代理時。 所有 代理範本都附帶著 一個 databricks.yml.

這兩條路徑產生相同的執行時配置。 本頁其餘部分會以兩種形式列出每項指令，讓你選擇其中一種，並在專案中保持一致。

要透過任一路徑將資源加入應用程式，你必須同時擁有 Can Manage 資源和應用程式的權限。

完整套件參考，請參閱 app resource 和 app.resources。 如需完整流程套件的導覽，請參閱 使用宣告式自動化套件管理 Databricks 應用程式。

應用程式授權

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

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

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

授予 MLflow 實驗權限

你的代理需要存取 MLflow 實驗來記錄追蹤和評估結果。 授予服務主體 Can Edit 在這個實驗上的權限。

工作區 UI（使用者介面）

1. 在你的應用程式首頁點擊 編輯 。
2. 進入 設定 步驟。
3. 在 應用程式資源 區塊，請經授權新增 MLflow 實驗資源 Can Edit 。

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

宣告式自動化套件組

1. 在你的應用程式 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'
   

2. 重新部署套件：

   databricks bundle deploy
   databricks bundle run my_agent
   

所有欄位請參見 app.resources.experiment 。

授予其他 Databricks 資源權限

如果你的代理使用其他 Databricks 資源，例如 Genie 代理、AI 搜尋索引或 SQL 倉庫，請對每個資源授予服務主體權限。

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

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

工作區 UI（使用者介面）

在 Databricks 工作區建立或編輯應用程式時，透過 應用程式資源 區塊新增資源。

1. 在你的應用程式首頁點擊 編輯 。
2. 進入 設定 步驟。
3. 在 App 資源中，點選 + 新增資源 ，針對代理使用的每個資源設定權限。

完整支援資源清單及截圖請參閱 「新增資源至Databricks應用程式 」。

宣告式自動化套件組

1. 在你的應用程式下的resources清單中，宣告代理使用的每一個資源databricks.yml。 以下範例展示了一個代理，該代理使用了 MLflow 實驗、服務端點、Genie 代理、SQL 倉庫、AI 搜尋索引、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 必須與列表中的某個 name 欄位 resources 相符。 不匹配會導致環境變數在已部署的應用程式中被解析為 。None

2. 部署並啟動套件：

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent
   

   bundle deploy 上傳原始碼並設定資源。 bundle run 用最新的原始碼啟動或重新啟動應用程式。 參數 bundle run 是位於 resources.apps 下的 YAML 金鑰（這裡是 my_agent），而不是已部署應用程式的 name 欄位。

每個資源子類型的完整架構，請參見 app.resources。

下表列出上述範例中使用的最低權限值及各資源類型的宣告式自動化套件（Declarative Automation Bundles）值：

遵循最低權限原則。 只授予服務主體需要的權限，並為每個應用程式使用獨立的服務主體。 完整清單請參見 安全最佳實務。

使用者授權

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

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

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

使用者授權的運作方式

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

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

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

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

• SQL 資料倉儲
• 精靈特工
• 檔案與目錄
• 模型服務端點
• AI 搜尋索引
• Unity 目錄連結
• Unity Catalog 資料表

實作使用者授權

要實作使用者授權，你必須在應用程式中新增授權範圍。 權限範圍限制應用程式可以代表使用者執行的操作。 關於可用範圍及其語意列表，請參見 基於範圍的安全與權限提升。

工作區 UI（使用者介面）

1. 在 Databricks 介面中，前往你應用程式的 授權 設定。
2. 在 使用者授權中，點擊 + 新增範圍 ，選擇應用程式需要的範圍來代表使用者存取資源。
3. 儲存更改並重新啟動應用程式。

宣告式自動化套件組

1. 在user_api_scopes的應用程式資源中，在databricks.yml處宣告範圍：

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

2. 重新部署套件並重新啟動應用程式：

   databricks bundle deploy
   databricks bundle run my_agent
   

   Note

   在首次啟用工作區的使用者授權後，必須重新啟動現有的應用程式才能使用這些範疇。 請參見「新增瞄準鏡到應用程式」。

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

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

   如果使用 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 標頭，並建立一個包含使用者憑證的工作區用戶端，負責使用者、應用程式與代理伺服器之間的認證。

2. 請在查詢時初始化工作區用戶端，而非應用程式啟動時：

   這很重要

   請在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)
   

關於新增範圍及理解基於範圍的安全，請參閱「 範圍式安全性與權限提升」。 只請求代理所需的最小範圍，並記錄代表使用者執行的每一個動作;請參閱 使用者授權的最佳實務。

驗證使用者授權

在你新增範圍並撥打 get_user_workspace_client()電話後，確認客服人員是以來電者身份運作，而非應用程式的服務主體。 如果轉發的標記遺失，則 get_user_workspace_client() 會回退給服務主體而不提升，因此代理可以在仍作為應用程式的同時回傳正常的回應。 要檢查時，新增一個 whoami 工具並以自己身份呼叫。 如果它回傳你的使用者名稱，代表使用者授權有效。

current_user.me() 已涵蓋於預設 iam.current-user:read 範圍，因此此測試不需要新增任何範圍。

from agents import Agent, function_tool
from agent_server.utils import get_user_workspace_client

@function_tool
def whoami() -> str:
    """Returns the identity of the current user."""
    user_wc = get_user_workspace_client()
    return user_wc.current_user.me().user_name

agent = Agent(
    name="my-agent",
    instructions=(
        "When the user asks who they are, call the whoami tool "
        "and return the raw result."
    ),
    model="databricks-claude-sonnet-4-6",
    tools=[whoami],
)

重新部署代理。 請參閱 建立代理程式並將其部署到 Databricks Apps。

工作區 UI（使用者介面）

Workspace UI 測試是最快的合理性檢查，且不需要 OAuth 標記。

1. 範圍變更會立即生效，但內部快取可能需要長達 5 分鐘才能重新整理——請等這麼久再測試（無需重新啟動應用程式）。 請務必清除瀏覽器 App URL 的 Cookie（請參考下方下拉選單的步驟），否則 session 會重複使用範圍變更前發出的令牌。
2. 確認你有 CAN USE 使用該應用程式的權限。 請參閱 設定 Databricks 應用程式的許可權。
3. 在瀏覽器中開啟應用程式網址。 首次造訪時，接受針對所要求權限範圍的同意提示。
4. 在聊天室詢問Who am I?並確認客服是否回傳你的使用者名稱（例如）。 you@your-company.com

Python

使用 CLI 設定檔或服務主體憑證來呼叫代理。 查詢選項請參閱 查詢部署在 Azure Databricks 上的代理程式，以及參閱 使用權杖驗證連線至 API Databricks 應用程式 以了解如何產生 OAuth 權杖。

1. 範圍變更會立即生效，但內部快取可能需要長達 5 分鐘才能重新整理，因此測試前請稍等（無需重新啟動應用程式）。

2. 以你自己身份召喚代理人：

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   app_name = "<your-app-name>"
   prompt = [{"role": "user", "content": "Call the whoami tool and return only the raw result."}]
   
   w = WorkspaceClient(profile="<your-profile>")
   client = DatabricksOpenAI(workspace_client=w)
   response = client.responses.create(model=f"apps/{app_name}", input=prompt)
   print(response.output_text)
   

   輸出應該是你的使用者名稱——例如。 you@your-company.com

如果工具回傳的是 UUID 而非使用者名稱，表示 x-forwarded-access-token 標頭無法傳達工具，代理程式會回退到應用程式的服務主體（UUID 是應用程式的服務主體客戶端 ID）。 診斷時，請確認以下各項：

1. 使用者授權已在工作區啟用。
2. 應用程式已設定權限範圍。
3. get_user_workspace_client() 會在 @invoke 或 @stream 處理常式內呼叫，而不是在應用程式啟動時呼叫。
4. 程式碼使用 get_user_workspace_client() 且 不 WorkspaceClient()。

有幾點需要注意：

• 生產前先拆除 whoami 工具。 它僅用於診斷，並向任何能呼叫代理的人暴露使用者身份。
• 用第二個使用者測試。 單用戶檢查確認令牌已轉發;第二位呼叫者確認每個請求都有自己的身份，而非共享的備援。
• 千萬不要記錄轉發的代幣。 請參閱 用戶授權的最佳做法。
• 要驗證特定的作用域，請替換 current_user.me() 成需要該作用域的呼叫。 例如，針對倉儲的 SELECT current_user() 陳述式會端對端地運用 sql 範圍。

認證至 Databricks MCP 伺服器

Databricks 管理的 MCP 伺服器會透過形如 https://<workspace>/api/2.0/mcp/ai-search/<catalog>/<schema> 和 https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema> 的 URL，將 AI Search 索引和 Unity Catalog 函式公開為工具。 舊有 /api/2.0/mcp/vector-search/ 的 URL 前綴仍持續運作，以維持向下相容性。 關於可用伺服器及其 URL 模式的列表，請參見 Azure Databricks 管理的 MCP 伺服器。

要驗證時，請授權代理的服務主體（或使用使用者授權時的使用者）存取這些結構中所有下游資源。

例如，如果您的代理程式使用下列 MCP 伺服器 URL：

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

你必須授予對 prod.customer_support 和 prod.billing 中每個 AI Search 索引的存取權，以及對 prod.billing 中每個 Unity Catalog 函式的存取權。

工作區 UI（使用者介面）

將每個索引和函式都加入 App 資源作為資源。 請遵循與授權其他 Databricks 資源相同的步驟。

宣告式自動化套件組

1. 在你的應用程式清單下，為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'
   

2. 重新部署套件：

   databricks bundle deploy
   databricks bundle run my_agent
   

向 MCP 服務進行驗證

前一節介紹的是受管理的 MCP 伺服器，這些伺服器會揭露你自己的 Unity 目錄資料和功能。 MCP 服務則不同：它們涵蓋你註冊的外部 MCP 伺服器，以及 Azure Databricks 為第三方 SaaS 工具提供的內建system.ai.*服務（例如 system.ai.google_calendar）。 兩種類型都會透過位於 https://<workspace>/ai-gateway/mcp-services/<catalog>.<schema>.<mcp-service> 的 Unity Gateway 叫用，且兩者的驗證方式相同。

每個 MCP 服務都是獨立的 Unity 目錄可保護，所以你一次只授權一個服務存取權限。

授權來電者使用該服務

若要呼叫某項服務，呼叫端需要在該服務上具有 EXECUTE，以及在其父目錄和結構描述上具有 和 USE SCHEMA。 EXECUTE 單靠這點還不夠，因為 Unity Catalog 也會檢查上層鏈結（請參閱 授與隊友存取權）。

對於內建 system.ai.* 服務，帳號使用者預設就擁有這些權限，所以通常不需要授權。

若在你自己的目錄與架構中建立服務，請自行授權呼叫者：應用程式的服務主體用於應用程式身份存取，或呼叫使用者或群組作為代理存取權限。 請在目錄總管中使用 權限 索引標籤，或使用 REST API（替換為您自己的 <catalog>.<schema>.<service>）：

databricks api patch "/api/2.1/unity-catalog/permissions/mcp_service/<catalog>.<schema>.<service>" \
  --json '{ "changes": [ { "principal": "data-team", "add": ["EXECUTE"] } ] }'
databricks api patch "/api/2.1/unity-catalog/permissions/catalog/<catalog>" \
  --json '{ "changes": [ { "principal": "data-team", "add": ["USE_CATALOG"] } ] }'
databricks api patch "/api/2.1/unity-catalog/permissions/schema/<catalog>.<schema>" \
  --json '{ "changes": [ { "principal": "data-team", "add": ["USE_SCHEMA"] } ] }'

轉發使用者的令牌以供代表存取

代理存取權以通話使用者身份執行每通電話，因此應用程式必須被允許將該使用者的令牌轉發給 Unity Gateway。 透過新增 ai-gateway 使用者 API 範圍來啟用此功能：在應用程式資源上宣告 user_api_scopes: [ai-gateway] （參見 「新增應用程式範圍」），然後用 Author 代理程式的每使用者客戶端get_user_workspace_client()呼叫服務 ，部署到 Databricks 應用程式上。

每位使用者第一次呼叫服務時，必須授權。 在他們這麼做之前，該呼叫會傳回 JSON-RPC 錯誤 -32042，並附帶登入url於error.data.elicitations[]。 顯示該連結，讓使用者可以在應用程式內授權，或請他們在 Catalog Explorer 中開啟該服務，然後按一下登入。

以 Data bricks 應用程式（應用程式名稱前綴為 mcp-）所託管的自訂 MCP 伺服器尚未作為套裝資源支援。 手動在 MCP 伺服器應用程式Can Use中授予代理的服務主體databricks apps update-permissions權限。 請參閱代理範本庫中的 custom-mcp-server 技能 。

下一步

• 撰寫代理並部署到 Databricks 應用程式上
• 使用 Declarative Automation Bundles 管理 Databricks 應用程式
• 在 Databricks 應用程式中設定授權
• 為 Databricks 應用程式新增資源
• 應用程式資源參考