撰寫一個 AI 代理並部署到 Databricks 應用程式上

建立一個 AI 代理，並使用 Databricks 應用程式部署。 Databricks Apps 讓你完全掌控代理程式碼、伺服器設定和部署工作流程。當你需要自訂伺服器行為、基於 git 的版本管理或本地 IDE 開發時，這種方法非常適合。

小提示

如果你的代理只使用Azure Databricks託管工具，且不需要工具呼叫間自訂邏輯，你可以使用 Supervisor API （Beta）讓Azure Databricks幫你管理代理迴圈。

客服聊天介面預覽

每個對話客服範本都內建聊天介面（如上圖），無需額外設定。聊天介面支援串流回應、標記顯示、Databricks 認證，以及可選的持久聊天歷史。

要求

在您的工作區啟用 Databricks 應用程式。請參閱設定 Databricks Apps 工作區和開發環境。

第一步。複製代理人應用程式範本

請使用來自 Databricks 應用程式範本庫的預先建置代理範本開始。

本教學使用範本 agent-openai-agents-sdk ，內容包括：

使用 OpenAI 代理 SDK 建立的代理程式
一個代理應用程式的起始程式碼，具備對話式 REST API 與互動式聊天介面
使用 MLflow 評估代理的程式碼

請選擇以下路徑之一來設置範本：

工作區 UI（使用者介面）

用 Workspace 介面安裝應用程式範本。這會安裝應用程式並將它部署到你工作空間中的運算資源。接著你可以將應用程式檔案同步到本地環境進行進一步開發。

在你的 Databricks 工作區，點選 + 新>應用程式。
點擊 Agents>自訂代理程式（OpenAI SDK）。
建立一個新的 MLflow 實驗，並用這個名稱 openai-agents-template 完成剩下的設定來安裝範本。
建立應用程式後，點擊應用程式網址即可開啟聊天介面。

建立應用程式後，請將原始碼下載到本地電腦以進行自訂：

複製第一個指令，在「同步檔案」裡
在本地終端機執行複製的指令。

從 GitHub 複製

要從本地環境開始，先克隆代理範本庫並開啟目錄：agent-openai-agents-sdk

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

步驟 2。了解代理應用程式

代理範本展示了具備這些關鍵元件的生產準備架構。請開啟以下章節以了解更多關於每個元件的詳細資訊：

應用程式代理簡易圖

請開啟以下章節以了解更多關於每個元件的詳細資訊：

內建聊天介面

代理範本會自動擷取並執行聊天應用程式範本作為前端。這個聊天介面會綁定在同一個 Databricks 應用程式部署中，並與你的代理一起提供，因此不需要額外的設定。

你可以直接在專案中自訂聊天介面。欲了解更多聊天應用程式的功能細節，包括如何啟用持久聊天紀錄及用戶回饋收集，請參閱「與 Databricks 應用程式建立並分享聊天介面」。

MLflow 代理伺服器

一個非同步的 FastAPI 伺服器，能處理代理請求，內建追蹤與可觀察功能。 AgentServer 提供/responses查詢代理的端點，並自動管理請求路由、日誌記錄及錯誤處理。

ResponsesAgent介面

Databricks 建議 MLflow ResponsesAgent 來建立代理程式。 ResponsesAgent 可讓您使用任何第三方架構建置代理程式，然後將它與 Databricks AI 功能整合，以取得健全的記錄、追蹤、評估、部署和監視功能。

ResponsesAgent 可輕鬆地包裝現有的代理程式，以取得 Databricks 相容性。

想了解如何建立一個ResponsesAgent，請參考MLflow 文檔——ResponsesAgent for Model Serving中的範例。

ResponsesAgent 提供下列優點：

