監督 API（測試版）

Important

這項功能位於測試版 (Beta) 中。工作區管理員可以從 [預覽 ] 頁面啟用這項功能。請參閱管理 Azure Databricks 預覽。

Supervisor API 簡化了在 Azure Databricks 上構建自訂代理程式，並支援長時間執行任務的背景模式。你只需向相容OpenResponses端點（POST ai-gateway/mlflow/v1/responses）請求，定義模型、工具與指令，Azure Databricks會替你執行代理迴圈：反覆呼叫模型、選擇並執行工具，並綜合最終回應。

在 Azure Databricks 上建立客製化工具呼叫代理有三種方法：

Agent Bricks Supervisor Agent （推薦）：完全宣告式設計，並透過人工回饋進行優化，追求最高品質。
監督 API：以程式方式建置自訂代理程式——在執行時選擇模型、控制每個請求使用的工具，或在開發過程中反覆修改。當你需要控制模型選擇，同時將代理迴圈管理轉交給 Azure Databricks 時，這是正確的選擇。
AI Gateway 統一或原生 API：撰寫您自己的代理迴圈。 Azure Databricks 只提供 LLM 推理層。在可能的情況下使用統一 API，以啟用模型切換，或在將現有程式碼移植到 Azure Databricks 或使用提供者專屬功能時，使用提供者專用的原生 API（/openai、/anthropic、/gemini）。

Requirements

Unity AI Gateway 的 AI 治理已為您的帳戶啟用。請參閱管理 Azure Databricks 預覽。
- 由於 Supervisor API 透過 Unity AI Gateway 運行，AI Gateway 功能如推論表、速率限制與備援皆適用。本測試版不支援使用追蹤功能。
將 OpenTelemetry 追蹤資料儲存在 Unity Catalog 中，為你的帳號啟用。請參閱管理 Azure Databricks 預覽。
- 將 Supervisor API agent 迴圈的追蹤資料儲存在 Unity 目錄資料表中。
一個位於支援區域的Azure Databricks工作區。
已為您的工作區啟用了 Unity Catalog。請參閱為 Unity Catalog 啟用工作區。
你傳遞的工具（Genie 代理、 Unity 目錄函數、 MCP 伺服器、知識助理、應用程式）必須已經設定並可存取。
該 databricks-openai 套件安裝了： pip install databricks-openai

步驟 1：創建單次 LLM 呼叫

從一個基本的通話開始，不用工具。 DatabricksOpenAI用戶端會自動設定你工作區的基礎網址和認證：

from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  stream=False
)

print(response.output_text)

步驟 2：新增託管工具以執行代理迴圈

當你在請求中包含工具時，Azure Databricks 會代表你管理一個多回合循環：模型決定呼叫哪些工具，Azure Databricks 執行它們，將結果回饋給模型，然後重複此過程直到模型產生最終答案。

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Summarize recent customer reviews and flag any urgent issues."}],
  tools=[
    {
      "type": "genie_space",
      "name": "Customer reviews",
      "description": "Answers customer review questions using SQL",
      "genie_space": {"space_id": "<genie-space-id>"}
    },
    {
      "type": "dashboard",
      "name": "Customer reviews dashboard",
      "description": "Answers questions about the customer reviews dashboard",
      "dashboard": {"dashboard_id": "<dashboard-id>"}
    },
    {
      "type": "uc_function",
      "name": "Flag urgent review",
      "description": "Flags a review as requiring urgent attention",
      "uc_function": {"name": "<catalog>.<schema>.<function_name>"}
    },
    {
      "type": "table",
      "table": {
        "name": "<catalog>.<schema>.<table_name>",
        "description": "Reads from the customer reviews table"
      }
    },
    {
      "type": "vector_search_index",
      "vector_search_index": {
        "name": "<catalog>.<schema>.<index_name>",
        "description": "Searches the product documentation index for relevant passages"
      }
    },
    {
      "type": "knowledge_assistant",
      "name": "Internal docs",
      "description": "Answers questions from internal documentation",
      "knowledge_assistant": {"knowledge_assistant_id": "<knowledge-assistant-id>"}
    },
    {
      "type": "serving_endpoint",
      "name": "Custom agent",
      "description": "Calls a custom agent served from a Databricks model serving endpoint",
      "serving_endpoint": {"name": "<serving-endpoint-name>"}
    },
    {
      "type": "vector_search_index",
      "name": "Product docs",
      "description": "Looks up product documentation by semantic search",
      "vector_search_index": {
        "name": "<catalog>.<schema>.<index>",
        "columns": ["title", "content"]
      }
    },
    {
      "type": "app",
      "name": "Support agent",
      "description": "Custom application endpoint",
      "app": {"name": "<app-name>"}
    },
    {
      "type": "uc_connection",
      "name": "GitHub",
      "description": "Searches GitHub for issues and pull requests",
      "uc_connection": {"name": "<uc-connection-name>"}
    },
    {
      "type": "uc_mcp",
      "name": "Slack",
      "description": "Searches and reads from the team Slack workspace",
      "uc_mcp": {"name": "<catalog>.<schema>.<mcp_service>"}
    },
    {
      "type": "databricks_web_search",
      "name": "Web search",
      "description": "Searches the public web for current information and returns a synthesized answer with citations",
      "web_search": {}
    },
    {
      "type": "volume",
      "volume": {
        "name": "<catalog>.<schema>.<volume>",
        "description": "Searches files in a Unity Catalog volume"
      }
    },
  ],
  stream=True
)

