在 Databricks 應用程式上建立多代理系統

多代理協調器不是建立一個能處理所有事情的代理，而是從單一入口點將請求導向專門的子代理。

例如，你可以結合查詢非結構化文件的 RAG 代理與查詢結構化資料的 Genie 代理，讓使用者能從多個來源獲得答案。

編排器將每個子代理視為工具，並利用其指令將請求路由到正確的代理。編排器支援以下子代理類型：

Databricks Apps 代理：其他以 Databricks 應用程式形式部署的代理，透過 Responses API 呼叫。
Genie Agents：透過內建的 Azure Databricks MCP 伺服器進行自然語言資料查詢。
服務端點：支援 Responses API 的知識助理、代理或建立於 Model Serving 的模型。

Requirements

Databricks CLI 已安裝並驗證。應用程式對應用程式呼叫需要 OAuth。請參閱安裝或更新 Databricks CLI。
Python 3.11 或以上。
uv 套件管理器。請參見 uv 安裝。
在您的工作區啟用 Databricks 應用程式。請參閱設定 Databricks Apps 工作區和開發環境。
至少要有一個子代理進行協調：Genie 代理、另一個 Databricks 應用程式、知識助理或服務端點。

先試試探員主管

在建立自訂編排器之前，請考慮使用 Supervisor Agent 來建立一個協調的多代理系統。它透過使用者介面幫你建置和管理多代理系統。你可以連接 Genie 代理、代理端點、Unity 目錄函式、MCP 伺服器和自訂代理，並利用專家的自然語言回饋，隨時間提升協調品質。

如果你需要 Agent Supervisor 不支援的自訂路由邏輯或編排行為，可以在 Databricks Apps 上建置多代理系統。

複製多代理編排器範本

多代理編排器範本提供專案結構與編排邏輯的支架，使用 OpenAI Agents SDK 進行。同時也包含技能檔案，教導 AI 編碼助理如何開發編排器。

複製範本，然後進入資料夾：

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk-multiagent

設定子代理

編排器可呼叫的每個後端都定義為中SUBAGENTS列表中的子代理agent_server/agent.py。

取消留言並設定你需要的條目。更新說明，以更詳細地描述子代理。描述品質直接關乎編排器將請求路由到正確子代理的能力：

SUBAGENTS = [
    {
        "name": "genie",
        "type": "genie",
        "space_id": "<YOUR-GENIE-SPACE-ID>",
        "description": (
            "Query a Genie Agent for structured data analysis. "
            "Use this for questions about data, metrics, and tables."
        ),
    },
    {
        "name": "app_agent",
        "type": "app",
        "endpoint": "<YOUR-APP-AGENT-NAME>",
        "description": (
            "Query a specialist agent deployed as a Databricks App. "
            "Use this for questions the specialist app agent handles."
        ),
    },
    {
        "name": "knowledge_assistant",
        "type": "serving_endpoint",
        "endpoint": "<YOUR-ENDPOINT>",
        "description": (
            "Query the knowledge-assistant endpoint on Model Serving. "
            "Use this for knowledge-base and documentation lookups. "
            "The endpoint must have task type agent/v1/responses."
        ),
    },
]

每個條目自動成為編排器可呼叫的可用工具。你必須啟用至少一個子代理。

下表描述每種子代理類型：

Type	它如何連接	要求
`app`	回應 API 透過 `apps/<name>`	OAuth 認證，目標應用程式 `CAN_USE` 的權限
`genie`	內建 Azure Databricks MCP 伺服器	Genie Agent ID、`CAN_RUN` 權限
`serving_endpoint`	回應 API 透過端點名稱	端點必須在服務介面上有任務類型代理（回應）。包含知識助理、代理與模型。

自訂編排器

編排代理是在函式 create_orchestrator_agent() 中建立的。更新說明書，說明你的具體工具以及使用時機：

Agent(
    name="Orchestrator",
    instructions=(
        "You are an orchestrator agent. Route the user's request to the "
        "most appropriate tool or data source:\n"
        "- Use the Genie MCP tools for questions about structured data in <dataset_name> that contains information about <topic>\n"
        "- Use query_app_agent for questions or tasks that the specialist app agent handles for ...\n"
        "- Use query_knowledge_assistant for knowledge-base lookups about <topic>.\n"
        "If unsure, ask the user for clarification."
    ),
    model="databricks-claude-sonnet-4-5",
    mcp_servers=[mcp_server] if mcp_server else [],
    tools=subagent_tools,
)

Tip

編排器指令越具體，對請求的路由就越準確。描述每個工具的用途以及它處理的問題類型。

配置資源與權限

在databricks.yml中宣告你的編排器所需的資源。每個子代理類型都需要自己的資源條目：

resources:
  - name: 'genie_space'
    genie_space:
      name: 'Genie Agent'
      space_id: '<YOUR-GENIE-SPACE-ID>'
      permission: 'CAN_RUN'

  - name: 'serving_endpoint'
    serving_endpoint:
      name: '<YOUR-ENDPOINT>'
      permission: 'CAN_QUERY'

更新 databricks.yml 中的佔位符值，使其與你在 agent_server/agent.py 中設定的子代理相匹配。

授權編排器存取目標 Databricks 應用程式

如果你的協調器呼叫子代理程式 Databricks 應用程式，你必須手動授予協調器應用程式的服務主體在目標應用程式上的CAN_USE 權限。此權限不能宣告為 bundle 資源，必須在部署後套用。

Note

service_principal_name權限請求中的欄位必須是服務主體的客戶端 ID（UUID），而非顯示名稱。使用顯示名稱會在不通知的情況下成功，但不會授予權限。命令將databricks apps get值傳回為service_principal_client_id。

查找編排器應用程式的服務主體用戶端識別碼：

databricks apps get <YOUR-ORCHESTRATOR-APP-NAME> --output json | jq -r '.service_principal_client_id'

將編排器應用程式的服務主體 CAN_USE 權限授予目標應用程式。

databricks apps update-permissions <TARGET-APP-NAME> \
  --json '{"access_control_list": [{"service_principal_name": "<SP-CLIENT-ID>", "permission_level": "CAN_USE"}]}'

本地測試

建立你在地的環境並啟動代理：

uv run quickstart
uv run start-app

這個 quickstart 腳本會設定 Azure Databricks 認證程序，並建立 MLflow 實驗以用來追蹤。設定完成後，start-app啟動代理伺服器和聊天介面。http://localhost:8000

部署至 Databricks 應用程式

使用宣告式自動化套件部署編排器：

驗證束狀配置：
```
databricks bundle validate
```
將套件部署到你的工作空間：
```
databricks bundle deploy
```

啟動應用程式：

databricks bundle run agent_openai_agents_sdk_multiagent

Important

bundle deploy 上傳檔案但無法啟動應用程式。執行 bundle run 啟動應用程式。

其他資源

部署好編排器後，請探索以下資源：

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-08