進階代理程式功能
- 多代理支援
- 串流輸出：以較小的區塊串流輸出。
- 完整的工具通話訊息歷程記錄：傳回多個訊息，包括中繼工具通話訊息，以改善品質和交談管理。
- 工具通話確認支援
- 持續運行工具的支援
簡化的開發、部署和監視
- 使用任何架構撰寫代理程式：使用ResponsesAgent 介面包裝任何現有的代理程式，以取得與 AI 遊樂場、代理程式評估及代理程式監視的現用相容性。
- Typed authoring interfaces：使用型別化的 Python 類別撰寫代理程式，並可利用 IDE 與筆記本自動補全功能。
- 自動追蹤：MLflow 自動將串流回應匯聚成追蹤，方便評估與顯示。
- 與 OpenAI Responses 架構相容：請參見 OpenAI：回應與 ChatCompletion 的比較。

OpenAI 代理程式 SDK

該範本使用 OpenAI Agents SDK 作為對話管理與工具編排的代理框架。你可以用任何框架來撰寫代理。關鍵是用 MLflow ResponsesAgent 介面包裝你的代理。

MCP（模型上下文協定）伺服器

該範本連接至 Databricks MCP 伺服器，讓代理人員存取工具與資料來源。請參閱 Databricks 上的模型內容通訊協定（MCP）。

作者代理人使用 AI 編碼助理

Databricks 建議使用 AI 程式助理，例如 Claude、Cursor 和 Copilot，來撰寫代理。使用提供的代理技能，/.claude/skills 以及 AGENTS.md 檔案，協助 AI 助理了解專案結構、可用工具及最佳實務。代理程式可以自動讀取這些檔案，以開發並部署 Databricks 應用程式。

步驟 3。為你的經紀人新增工具

讓你的代理程式具備查詢資料庫、文件搜尋或呼叫外部 API 的能力，並透過連接 MCP 伺服器。代理範本包含預設的 MCP 伺服器連線。若要新增更多工具，請在代理程式中設定額外的 MCP 伺服器，並在中授予所需權限 databricks.yml。

請參閱 AI 代理工具以了解支援的工具類型與程式碼範例。

定義局部Python函數工具

對於不需要外部資料來源或 API 的操作，直接在你的代理程式碼中定義工具。這些工具與您的代理程式相同，對資料轉換、計算或公用運算非常有用。

OpenAI 智能代理 SDK

使用來自 OpenAI Agents SDK 的@function_tool 裝飾器：

from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

LangGraph

使用 @tool LangChain 的裝飾器

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

@tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

本地函式工具不需要資源授權 databricks.yml ，因為它們是在代理程序中執行的。

步驟四。用 Unity AI Gateway 來管理 Databricks 應用程式中的代理對 LLM 的使用情況

將你的代理的大型語言模型通話路由到 AI 閘道器（Beta），讓每個請求都受到相同的控制，不論是哪個提供者回應。當閘道在請求路徑中時，你可以集中權限、設定每個應用程式的費用、交換模型，並在不修改代理代碼或輪換提供者憑證的情況下檢查或重播流量。

Important

這項功能位於測試版 (Beta) 中。工作區管理員可以從 「預覽 」頁面控制對此功能的存取。請參閱管理 Azure Databricks 預覽。

在您的工作區啟用 AI 閘道。 AI Gateway 在測試階段需要用戶選擇加入。帳號管理員必須先從帳號主控台 的預覽 頁面開啟此功能，才能建立或查詢閘道端點。請參閱管理 Azure Databricks 預覽。

將你的代理程式指向 AI 閘道介面端點。在你的代理程式碼中，將 AI Gateway 端點名稱作為 model 參數傳遞，並在 Azure Databricks LLM 用戶端設定 use_ai_gateway=True。用戶端會自動將流量導向閘道器並處理認證。

OpenAI

from agents import Agent, set_default_openai_api, set_default_openai_client
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
set_default_openai_api("chat_completions")

agent = Agent(
    name="Agent",
    instructions="You are a helpful assistant.",
    model="<ai-gateway-endpoint>",
)

LangGraph

from databricks_langchain import ChatDatabricks

llm = ChatDatabricks(
    model="<ai-gateway-endpoint>",
    use_ai_gateway=True,
)