for event in response:
  print(event)

步驟 3（可選）：連接系統管理連線的第三方服務

Azure Databricks 提供系統管理連接，支援 Google Drive、GitHub、Atlassian、SharePoint 和 Glean 等熱門第三方服務。這些連線是建立自己外部 MCP 伺服器的快速替代方案——你仍然可以使用該 uc_connection 工具類型連接到你自己設定的任何外部 MCP 伺服器。

系統管理連線需要在您的工作區啟用第三方代理連接器 Beta 。請參閱管理 Azure Databricks 預覽。

支援下列連接器：

連接器	Description
`system_ai_agent_google_drive`	搜尋並閱讀 Google Drive 上的檔案。
`system_ai_agent_github_mcp`	存取 GitHub 倉庫、問題及提取請求。
`system_ai_agent_atlassian_mcp`	搜尋並管理 Atlassian 資源（Jira、Confluence）。
`system_ai_agent_sharepoint`	搜尋並閱讀 SharePoint 上的檔案。
`system_ai_agent_glean_mcp`	搜尋由 Gelean 索引的企業級內容。

使用tools工具類型在uc_connection陣列中傳遞一個連接器，並將name欄位設為連接器名稱。

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "List my open GitHub pull requests."}],
  tools=[
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "system_ai_agent_github_mcp"
      }
    }
  ],
)

用戶對電腦（U2M）驗證

每位使用者都要個別驗證。 OAuth 代幣不會在使用者間共享。在第一次使用使用者尚未驗證的連接器的請求中，回應會完成並包含 status: "failed" 和 oauth 錯誤，以及登入網址。

{
  "status": "failed",
  "error": {
    "code": "oauth",
    "message": "Failed request to <connector>. Please login first at <login-url>."
  }
}

在瀏覽器中開啟 URL，完成 OAuth 流程，然後重複執行相同的請求。

步驟 4（可選）：新增客戶端功能工具

當你希望應用程式能同時執行自訂邏輯與Azure Databricks託管工具時，請使用 function 工具。使用 type: "function"、name、可選的 description，以及 JSON Schema parameters 物件來宣告一個函式工具：

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "<user prompt>"}],
  tools=[
    {
      "type": "function",
      "name": "<client-side-function-name>",
      "description": "<description of what this function does>",
      "parameters": {
        "type": "object",
        "properties": {"<param-name>": {"type": "string"}},
        "required": ["<param-names>"],
        "additionalProperties": False,
      },
    }
  ],
)

Supervisor API 不會在請求間儲存對話狀態，因此客戶端函式呼叫會分兩個回合：

