Important
此功能在 Beta 版中。 启用它不需要工作区设置。 安装 Agent Bricks CLI 即可开始使用。
Agent Bricks CLI(databricks-agentbricks)是 Azure Databricks 为开发者构建和部署自定义代理的 Commandline 工具。
使用 Agent Bricks CLI 在代码中使用 LangGraph 或 OpenAI Agents SDK 模板编写自定义代理逻辑,并从终端部署。 要构建一个用于回答数据相关问题的无代码代理,请在 Azure Databricks 用户界面中使用 Genie 代理。 欲了解更多信息,请参阅 《什么是 Agent Bricks?》、《 Agent Bricks 常见问题解答》以及《 Agent Bricks 快速入门指南》。
Agent Bricks CLI 基于 Databricks 最佳实践,利用内置框架构建项目架构。 然后它可以在本地运行项目进行测试,并部署到 Azure Databricks 代理运行时。 CLI使你能够从空目录切换到已部署的代理,而无需手动布线运行时、工具、内存和管理资源。 关于构建自定义代理的其他方法,包括基于应用的工作流程,请参见 使用遗留代理服务器在 Databricks Apps 上运行代理。
先决条件
Databricks 的 CLI 已安装并可访问您的路径。
Python 3.11 或更高版本。 Agent Bricks CLI 包安装在 Python 3.10 上,但它生成的项目需要 Python 3.11 或更高版本。 Databricks 推荐使用 Python 3.12。
uv,用于运行agentbricks init、agentbricks dev和agentbricks deploy的脚手架项目。安装Agent Bricks CLI。 要将其安装为
uv工具,请运行以下操作:uv tool install databricks-agentbricks要改用
pip安装,请运行pip install databricks-agentbricks。 如果安装失败,请参见 故障排除。
概述:从登录到部署代理
以下流程总结了 创建新代理中的步骤:
databricks auth login --host "https://<your-workspace-url>" --profile my-workspace
agentbricks login --profile my-workspace
agentbricks init --framework langgraph my-agent
cd my-agent
agentbricks dev
agentbricks deploy my-agent
Tip
每个命令和命令组都支持 --help。 例如,运行 agentbricks memory --help 以列出内存命令及其标志。
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 代理运行时。
注释
你也可以随时添加工具,绑定内存和会话存储,而不仅仅是在初始化阶段。 在这些步骤之间使用 agentbricks tools add、 agentbricks memory bind和 agentbricks sessions bind 来更新你的代理配置。
Agent Bricks CLI 功能
| 能力 | Description |
|---|---|
| 模型访问 | Agent Bricks CLI 会自动配置模型访问,使您的代理可以调用由 Azure Databricks 服务的模型,而无需管理凭据或端点。 请参阅 Databricks 基础模型 API。 |
| 托管内存 | 智能体可以写入和搜索的长期记忆,按主体分区,并由托管存储支持。 使用内存跨会话保存事实和首选项,并使用 agentbricks memory pipeline 从会话存储中提取内存。 参见 Agent 内存 和 Agent 内存管道。 |
| 管理式会议 | 保存在托管会话存储中并按主体分区的对话记录,支持将会话分叉为独立副本。 参见 代理会话。 |
| Tools | 在 agent.toml 中声明的由 Azure Databricks 管理的功能:沙盒、由 Azure Databricks 管理的 MCP 服务,或 Unity Catalog 函数。 自定义 Python 工具直接写入项目代码。 参见MCPs。 |
| 跟踪 | 默认启用的 MLflow 追踪会将每次运行的追踪数据发送到每个项目对应的 MLflow 实验中,以便进行调试和监控。 详见 追踪概述。 |
| Deployment | 将代理部署到 Azure Databricks 代理运行时,授予代理的服务主体访问绑定存储,并管理部署生命周期。 |
创建一个新的智能体
步骤1:使用 OAuth 认证并保存个人资料
Agent Bricks CLI 使用 Databricks CLI 认证。 用OAuth(用户对机器)认证你的工作区,并将凭证保存为命名配置文件。 执行以下两个命令。
注释
配置文件是一组命名的连接设置(工作区URL及其凭证),存储在 ~/.databrickscfg。 本页示例使用名为 my-workspace的配置文件。 选择任意名称,然后用 --profile 传递。
要启动OAuth流程,请执行以下操作,将主机替换为你的工作区URL。 该命令会打开浏览器完成登录,然后将
my-workspace配置文件写入~/.databrickscfg:databricks auth login --host "https://<your-workspace-url>" --profile my-workspace要验证配置文件并将其保存为Agent Bricks的CLI默认设置,以便后续命令可以省略
--profile,请执行以下操作:agentbricks login --profile my-workspace如果配置文件的凭据缺失或被拒绝,
agentbricks login会重新运行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:附加托管会话和内存存储
使用托管存储库,智能体可以持久保存对话历史记录和长期记忆。
agentbricks init 在 agent.toml 中声明一个以项目命名的会话存储和内存存储,例如 my-agent-cuzvas-memory。
agentbricks deploy 创建缺失的存储并授予代理访问权限,因此大多数代理可以跳过这一步。
如果想用不同的存储,就按名称绑定。 每个命令都会替换 agent.toml 中的存储库名称。 它不会创建存储库。 要绑定名为 my-agent-sessions 的会话存储和名为 my-agent-memory的内存存储,执行以下操作:
agentbricks sessions bind my-agent-sessions
agentbricks memory bind my-agent-memory
要在存储中已有记忆条目的情况下启动代理,先创建存储并添加条目,再部署。 请参阅“开始使用代理内存”中的 Agent Bricks CLI 标签。
步骤 4:查看跟踪
追踪默认开启。
agentbricks init 绑定一个默认的 /Shared/agentbricks_traces/<project>-<suffix> 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 发送请求以与该代理交互。
注释
agentbricks dev 无法连接到内存或会话存储。 长期记忆失效,对话记录只会在本地服务器运行时持续。 即使存储库已绑定,聊天应用在本地记忆状态下依然显示未连接。 执行 agentbricks deploy 后记忆功能即可连接。
步骤6:部署代理
将代理部署到Azure Databricks代理运行时。 CLI 会预配已绑定的存储资源,授予该代理的服务主体对这些存储的访问权限,并执行部署。 已部署的代理名为 agent-bricks-<name>。
agentbricks deploy my-agent
部署结束后,CLI返回部署的URL。 打开该URL与你的实时代理交互,该代理会自动连接到Azure Databricks模型服务。 要管理后续部署,可以使用 agentbricks deployments 命令,如 agentbricks deployments logs 和 agentbricks deployments stop。
第一次部署需要几分钟,主要是启动应用的计算资源。 后期部署更快。 如果部署超时或URL无响应,请参见 部署超时或URL无响应。 关于 MCP_USER_AUTH_REQUIRED 调用已部署的代理时的错误,请参见 故障排除。
引入现有代理
如果你已经使用 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 <catalog>.<schema>.<service> 向你的项目添加 MCP 服务。 该命令接受你工作空间中任何你可以访问的MCP服务,包括其他目录和模式中的内置 system.ai 服务和MCP服务。 该命令会检查服务是否存在于你的工作区,并将工具记录在 agent.toml。 代理在运行时连接到工具,所以你不需要写任何连接代码。
要列出你可以添加的内置 system.ai MCP服务,请执行以下命令:
agentbricks tools list --kind mcp
要在另一个架构中列出 MCP 服务,运行 agentbricks tools list --kind mcp --schema <catalog>.<schema>。
以下示例添加了常见的内置服务:
# 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
要从其他目录和模式(如 外部 MCP 服务器)添加 MCP 服务,需传递其三部分名称。
--name 选项将工具的 ID 设置在 agent.toml 中:
agentbricks tools add mcp main.tools.ticket_search --name tickets
默认情况下,工具以向你的代理发送请求的用户权限运行。 如果要作为应用的服务主体运行,请添加 --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 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 读取它以配置资源并授予访问权限。 你也可以直接编辑它。
| 部分或字段 | 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-cuzvas-memory"
[session_store]
name = "my-agent-cuzvas-sessions"
[tracing]
experiment_name = "/Shared/agentbricks_traces/my-agent-cuzvas"
随机后缀(cuzvas 本例中)因项目而异,因此同名项目不会共享存储或实验。
以下示例展示了由 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" }
调用 Unity Catalog 函数的工具使用 auth = "app",并且仅支持 source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" }。
命令参考
下表列出了Agent Bricks的CLI命令。
| Command | Description |
|---|---|
agentbricks login |
验证配置文件并将其保存为默认配置。 |
agentbricks logout |
不用删除其凭证就忘掉已保存的默认配置档案。 |
agentbricks init |
搭建新的代理项目,或使用 --existing 为现有代理迁移做好准备。 |
agentbricks doctor |
检查是否已为 Agent Bricks CLI 设置好现有智能体。 |
agentbricks dev |
本地运行代理,配合聊天界面。 |
agentbricks memory |
管理长期记忆:绑定或解绑存储,管理存储、条目和记忆管道。 |
agentbricks sessions |
管理对话会话:绑定存储库或解除存储库绑定,并管理会话存储库。 |
agentbricks tools |
列出、添加和移除代理的工具。 |
agentbricks mcp |
探索托管MCP服务。 |
agentbricks tracing |
绑定、解绑并检查跟踪。 |
agentbricks deploy |
将代理部署到Azure Databricks代理运行时。 |
agentbricks deployments |
管理已部署代理:list, get, wait, logs, start, stop,和 delete。 |
agentbricks endpoint |
调用一个HTTP端点。 |
agentbricks experimental |
可能在未预警的情况下发生变化的实验命令: experimental models 和 experimental prompts。 |
关于每个标志和选项,请参见 GitHub 上的 Agent Bricks CLI 命令参考。
Troubleshooting
部署失败是因为工作区已达到上限
托管内存存储和会话存储各自都有工作空间级限制。 如果 agentbricks deploy 因 Workspace has reached the maximum of <N> managed memory stores 而失败,请执行以下任一操作,然后重新运行 agentbricks deploy:
- 释放一个插槽。 运行
agentbricks memory stores list --all以查找你不再需要的存储,然后用agentbricks memory stores delete <name>删除它们。 对于会话存储,运行agentbricks sessions stores list,并使用agentbricks sessions stores delete <name>删除未使用的存储。 - 部署时不带存储。 对于内存存储限制,运行
agentbricks memory unbind。 对于会话存储限制,运行agentbricks sessions unbind。 随后,智能体在没有长期记忆或对话历史的情况下运行。
部署超时或 URL 无响应
如果你是从脚本或编码代理部署,且命令超时时间短,先不等待部署,然后分别等待:
agentbricks deploy my-agent --no-wait
agentbricks deployments wait agent-bricks-my-agent
默认情况下,agentbricks deployments wait 大约在 100 秒后返回。 其退出代码为:
-
0: 代理已部署并运行中。 -
1:部署失败了。 停止重试。 检查错误和agentbricks deployments logs agent-bricks-my-agent的输出。 -
75:部署仍在进行中。 再运行一次同样的命令。
在使用 set -e 的脚本中,退出代码 75 会停止脚本,因此仅在退出代码为 75 时重试:
while true; do
agentbricks deployments wait agent-bricks-my-agent && break
status=$?
[ "$status" -eq 75 ] || exit "$status"
done
如果部署失败,因为应用的计算没能及时启动,运行 agentbricks deployments get agent-bricks-my-agent 以检查应用状态。 如果应用被停止,运行 agentbricks deployments start agent-bricks-my-agent。 然后重新运行 agentbricks deploy my-agent。
对已部署代理的请求因 MCP_USER_AUTH_REQUIRED 而失败
如果MCP工具使用 auth = "user",部署的代理要求Databricks Apps转发已登录用户的令牌。 这适用于所有请求,包括那些不调用工具的提示。 直接使用承载令牌的请求(如 curl 调用或 CI 作业)会因 MCP_USER_AUTH_REQUIRED 而失败。
要以编程方式调用代理,可以使用 --auth app 添加该工具,例如 agentbricks tools add mcp system.ai.dbsql --auth app。 要切换现有工具,先用 agentbricks tools remove mcp <service> 移除,再用 --auth app 再次添加,然后重新部署。
在构建 cryptography 时,Intel Mac 安装失败
如果在英特尔Mac上从源码构建 cryptography 包时安装失败,建议安装预构建的包。 要使用 pip 安装,请执行以下操作:
pip install --only-binary :all: databricks-agentbricks
安装或agentbricks dev因 Python 版本问题失败
如果安装过程或在运行 agentbricks dev 时,在构建依赖项阶段失败,请使用 python3 --version 检查您的 Python 版本。 脚手架项目要求 Python 3.11 及以上版本,Databricks 推荐使用 Python 3.12。 在较新的 Python 版本中,有些依赖可能没有预构建的包。 要用 Python 3.12 安装 CLI,请执行以下操作:
uv tool install --python 3.12 databricks-agentbricks
其他资源
- 查询代理:查询使用
DurableAgentServer该代理的代理。 - 部署代理:在 Azure Databricks 上部署代理。
- 连接到模型:查询基础模型和嵌入模型。
- Agent Bricks 常见问题解答:Agent Bricks 常见问题解答。
- 代理工具和MCP服务: MCP。
- 代理内存概念与API: 代理内存。
- 代理会话概念与API:代理会话。
- 将会话历史提炼为长期记忆: 代理记忆流水线。
- MLflow 代理追踪: 跟踪概述。