如需更多 API 表面（OpenAI 回應 API、Anthropic Messages API、Google Gemini）及 REST 範例，請參見 Query Unity AI Gateway endpoints。

進階編輯主題

串流回應

串流可讓代理程式以即時區塊傳送回應，而不是等候完整的回應。若要使用 ResponsesAgent實作串流，請發送一系列增量事件，再發送最終完成事件。

發出差異事件：以相同的output_text.delta方式傳送多個item_id事件，以即時串流文字區塊。
完成事件：傳送與包含完整最終輸出文字之增量事件相同的response.output_item.done最終item_id事件。

每個增量事件會將一段文字資料串流至用戶端。最終完成的事件包含完整的回應文字，並指示 Databricks 執行下列動作：

使用 MLflow 追蹤功能來記錄代理程式的輸出
在 AI 閘道推斷數據表中匯總串流回應
在 AI 遊樂場 UI 中顯示完整的輸出

串流錯誤傳播

馬賽克 AI 會傳播串流時所遇到的任何錯誤，其下 databricks_output.error是最後一個令牌。呼叫客戶端有責任正確處理並顯示此錯誤。

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}

自訂輸入與輸出

某些案例可能需要額外的代理程式輸入，例如 client_type 和 session_id，或擷取來源鏈接等輸出，這些來源鏈接不應該包含在聊天記錄中以供日後互動。

在這些案例中，MLflow ResponsesAgent 原生支援字段 custom_inputs 和 custom_outputs。你可以透過 request.custom_inputs 上述框架範例存取自訂輸入。

代理程式評估檢閱應用程式不支援顯示具有其他輸入欄位的代理程式的追蹤。

在 AI Playground 和評論應用程式中提供custom_inputs

如果您的代理程式使用 custom_inputs 字段接受其他輸入，您可以在 AI 遊樂場和檢閱應用程式中手動提供這些輸入。

在 AI 遊樂場或代理程式檢閱應用程式中，選取齒輪圖示。
啟用 custom_inputs。
提供符合代理程式所定義輸入架構的 JSON 物件。

步驟 5. 在本地執行代理應用程式

建立你的在地環境：

安裝 uv（Python套件管理器）、nvm（Node 版本管理器）以及 Databricks CLI：
- uv 安裝
- nvm 安裝
- 執行以下步驟以使用 Node 20 LTS：
```
nvm use 20
```
- databricks CLI 安裝
把資料夾改成資料夾 agent-openai-agents-sdk 。
執行提供的快速啟動腳本來安裝相依性、設定環境，然後啟動應用程式。
```
uv run quickstart
uv run start-app
```

在瀏覽器中，打開 http://localhost:8000 內建的聊天介面，開始與客服人員聊天。

步驟 6。設定驗證

你的代理程式需要認證才能存取 Azure Databricks 資源。 Databricks Apps 提供兩種認證方法：應用程式授權（服務主體）與使用者授權（代表使用者授權）。你可以透過工作區介面配置任何一種，或者在 databricks.yml 中使用宣告式自動化套件來以宣告方式配置。代理範本會附帶一個 databricks.yml，所以當你從範本開始時，這條路徑是預設的。

完整參考資料，包括所有支援的資源類型、權限值及端對端完整操作指南databricks.yml，請參見AI 代理的身份驗證。

應用程式授權（預設）

應用程式授權使用一個服務主體，Azure Databricks 會自動為你的應用程式建立。所有使用者共享相同的權限。

在resources.apps.<app>.resources中的databricks.yml下宣告代理使用的每一個資源。部署套件以授予服務主體宣告的權限：

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

完整資源類型清單請參閱應用程式授權。

使用者授權

使用者授權讓你的代理程式根據每位使用者的個別權限來行動。當你需要每個使用者的存取控制或稽核追蹤時，可以使用這個功能。

將此代碼加入到您的程式代理中：

from agent_server.utils import get_user_workspace_client

# In your agent code (inside @invoke or @stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Important