第一回合。 模型會回傳一個function_call項目（例如「與 get_weather通話location=Paris」），而非最終答案。
你的程式碼 在本地執行這個函式並產生結果。
第二回合。 再次呼叫 responses.create()，並傳入原始輸入、模型的 function_call，以及一個內含你的結果的新 function_call_output。模型會利用結果來產生最終答案。

用戶端功能工具範例

import json
from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)
MODEL = "databricks-claude-sonnet-4-5"

GET_WEATHER = {
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
        "additionalProperties": False,
    },
}

def run_get_weather(args):
    return json.dumps({
        "location": args["location"],
        "temp_c": 18,
        "condition": "sunny",
    })

CLIENT_TOOLS = {"get_weather": run_get_weather}
TOOLS = [GET_WEATHER]

input_list = [{"role": "user", "content": "What's the weather in Paris?"}]

# Turn 1 — model emits a function_call
resp = client.responses.create(model=MODEL, input=input_list, tools=TOOLS)

# Echo the model's turn into history, then execute pending client function_calls
input_list += [item.model_dump() for item in resp.output]
for item in resp.output:
    if item.type == "function_call" and item.name in CLIENT_TOOLS:
        args = json.loads(item.arguments)
        # Execute the client-side function with the model's arguments
        # and append the result so the model can use it on the next turn.
        tool_output = CLIENT_TOOLS[item.name](args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": tool_output,
        })

# Turn 2 — model produces the final answer using the tool result
final = client.responses.create(model=MODEL, input=input_list, tools=TOOLS)
print(final.output_text)

更多模式（串流、託管加客戶端工具、MCP 核準、故障排除），請參考 Supervisor API 用戶端函式呼叫技能。

步驟五：啟用追蹤

在請求主體中傳遞 trace_destination 以將追蹤從代理循環傳送到 Unity Catalog 資料表。每個請求都會產生一條追蹤，捕捉模型呼叫與工具執行的完整序列。如果你不設定 trace_destination，則不會留下任何痕跡。關於設定細節，請參閱 Unity 目錄中的「Store OpenTelemetry traces」。

使用 databricks-openai Python 用戶端，透過 extra_body 傳遞：

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  extra_body={
    "trace_destination": {
      "catalog_name": "<catalog>",
      "schema_name": "<schema>",
      "table_prefix": "<table-prefix>"
    }
  }
)

若要在 API 回應中直接回傳 trace，請在 "databricks_options": {"return_trace": True} 中傳遞 extra_body。

你也可以使用 MLflow 分散式追蹤，將應用程式碼與 Supervisor API 代理的追蹤合併成單一的端對端追蹤。使用 extra_headers 欄位來傳播追蹤上下文標頭：

import mlflow
from mlflow.tracing import get_tracing_context_headers_for_http_request

with mlflow.start_span("client-root") as root_span:
  root_span.set_inputs({"input": "Tell me about Databricks"})

  trace_headers = get_tracing_context_headers_for_http_request()

  response = client.responses.create(
    model="databricks-claude-sonnet-4-5",
    input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
    tools=[...],
    extra_body={
      "trace_destination": {
        "catalog_name": "<catalog>",
        "schema_name": "<schema>",
        "table_prefix": "<table-prefix>"
      }
    },
    extra_headers=trace_headers,
  )

背景模式

背景模式讓你能執行長期執行包含多個工具呼叫和複雜推理的代理工作流程，而不必等待它們同步完成。提交你的請求 background=True，立即收到回應 ID，並在結果準備好時投票。這對於查詢多個資料來源或串接多個工具在同一請求中的代理特別有用。

建立背景請求

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  background=True,
)

print(response.id)     # Use this ID to poll for the result
print(response.status) # "queued" or "in_progress"

選舉結果的民調

使用 responses.retrieve() 來檢查狀態直到達到終端狀態：

from time import sleep

while response.status in {"queued", "in_progress"}:
  sleep(2)
  response = client.responses.retrieve(response.id)

print(response.output_text)

MCP 背景模式

為了安全起見，Supervisor API 在背景模式下執行任何 MCP 工具呼叫前，需明確獲得使用者的批准。當代理迴圈選擇 MCP 工具時，會以 mcp_approval_request 完成回應。你可以檢視工具名稱、伺服器標籤，以及模型打算傳遞的參數：

