Agent Bricks CLI

Agent Bricks CLI （databricks-agentbricks） 是 Azure Databricks 的命令列工具，專為開發者設計自訂代理程式而設。

Agent Bricks CLI 是一條以程式碼為優先的路徑，用於從終端建置自訂代理。 Agent Bricks CLI 利用基於 Databricks 最佳實務的內建框架，構建專案架構。 接著它可以在本地執行專案進行測試，並部署到 Azure Databricks 代理執行環境。 CLI 讓你能從空白目錄切換到已部署的代理程式，而不必手動布線執行時、工具、記憶體和管理資源。 關於建立自訂代理的其他方法，包括基於應用程式的工作流程，請參見 「使用舊版代理伺服器在 Databricks 應用程式上執行代理」。

先決條件

• Databricks CLI 已安裝，且可在您的 PATH 中使用。

• Python 3.10 或以上版本，且 pip。

• 安裝 Agent Bricks CLI：

  pip install databricks-agentbricks
  

Agent Bricks CLI 生命週期

Agent Bricks CLI 會根據框架範本建立一個包含可部署代理程式碼的本機目錄，且已預先串接好執行階段、測試，以及可選用的聊天介面。 你寫應用程式邏輯（模型、工具和提示），CLI 負責本地執行並部署到 Azure Databricks 基礎架構。

agent.toml是所有 Azure Databricks 管理資源的宣告真實來源，這些資源由您的代理依賴：工具綁定（資料沙盒、受管理的模型情境協定（MCP）服務、Unity 目錄函式）以及記憶體、會話和追蹤資源。 agentbricks deploy 它讀取檔案來配置並接線，所以部署的是檔案，而不是手寫的設定程式碼。

將代理從空白目錄帶到生產環境的三個指令：

• agentbricks init 會根據隨附的範本建立專案骨架，並可選擇在 .env 檔案中預先填入 Databricks 設定檔，讓專案可立即執行。
• agentbricks dev會在本機針對 Azure Databricks 模型服務執行代理程式，讓你可以在部署前先進行測試。
• agentbricks deploy配置已宣告的agent.toml資源，並將代理推送至 Azure Databricks 代理執行環境。

Agent Bricks CLI 功能

建立一個新的代理程式

步驟 1：使用 OAuth 認證並儲存個人資料

Agent Bricks CLI 採用 Databricks CLI 認證。 用 OAuth（使用者對機器）驗證你的工作區，並將憑證存為命名設定檔。

要啟動 OAuth 流程，執行以下操作，將主機替換成你的工作區網址。 此指令會開啟瀏覽器完成登入，然後將個人檔案寫入：~/.databrickscfg

databricks auth login --host https://<your-workspace-url> --profile <profile>

若要將該設定檔設為 CLI 的預設值，以便後續指令可以省略 --profile，執行以下操作：

agentbricks login --profile <profile>

agentbricks login 驗證個人資料的憑證。 如果這些項目缺失或遭拒絕，CLI 會重新執行 databricks auth login 並重試。

步驟二：搭建代理專案架構

建立新的代理程式專案，並傳入 --framework 來選擇範本。 此範例使用 LangGraph 範本，其中包含一個瀏覽器聊天應用程式：

agentbricks init --framework langgraph my-agent
cd my-agent

CLI 針對每個框架都隨附一個範本，而 --framework 用來選擇要以哪個範本產生專案架構：langgraph 用於 LangGraph，或 openai 用於 OpenAI Agents SDK。 CLI 會將專案的管理資源與工具綁定寫入 agent.toml ，並將範本來源寫入 .agentbricks/project.toml。 若要在沒有聊天應用程式的情況下，支撐僅支援 API 的後端，請加入 --disable-chat-app。

步驟 3：附加受管理的會話與記憶體儲存

綁定管理的儲存庫，讓你的客服人員能持續保留對話紀錄和長期記憶。 每個指令都會記錄商店 agent.toml 名稱，如果不存在，則建立該商店名稱。

