Agent Bricks CLI

Important

此功能在 Beta 版中。启用它不需要工作区设置。安装 Agent Bricks CLI 即可开始使用。

Agent Bricks CLI（databricks-agentbricks）是 Azure Databricks 为开发者构建和部署自定义代理的 Commandline 工具。

Agent Bricks CLI 是一条以代码为先的路径，用于从终端构建自定义代理。 Agent Bricks CLI 基于 Databricks 最佳实践，利用内置框架构建项目架构。然后它可以在本地运行项目进行测试，并部署到 Azure Databricks 代理运行时。 CLI使你能够从空目录切换到已部署的代理，而无需手动布线运行时、工具、内存和管理资源。关于构建自定义代理的其他方法，包括基于应用的工作流程，请参见使用遗留代理服务器在 Databricks Apps 上运行代理。

先决条件

Databricks 的 CLI 已安装并可访问您的路径。
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 生命周期：init、dev 和 deploy 阶段及其各自的关键操作

注释

你也可以随时添加工具，绑定内存和会话存储，而不仅仅是在初始化阶段。在这些步骤之间使用 agentbricks tools add、 agentbricks memory bind和 agentbricks sessions bind 来更新你的代理配置。

Agent Bricks CLI 功能

能力	Description
模型访问	Agent Bricks CLI 会自动配置模型访问，使您的代理可以调用由 Azure Databricks 服务的模型，而无需管理凭据或端点。请参阅 Databricks 基础模型 API。
托管内存	智能体可以写入和搜索的长期记忆，按主体分区，并由托管存储支持。使用记忆功能在不同会话之间持续保存事实和偏好。请参阅托管代理内存。
管理式会议	保存在托管会话存储中并按主体分区的对话记录，支持将会话分叉为独立副本。参见托管代理会话。
Tools	在 `agent.toml` 中声明的 Azure Databricks 管理的功能：范围受限的 Unity Catalog 沙箱、Azure Databricks 管理的 MCP 服务或 Unity Catalog 函数。自定义 Python 工具直接写入项目代码。参见MCPs。
跟踪	默认启用的 MLflow 追踪会将每次运行的追踪数据发送到每个项目对应的 MLflow 实验中，以便进行调试和监控。详见追踪概述。
Deployment	将代理部署到 Azure Databricks 代理运行时，授予代理的服务主体访问绑定存储，并管理部署生命周期。

创建一个新的智能体

步骤1：使用 OAuth 认证并保存个人资料

Agent Bricks CLI 使用 Databricks CLI 认证。用OAuth（用户对机器）认证你的工作区，并将凭证保存为命名配置文件。

要启动OAuth流程，请执行以下操作，将主机替换为你的工作区URL。该命令会打开浏览器完成登录，然后将配置文件写入 ~/.databrickscfg：

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

要将该配置文件设置为CLI默认设置，以便后续命令可以省略 --profile，请执行以下操作：

agentbricks login --profile <profile>

agentbricks login 验证配置文件的凭据。如果缺少或被拒绝，CLI会重新运行 databricks auth login 并重试。

步骤2：搭建代理项目支架

搭建一个新的代理项目，然后通过 --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。

步骤5：本地运行代理

在部署前先在你的机器上运行该代理进行测试。

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。打开该URL与你的实时代理交互，该代理会自动连接到Azure Databricks模型服务。要管理后续部署，可以使用 agentbricks deployments 命令，如 agentbricks deployments logs 和 agentbricks deployments stop。

带来现有智能体

如果你已经使用 LangGraph 或 OpenAI Agents SDK 构建了智能体，请使用 --existing 标志将其移动到 Agent Bricks CLI 和 DurableAgentServer。 CLI不会重写你的代码。相反，它准备迁移指令，由编码代理（如 Claude Code 或 Codex）执行以将该项目迁移。

步骤1：准备迁移

从智能体的项目目录，准备迁移。传递智能体使用的框架：用于 LangGraph 的 langgraph，或用于 OpenAI Agents SDK 的 openai。