{
  "type": "mcp_approval_request",
  "id": "<tool-call-id>",
  "arguments": "{\"query\": \"what is Databricks\", \"count\": 5}",
  "name": "you-search",
  "server_label": "<server-label>",
  "status": "completed"
}

要批准工具呼叫並繼續代理迴圈，請在 mcp_approval_response 欄位回傳 input，其內含完整的對話歷史。

{
  "type": "mcp_approval_response",
  "id": "<tool-call-id>",
  "approval_request_id": "<tool-call-id>",
  "approve": true
}

Note

背景模式的回應在資料庫中最多保留30天。

支援工具

你在請求的陣列中定義工具 tools 。每個工具物件共享三個頂層欄位：

type （字串，必填）：選擇工具類型的判別器。
name （字串，選用）：顯示給模型的名稱。
description （字串，選用）：提示模型何時呼叫此工具。

此外，每個工具物件都攜帶一個巢狀配置物件，其鍵值與該 type 值相符。下表說明了每種支援工具類型的巢狀配置。

工具類型	範例	Scope
`genie_space`	`{` `"type": "genie_space",` `"name": "Customer reviews",` `"genie_space": {` `"space_id": "<id>"` `}` `}`	`genie`
`dashboard`	`{` `"type": "dashboard",` `"name": "Sales dashboard",` `"dashboard": {` `"dashboard_id": "<id>"` `}` `}`	`dashboards`
`uc_function`	`{` `"type": "uc_function",` `"name": "Flag urgent review",` `"uc_function": {` `"name": "<catalog>.<schema>.<function>"` `}` `}`	`unity-catalog`
`table`	`{` `"type": "table",` `"name": "Customer reviews",` `"table": {` `"name": "<catalog>.<schema>.<table_name>"` `}` `}`	`unity-catalog`
`knowledge_assistant`	`{` `"type": "knowledge_assistant",` `"name": "Internal docs",` `"knowledge_assistant": {` `"knowledge_assistant_id": "<id>"` `}` `}`	`model-serving`
`serving_endpoint`	`{` `"type": "serving_endpoint",` `"name": "Custom agent",` `"serving_endpoint": {` `"name": "<endpoint-name>"` `}` `}`	`model-serving`
`databricks_web_search`	`{` `"type": "databricks_web_search",` `"name": "Web search",` `"web_search": {}` `}`	`model-serving`
`vector_search_index`	`{` `"type": "vector_search_index",` `"name": "Product docs",` `"vector_search_index": {` `"name": "<catalog>.<schema>.<index>",` `"columns": ["title", "content"]` `}` `}`	`vector-search`
`volume`	`{` `"type": "volume",` `"volume": {` `"name": "<catalog>.<schema>.<volume>",` `"description": "Searches files in a Unity Catalog volume"` `}` `}`	`unity-catalog`
`app`	`{` `"type": "app",` `"name": "Support agent",` `"app": {` `"name": "<app-name>"` `}` `}`	`apps`
`uc_connection`	`{` `"type": "uc_connection",` `"name": "GitHub",` `"uc_connection": {` `"name": "system_ai_agent_github_mcp"` `}` `}`	`unity-catalog`
`uc_mcp`	`{` `"type": "uc_mcp",` `"name": "Slack",` `"uc_mcp": {` `"name": "<catalog>.<schema>.<mcp_service>"` `}` `}`	`ai-gateway`
`function`	`{` `"type": "function",` `"name": "get_weather",` `"description": "Get the current weather for a location.",` `"parameters": {` `"type": "object",` `"properties": { "location": { "type": "string" } },` `"required": ["location"]` `}` `}`	沒有

對於 serving_endpoint，僅支援 ResponseAgent、ChatCompletions 及 ChatAgent 端點。

對於 app，僅支援 MCP 應用程式（帶有 mcp- 前綴）以及自訂 ResponseAgent 應用程式（帶有 agent- 前綴）。

對於 uc_connection，請使用你為外部 MCP 伺服器建立的連線名稱，或系統 system_ai_agent_* 管理連接器（參見步驟 3（可選）：連接系統管理連線的第三方服務）。應用程式上的自訂 MCP 伺服器不被支援。