要綁定會話儲存與記憶體儲存，請執行以下操作：

agentbricks sessions bind my-agent-sessions
agentbricks memory bind my-agent-memory

步驟 4：查看追蹤

追蹤預設是開啟的。 agentbricks init 會繫結預設的 /Shared/agentbricks_traces/<project> MLflow 實驗，而 agentbricks dev 和 agentbricks deploy 會將每次執行的追蹤傳送至該實驗。

若要在您的代理程式產生一些追蹤資料後列出這些追蹤資料，請執行下列命令：

agentbricks tracing list

要綁定特定的 MLflow 實驗，執行 agentbricks tracing bind --experiment-id <experiment-id>。 要關閉追蹤，請執行 agentbricks tracing unbind。

步驟五：在本地執行代理

在部署前先在你的機器上執行代理測試。

agentbricks dev

這會啟動一個位於 8000 埠的本地伺服器，使用與 Azure Databricks 代理執行時相同的指令和環境。 Agent Bricks CLI 會將代理連接到 Azure Databricks 模型服務，讓它能在本地呼叫該模型。 該範本將預設模型設定為 MODEL 中的 agent/agent.py值。 要使用不同的模型，請編輯該數值。 將請求傳送至 http://localhost:8000 以與該代理程式互動。

步驟 6：部署代理

將代理部署到 Azure Databricks 代理執行時。 CLI 會佈建已繫結的儲存體，授與代理程式的服務主體其存取權限，並推出部署。 已部署的代理程式名稱為 agent-bricks-<name>。

agentbricks deploy my-agent

部署結束後，CLI 會回傳部署的 URL。 打開那個網址可以與你的 live agent 互動，該代理會自動連接到 Azure Databricks 模型服務。 若要管理部署，請使用 agentbricks deployments 指令，如 agentbricks deployments logs 和 agentbricks deployments stop。

引入現有的代理程式

如果你已經用 LangGraph 或 OpenAI Agents SDK 建置代理，請用該 --existing 標誌將其移到 Agent Bricks 的 CLI，並使用 DurableAgentServer。 CLI 不會重寫你的程式碼。 它會準備遷移指令，讓程式代理程式（如 Claude Code 或 Codex）執行以轉換專案。

步驟一：準備遷移

從代理程式的專案目錄中準備遷移。 傳入代理所使用的框架：langgraph 用於 LangGraph 或 openai 用於 OpenAI 代理 SDK。

agentbricks init --framework langgraph --existing .

CLI 會建立一個 agent-bricks-migrate/ 目錄，裡面包含遷移指令、你的程式代理程式提示，以及由 CLI 範本產生的參考專案。 它也會在 .claude/skills/ 和 .agent/skills/ 中加入技能，將編碼代理指向這些指示。 這個指令不會改變你的應用程式代碼、相依關係或 .env 檔案，也不會在你的工作區建立任何資源。

步驟二：與你的程式設計代理一起轉換專案

把提示從 agent-bricks-migrate/ 貼到你的程式設計代理裡。 程式代理會將專案轉換為使用 agent.toml 和 DurableAgentServer 進入點，並驗證轉換結果。

步驟三：檢查轉換

在專案目錄中執行 agentbricks doctor ：

agentbricks doctor .

agentbricks doctor在不執行程式碼或聯絡 Azure Databricks 的情況下檢查專案檔案。 當專案擁有有效的 agent.toml，從 invoke 處理器開始 DurableAgentServer，並呼叫其框架的介面卡時，即可成功。 失敗的報告表示轉換尚未完成。

步驟四：清理、執行並部署

刪除 agent-bricks-migrate/ 和指向它的兩個技能，並且把它們排除在你的提交中。 然後用 agentbricks dev 執行代理，並用 agentbricks deploy 部署它。

Considerations

