使用 Supervisor API（測試版）建立自訂代理

Important

這項功能位於 測試版 (Beta) 中。 帳號管理員可從 預覽 頁面控制此功能的存取權限。 請參閱 管理 Azure Databricks 預覽。

你可以建立一個使用 Supervisor API （Beta）來編排的 Azure Databricks Apps 代理程式，而不是自己在程式碼中管理代理迴圈。 結果就像 撰寫自訂代理一樣：一個部署好的應用程式，擁有聊天介面、 /invocations 端點和認證功能。 差別在於 Azure Databricks 會幫你執行代理迴圈。 你的 agent.py 會呼叫單一 API，Azure Databricks 負責工具選擇、執行和回應綜合。

Supervisor API 可支援任何 支援的基礎模型。 在不更改工具定義或處理器邏輯的情況下，更改 model 字段以切換供應商。

何時使用 Supervisor API

當你的代理只使用 Azure Databricks 託管的工具，且不需要工具呼叫間的自訂邏輯時，Supervisor API 運作良好。 如果你的代理需要以下其中一項，則改用 自訂代理迴圈 ：

  • 用戶端功能工具（Supervisor API 無法在同一請求中混合託管與用戶端工具）
  • 除 Agent Bricks 知識助理 端點之外的其他代理端點
  • 自訂擷取器、自訂輸入/輸出，或細緻的串流控制
  • 工具呼叫間的自訂 Python 邏輯，例如條件分支或狀態管理
  • 對推論參數的控制，例如 temperature

完整 API 參考資料及支援參數，請參見 Supervisor API（Beta）。

Requirements

使用 Supervisor API 建立自訂代理

建議的起點是從最新的 Databricks 應用程式範本建立一個新應用程式。 最新範本包含內建 use-supervisor-api 的 AI 編碼助理技能，以及 add-tools 新增託管工具的技能。

要從範本建立新應用程式，請參閱 「Author an AI agent and deploy it on Databricks Apps」。

當你的應用程式從最新範本設定好後，請用你的 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 的限制。

結果是同樣部署的應用程式，具備聊天介面、認證 /invocations 和端點，但代理程式更簡單。 完整的部署工作流程（部署到應用程式、新增工具、評估），請參閱 「撰寫 AI 代理並部署於 Databricks 應用程式」。

支援的工具與參數

欲了解完整的支援工具類型、請求參數及程式碼範例，請參見 Supervisor API（Beta）。

對於你新增的每個工具，也要在 中授予相應資源權限 databricks.yml。 請參考 add-tools 技能範例 .claude/skills/ 。

託管工具授權

當 Supervisor API 執行代理迴圈時，會執行託管工具，使用應用程式的身份或請求使用者的身份。 根據所有應用程式使用者是否應該共享相同的工具存取權，或是每位使用者只存取自己權限允許的權限來選擇。

  • 應用程式授權 （預設）：工具作為應用程式的服務主體執行。 授予服務負責人對代理人使用的每一項工具的權限。 請參閱 應用程式授權。
  • 使用者授權：工具會以發送請求的使用者身份執行，因此 Unity 目錄的權限、列篩選器和欄位遮罩會依使用者而套用。 請參見以下章節。

以請求使用者身份執行工具

Important

使用者授權處於 公開預覽狀態。 您的工作區管理員必須先啟用它，才能將範圍新增至您的應用程式。 請參見「新增瞄準鏡到應用程式」。

若要代表請求使用者執行託管工具，請將使用者的權杖轉發給 DatabricksOpenAI 用戶端，並新增工具所需的使用者授權範圍。

  1. 加入你的應用程式所需的使用者授權範圍。 ai-gateway 是所有 Supervisor API 存取的必要條件。 為代理所使用的每種工具類型新增每個工具的範圍：

    工具類型 所需範圍
    所有工具 ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    不支援使用者授權的 app 工具類型。 若要呼叫應用程式端點作為工具，請改用應用程式授權。 關於如何透過工作區介面或宣告式自動化套件新增範圍，請參見 使用者授權。

  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. 授權每位執行代理的使用者對每個工具（例如 CAN_RUN 在 Genie 代理或 CAN_QUERY 知識助理端點）擁有所需的權限。

其他資源

  • Last updated on