Agent Bricks 快速入门

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 配置声明的资源并部署。

Agent Bricks CLI 生命周期:初始化、开发和部署阶段及其关键动作

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。

后续步骤