• --existing 支援 LangGraph 及 OpenAI Agents SDK，並可搭配 DurableAgentServer。 它不支援 --server custom。
• 將代理切換到受管理的會話儲存並不會將其現有的對話紀錄移轉過去。 遷移指示會要求你決定如何處理之前的對話。
• --disable-chat-app、--memory-store 和 --session-store 選項決定了參考專案。 他們不會建立資源。

新增 MCP 工具

如果你用 Agent Bricks CLI 建置代理，請使用 agentbricks tools add mcp 將內建的 system.ai MCP 服務加入你的專案。 這個指令會檢查服務是否存在於你的工作區，並將工具記錄在 agent.toml。 代理程式會在執行時連接到工具，所以你不需要寫任何連線程式碼。

要列出可新增的 MCP 服務，請執行以下指令：

agentbricks tools list --kind mcp

以下範例新增了常見的內建服務：

# Answer analytics questions across your workspace with Genie One.
agentbricks tools add mcp system.ai.genie_one_mcp

# Run SQL on a SQL warehouse.
agentbricks tools add mcp system.ai.dbsql

# Connect to third-party applications.
agentbricks tools add mcp system.ai.slack
agentbricks tools add mcp system.ai.github

預設情況下，工具會以向你的代理程式傳送請求的使用者權限執行。 若要以應用程式的服務主體執行，請加上 --auth app。 對於 Google Drive、Gmail、Google 行事曆和 Microsoft 365，每位使用者在第一次呼叫前需完成一次性 OAuth 登入。 請參閱 已連結的應用程式。

要檢視或移除工具，請執行 agentbricks tools list 或 agentbricks tools remove mcp <service>。

其他工具請參考以下頁面：

• 所有內建服務及其功能： Databricks 提供的 MCP。
• 你自己的外部 MCP 伺服器：外部 MCP 伺服器。
• Unity Catalog 函式可作為工具：使用 Unity Catalog 函式建立代理工具。
• 一個精選的 Genie Agent：Genie Agent MCP 伺服器（舊版）。

agent.toml 參考資料

agent.toml是您的代理所使用的 Azure Databricks 管理資源的宣告式真實來源。 agentbricks init 建立它、agentbricks tools add、agentbricks memory bind、agentbricks sessions bind 和 agentbricks tracing bind 更新它，並由 agentbricks deploy 讀取它以配置資源並授與存取權限。 你也可以直接編輯。

以下範例是 agentbricks init 為名為 my-agent 的 LangGraph 代理產生的檔案：

schema_version = 1

[agent]
framework = "langgraph"
server = "agentbricks"

[memory_store]
name = "my-agent-memory"

[session_store]
name = "my-agent-session"

[tracing]
experiment_name = "/Shared/agentbricks_traces/my-agent"

以下範例展示了由 agentbricks tools add 寫入的工具綁定：內建的 MCP 服務、Genie 代理，以及一個聚焦於單一資料表的沙盒：

[[tools]]
id = "web_search"
auth = "user"
source = { kind = "mcp", service = "system.ai.web_search" }

[[tools]]
id = "genie_agent"
auth = "user"
source = { kind = "genie_agent", space_id = "<space-id>" }

[[tools]]
id = "sandbox"
auth = "user"
source = { kind = "sandbox", service = "system.ai.sandbox" }
policy = { downscope = [{ resource = "table:samples.nyctaxi.trips", permission = "read_only" }] }

呼叫 Unity 目錄函式的工具會使用 auth = "app"，且僅支援 source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" }。

命令說明

如需完整且最新的指令參考（包含所有指令與旗標），請參閱 GitHub 上的 Agent Bricks CLI README。

其他資源

• 代理工具與 MCP 服務： MCP。
• 管理代理記憶體概念與 API： 託管代理記憶體。
• 管理代理會話概念與API：管理代理會話。
• MLflow 代理追蹤： 追蹤概述。