Important
此功能在 Beta 版中。 启用它不需要工作区设置。 安装 Agent Bricks CLI 即可开始使用。
本快速入门通过 Agent Bricks CLI(databricks-agentbricks),即用于构建和部署代理的 Azure Databricks 命令行工具,指导你从空目录开始,部署自定义代理。 Agent Bricks CLI 为你管理模型访问、内存、会话、工具和追踪,让你专注于代理的逻辑。
Agent Bricks CLI 的工作原理
Agent Bricks CLI 从框架模板搭建本地项目,运行时、测试和可选的聊天界面已经布线好。 你编写应用程序逻辑(模型、工具和提示),CLI 在本地运行它并进行部署。 声明文件agent.toml是代理所依赖的 Azure Databricks 管理资源的权威来源,如工具、内存、会话和追踪。
agentbricks deploy 读取它以进行配置并完成相关设置。
三个命令将代理从空白目录带到生产环境:
-
agentbricks init搭建项目框架并撰写agent.toml。 -
agentbricks dev本地运行该代理,使用与 Azure Databricks 相同的运行时和环境。 -
agentbricks deploy配置声明的资源并部署。
Prerequisites
Databricks 的 CLI 已安装并且已在 PATH 中。
Python 3.11 或更高版本。 Databricks 推荐使用 Python 3.12。 如果安装或
agentbricks dev因 Python 版本而失败,请参见故障排除。uv,用于运行agentbricks init、agentbricks dev和agentbricks deploy的脚手架项目。安装Agent Bricks CLI。 要将其安装为
uv工具,请运行以下操作:uv tool install databricks-agentbricks要改用
pip安装,请运行pip install databricks-agentbricks。
步骤 1:身份验证
用 OAuth 认证你的工作区,保存一个命名配置文件,并将其设置为 Agent Bricks CLI 的默认配置:
databricks auth login --host https://<your-workspace-url> --profile <profile>
agentbricks login --profile <profile>
第二步:搭建项目框架
搭建新的智能体项目,使用 --framework 选择框架模板:
agentbricks init --framework langgraph my-agent
cd my-agent
步骤3:本地运行代理
在部署前,先在你的机器上运行该代理进行测试:
agentbricks dev
agentbricks dev使用与 Azure Databricks 代理运行时相同的命令和环境,在 http://localhost:8000 提供聊天应用和代理的 API,并连接到 Azure Databricks 模型服务。
在浏览器中打开该网址与代理聊天。 保持服务器运行,为下一步做准备。
步骤4:在本地测试代理
在第二个终端中,向代理的调用API发送请求:
curl -X POST http://localhost:8000/api/invocations \
-H 'Content-Type: application/json' \
-d "{\"id\":\"$(uuidgen)\",\"session_id\":\"$(uuidgen)\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"
如果 uuidgen 不可用,请将每个 $(uuidgen) 替换为任意 UUID。
请求正文具有以下字段:
-
id:每个请求的一个新 UUID。 -
session_id:请求所属的对话。 要在同一对话中发送后续消息,请使用新的id复用该会话 ID。 -
input:发送给代理人的信息。
响应包含调用的status,以及一个output字段,其中包含代理的消息。 关于所有请求字段,请参见 请求正文。
步骤5:部署代理
从 project 目录中,将代理部署到 Azure Databricks 代理运行时:
agentbricks deploy
agentbricks init 把名称 my-agent 记录在 agent.toml 中,因此你无需传递名称。 CLI创建了一个名为 agent-bricks-my-agent的应用。 在 agentbricks endpoint 和 agentbricks deployments 命令中使用该名称。
Agent Bricks CLI 会预配任何绑定的存储,授予智能体的服务主体对它们的访问权限,并推出部署。 首次部署需要几分钟,主要是启动应用的计算资源。
agentbricks deploy 等待代理接听后,返回部署的URL。
要立即返回,而不是等待部署完成,先添加 --no-wait 到 agentbricks deploy,然后运行 agentbricks deployments wait。
如果部署失败,请查看部署日志:
agentbricks deployments logs agent-bricks-my-agent
步骤6:测试部署的代理
向已部署的代理发送请求:
agentbricks endpoint invoke agent-bricks-my-agent \
--path /api/invocations \
--json "{\"id\":\"$(uuidgen)\",\"session_id\":\"$(uuidgen)\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"
和第四步一样,如果 uuidgen 不可用,就将每个 $(uuidgen) 替换为任意 UUID。
命令会查找应用的URL,并用你的默认配置文件进行认证。 如需改用curl和 OAuth 令牌调用 API,请参见查询使用DurableAgentServer的代理。 要在浏览器中与代理聊天,打开部署的URL。
后续步骤
- 完整命令攻略及 Agent Bricks CLI 功能: Agent Bricks CLI。
- 查询部署的代理:查询部署在 Azure Databricks 上的代理。
- 绑定托管内存和会话:智能体记忆。
- 添加工具和 MCP 服务:MCP。
- 使用 MLflow 查看代理跟踪:追踪概览。