程式碼執行

當請求需要計算時，主管會在沙盒無伺服器計算會話中執行模型生成的程式碼，以分析資料、轉換檔案或執行計算。它支援 Python（預設）、SQL 及 shell 指令。主管會在需要時自行撰寫並執行程式碼，因此你不需要啟用、設定或提供程式碼。

程式碼會在受限的沙盒環境中執行，具備以下條件：

沒有網路連線。 它會阻擋所有外出網路，不論你工作區的網路政策如何，所以沙盒中執行的程式碼無法連到外部端點。
僅限 Azure Databricks 的範圍限定存取權限。 它本身沒有資料存取權限。它可以讀取你在同一請求中用 table 工具宣告的 Unity 目錄資料表。

支援的參數

每個對監督 API 的請求都接受以下參數。

model：以下支援的型號之一。將此欄位改為切換供應商，且不更改程式碼的其他部分。
- 克勞德俳句-4.5 （databricks-claude-haiku-4-5）
- 克勞德作品-4.1 （databricks-claude-opus-4-1）
- 克勞德作品-4.5 （databricks-claude-opus-4-5）
- 克勞德作品-4.6databricks-claude-opus-4-6 （）
- 克勞德十四行詩第四號（databricks-claude-sonnet-4）
- 克勞德十四行詩-4.5databricks-claude-sonnet-4-5（）
- Claude-Sonnet-4.6 （databricks-claude-sonnet-4-6）

input：發送對話訊息。
tools：代管工具定義（genie_space、dashboard、uc_function、table、knowledge_assistant、serving_endpoint、databricks_web_search、vector_search_index、volume、app、uc_connection、uc_mcp）以及用戶端函式工具（function）。請參見步驟 4（可選）：新增客戶端功能工具。
instructions：一個系統提示，用來引導主管的行為。
stream：設 true 為串流回應。
background：設為以 true 非同步執行請求。回傳一個回應 ID，您使用 responses.retrieve() 來輪詢該 ID。詳見背景模式。
trace_destination：具有 catalog_name、schema_name 和 table_prefix 欄位的可選物件。設定後，Supervisor API 會將完整代理迴圈的追蹤寫入指定的 Unity 目錄資料表。透過Python客戶端的 extra_body 傳遞。

API 不支援推論參數，例如 temperature。伺服器內部管理這些資料。

Authorization

Supervisor API 會以呼叫者的憑證執行代理迴圈，因此它所呼叫的工具會尊重呼叫者的 Unity Catalog 權限。當你直接呼叫 API 時， DatabricksOpenAI 客戶端會以你的身份進行認證。

當你從 Azure Databricks 應用程式呼叫 Supervisor API 時，你可以以應用程式的服務主體（應用程式授權）或請求使用者（使用者授權）身份執行工具。若要進行應用程式授權，請在每個工具上將權限授與該應用程式的服務主體。使用者授權時，將使用者的權杖轉發給 DatabricksOpenAI 用戶端，並新增所需的使用者授權範圍。請將執行工具視為請求使用者。

Limitations

監控器 API 有以下限制：

背景模式執行時間：背景模式請求的最大執行時間為 30 分鐘。
背景串流模式： stream 和 background 不可能同時出現 true 在同一個請求裡。
持久執行：不支援自動恢復失敗或中斷的狀態，也不支援代理迴圈的精確一次執行保證。

Web 搜尋工作區適用資格：Azure 不支援原生 databricks_web_search。包含內容 databricks_web_search 的請求會被拒絕。

其他資源

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-14

監督 API（測試版）

Requirements

步驟 1：創建單次 LLM 呼叫

步驟 2：新增託管工具以執行代理迴圈

步驟 3（可選）：連接系統管理連線的第三方服務

用戶對電腦 （U2M） 驗證

步驟 4（可選）：新增客戶端功能工具

步驟五：啟用追蹤

背景模式

建立背景請求

選舉結果的民調

MCP 背景模式

支援工具

程式碼執行

支援的參數

Authorization

Limitations

其他資源

意見反應

其他資源

用戶對電腦（U2M）驗證