agentbricks init --framework langgraph --existing .

CLI 会创建一个 agent-bricks-migrate/ 目录，其中包含迁移指令、编码代理的提示，以及由 CLI 模板生成的参考项目。它还在 .claude/skills/ 和 .agent/skills/ 中添加技能，将编码智能体指向说明。该命令不会更改你的应用代码、依赖或 .env 文件，也不会在工作区中创建任何资源。

步骤2：用你的代码智能体转换项目

将提示从 agent-bricks-migrate/ 粘贴到你的编码智能体中。编码代理将项目转换为使用 agent.toml 和一个 DurableAgentServer 入口点，并验证转换结果。

步骤3：检查转换

在项目目录中运行 agentbricks doctor ：

agentbricks doctor .

agentbricks doctor在不运行代码或联系 Azure Databricks 的情况下检查项目文件。当项目具有有效的 agent.toml，使用调用处理程序启动 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 Calendar和Microsoft 365，每位用户在首次调用前需完成一次性OAuth登录。参见连接的应用程序。

要查看或移除工具，运行 agentbricks tools list 或 agentbricks tools remove mcp <service>。

有关其他工具，请参见以下页面：

所有内置服务及其功能： Databricks提供的MCP。
你自己的外部 MCP 服务器：外部MCP服务器。
Unity Catalog 作为工具：使用 Unity Catalog 函数创建代理工具。
单个特选的 Genie 智能体：Genie 智能体 MCP 服务器（旧版）。

`agent.toml` 参考

agent.toml 是你智能体使用的 Azure Databricks 托管资源的声明性事实来源。 agentbricks init 创建它、 agentbricks tools add、 agentbricks memory bind、 agentbricks sessions bind并 agentbricks tracing bind 更新它，并 agentbricks deploy 读取它以配置资源并授予访问权限。你也可以直接编辑它。

部分或字段	Description
`schema_version`	`agent.toml` 格式的版本。生成项目使用 `1`。
`[agent]` `framework`	框架模板： `langgraph` 或 `openai`。
`[agent]` `server`	代理服务器程序：`agentbricks` 用于 `DurableAgentServer`，或 `custom` 用于你自己的服务器。
`[memory_store]` `name`	代理使用的托管内存存储。
`[session_store]` `name`	代理使用的托管会话存储。
`[tracing]` `experiment_name`	用于跟踪的 MLflow 实验。删除该部分以关闭跟踪。
`[[tools]]`	工具绑定。每个工具都有一个 `id`，一个`user`值为`auth`或`app`，以及一个用于标识该工具的`source`，外加一个可选的`policy`。
`[auth.user]`	为你用代码编写的工具请求用户授权：`required` 和 `additional_api_scopes`。参见请求用户授权。

以下示例是 my-agent 为名为 agentbricks init 的 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 Catalog 函数的工具使用 auth = "app"，并且仅支持 source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" }。

命令参考

有关完整的最新命令参考（包括所有命令和标志选项），请参见 GitHub 上的 Agent Bricks CLI README。

其他资源

代理工具和MCP服务： MCP。
托管代理内存概念与API：托管代理内存。
托管代理会话概念与API：托管代理会话。
MLflow 代理追踪：跟踪概述。

反馈

此页面是否有帮助？

上次更新时间为 2026-10-12

Agent Bricks CLI

先决条件

Agent Bricks CLI 生命周期

Agent Bricks CLI 功能

创建一个新的智能体

步骤1：使用 OAuth 认证并保存个人资料

步骤2：搭建代理项目支架

步骤3：附加托管会话和内存存储

步骤 4：查看跟踪

步骤5：本地运行代理

步骤6：部署代理

带来现有智能体

步骤1：准备迁移

步骤2：用你的代码智能体转换项目

步骤3：检查转换

第四步：清理、运行和部署

Considerations

添加MCP工具

agent.toml 参考

命令参考

其他资源

反馈

其他资源

`agent.toml` 参考