在你的 get_user_workspace_client() 或 @invoke 函式中初始化 @stream，而不是在應用程式啟動時。使用者憑證僅在處理請求時存在。

在應用程式的 Azure Databricksuser_api_scopes 中，新增 databricks.yml 下的範圍，配置代理可以代表使用者呼叫哪些 API：

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

有關可用範圍清單及完整設定說明，請參閱使用者授權。

步驟 7。評估代理人

範本包含代理人評估程式碼。如需相關資訊，請參閱 agent_server/evaluate_agent.py 。請透過終端機執行以下程序來評估您的客服人員回應的相關性與安全性：

uv run agent-evaluate

步驟 8. 將代理部署到 Databricks 應用程式

設定好驗證後，將代理部署到 Azure Databricks。代理範本使用 Databricks 資產套件（DAB）來部署。 databricks.yml範本中的檔案定義了應用程式的設定與資源權限。確保你已經安裝並設定好 Databricks 的 CLI 。

提示

如果你是在步驟 1 透過 Workspace UI 建立應用程式，請在部署前執行 databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve ，將現有應用程式綁定到你的套件中。否則， databricks bundle deploy 會失敗，因為「已有同名應用程式存在」。

在部署前驗證套件組設定以捕捉錯誤：
```
databricks bundle validate
```
部署套件。這會上傳程式碼並配置定義於 databricks.yml 的資源（MLflow 實驗、服務端點等）：
```
databricks bundle deploy
```
啟動或重新啟動應用程式：
```
databricks bundle run agent_openai_agents_sdk
```
提示

bundle deploy 只負責上傳檔案和設定資源。 bundle run 啟動或重新啟動應用程式時，必須使用新程式碼。

未來更新時，先執行 databricks bundle deploy 再 databricks bundle run agent_openai_agents_sdk 重新部署。

步驟 9. 查詢已部署代理

以下範例使用了使用 OAuth 標記的快速 curl 請求。 Databricks 應用程式不支援個人存取權杖（PAT）。

欲了解完整的查詢方法清單，包括 Databricks OpenAI 用戶端與 REST API，請參見查詢部署在 Azure Databricks 上的代理程式。

使用 Databricks CLI 產生 OAuth 代幣：

databricks auth login --host <https://host.databricks.com>
databricks auth token

使用該令牌查詢代理人：

curl -X POST <app-url.databricksapps.com>/responses \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

局限性

僅支援中大型運算規模。請參見「為 Databricks 應用程式配置運算資源」。
MLflow Review App 聊天介面目前不支援部署在 Databricks Apps 上的代理程式。為了評估現有的追蹤記錄，可以使用標籤會話，無論部署方式如何，它們都能正常運作。 Databricks 正在直接將審查與回饋支援整合進聊天機器人範本中。

下一步

負載測試你的 Databricks Apps 代理程式

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-05-03

撰寫一個 AI 代理並部署到 Databricks 應用程式上

要求

第一步。 複製代理人應用程式範本

工作區 UI（使用者介面）

從 GitHub 複製

步驟 2。 了解代理應用程式

作者代理人使用 AI 編碼助理

步驟 3。 為你的經紀人新增工具

定義局部Python函數工具

OpenAI 智能代理 SDK

LangGraph

步驟四。 用 Unity AI Gateway 來管理 Databricks 應用程式中的代理對 LLM 的使用情況

OpenAI

LangGraph

進階編輯主題

串流回應

自訂輸入與輸出

步驟 5. 在本地執行代理應用程式

步驟 6。 設定驗證

應用程式授權（預設）

使用者授權

步驟 7。 評估代理人

步驟 8. 將代理部署到 Databricks 應用程式

步驟 9. 查詢已部署代理

局限性

下一步

意見反應

其他資源

第一步。複製代理人應用程式範本

步驟 2。了解代理應用程式

步驟 3。為你的經紀人新增工具

步驟四。用 Unity AI Gateway 來管理 Databricks 應用程式中的代理對 LLM 的使用情況

步驟 6。設定驗證

步驟 7。評估代理人