使用 Databricks 实现 AI 代理：完整实用指南

信息技术数字 » 资源 » 使用 Databricks 实现 AI 代理：完整实用指南

在 Databricks 中构建 AI 代理不再是技术精英的专属领域：借助AI Playground 等可视化环境、Agent Bricks 自动化功能以及 MLflow 框架，您现在可以从构思到原型，再从原型到生产，轻松完成整个流程。本指南将为您精简创建、评估和部署代理所需的一切内容，这些代理可以调用​​工具、查询数据并与Unity Catalog管理系统集成。

除了探索无代码方法和 Python 开发之外，您还将学习如何使用MLflow（ChatAgent 和 ResponsesAgent）打包代理、在目录中注册资源、启用实时监控以及使用模型服务进行扩展。我们还提供了一个使用React 和 FastAPI构建的示例应用程序，可将您的代理无缝集成到企业 Web 界面中。

在 Databricks 中创建代理的选项

如果您注重速度和简易性，Agent Bricks提供了一个自动化工作流程，用于构建高质量、领域相关的代理系统。您只需指定用例并连接Unity Catalog数据；平台即可生成代理变体，通过评估进行优化，并允许您进行改进，所有操作均内置治理和安全机制。

当您需要精细的控制并希望重用熟悉的库时，基于代码的方法结合了Mosaic AI Agent Framework 和 MLflow。借助 Python，您可以定义代理逻辑、启用工具调用、执行详细跟踪，并最终将其打包并部署到 Databricks 生态系统中以进行生产。

如果您已经在使用第三方框架，MLflow 原生支持LangGraph/ LangChain、LlamaIndex或自定义 Python 实现。得益于 MLflow 的模型签名和代理接口，您可以直接将它们集成到评估和监控功能中，而无需从头开始重写代码。

想以闪电般的速度构建原型？借助AI Playground，您可以选择模型和虚拟机，通过低代码界面向 LLM 添加工具，并通过聊天进行验证。然后，您可以将代理导出为可用于生产环境的代码，并继续执行标准的开发生命周期。

模型签名及与平台功能的兼容性

Azure Databricks 使用MLflow 模型签名来描述代理的输入和输出架构。产品功能（例如 AI Playground 或评估）要求代理符合受支持的签名之一，以确保互操作性。

如果您在构建代理时遵循推荐方法，MLflow 会自动推断兼容的签名，无需任何额外步骤。否则，请验证您的实现是否符合代理输入和输出的旧版模式中的签名之一，以避免在与 Databricks 工具集成时出现意外情况。

快速教程：使用 Mosaic AI Agent Framework 构建第一个代理

目标是创建一个能够进行推理的智能体 由 Databricks 主办的 LLM 并且能够运行工具，例如内置函数 system.ai.python_exec 从 Unity Catalog 运行 Python 代码。此外，我们将启用 使用 MLflow 进行跟踪 用于检查痕迹和诊断。

基本工作区要求：启用代理功能并具备 获取模型服务在运行时环境中，安装诸如以下软件包： mlflow, databricks-openai 以及代理包装工（databricks-agent o databricks-agents（取决于你所遵循的指南和版本），然后重启 Python 以加载依赖项。

使用 OpenAI 客户端定义与模型服务的连接，该客户端公开了该模型服务。 工作区客户端， 积极的 mlflow.openai.autolog() 用于自动仪器测量，并记录可用工具。其中包括： system.ai.python_exec 它充当无状态 Python 解释器，允许 LLM 在对话期间进行计算或操作数据。

使用类似这样的函数 run_agent()您将用户的提示发送到聊天端点（例如，像“databricks-claude-3-7-sonnet«并管理可能的情况 调用工具 以连贯的列表形式返回助手消息和工具响应。

为了进行测试，请运行一个需要代码的查询（例如，计算斐波那契数列的第 100 个数），并查看向导输出以及相关笔记本或实验中记录的MLflow 跟踪信息。这将帮助您在打包之前优化流程。

与 MLflow 打包并部署在模型服务中

为生产环境准备代理的推荐方法是实现接口 MLflow ChatAgent你需要一种方法 predict() 它接收消息，调用你的代理逻辑，并返回一个 聊天代理响应 包含消息列表（如果适用，包括与工具关联的中间消息）。

为了便于管理，请将所有代码合并到一个 Python 文件中（例如，通过使用 %%writefile quickstart_agent.py （如果您使用的是笔记本电脑）。在最后一部分，请调用 mlflow.models.set_model() 传递你的类实例（例如， QuickstartAgent）建立 入口点 的推理。

注册代理人 统一目录 同 mlflow.pyfunc.log_model，包括 手段 您在生产环境中需要用到：LLM 模型端点（例如， DatabricksServingEndpoint）以及代理将调用的目录函数（例如， DatabricksFunction 同 system.ai.python_exec因此，Databricks可以 配置身份验证 部署这些资源时需要用到这些资源。

最后，使用代理 API 来 废话 将模型映射到服务端点： from databricks import agents y agents.deploy(model_name, model_version)当终点站启动时，您将能够 来自 AI Playground 的聊天分享给感兴趣的各方，并开始收集反馈意见。

如果您想继续改进，Databricks 提供了衡量代理质量、构建具有检索（RAG）的代理（针对非结构化数据）和控制多轮对话的指南，以及使用LangGraph、纯 Python 或 OpenAI 的替代方案。

ResponsesAgent：面向生产代理的现代化界面

虽然 聊天代理 它运行良好，MLflow 今天也推荐它。 响应代理 适用于严肃的代理商。此接口与该方案兼容。 Responses 来自 OpenAI，并允许集成来自 OpenAI 的代理 任何框架 借助 Databricks 的各项功能（注册、跟踪、评估、部署和可观测性），您可以轻松无阻地完成这些操作。

主要优势：原生支持 系统 多代理退出模式 流完整的消息和工具调用历史记录，工具调用确认信息以及 持久耐用的工具。 此外，它还提供 类型化接口 在Python中，自动签名推断、自动跟踪 predict y predict_stream 并通过改进推理表 人工智能网关.

此方案的安装要求： databricks-agents 1.2.0+, mlflow 3.1.3+ y Python 3.10 + （使用 Serverless 或 Databricks Runtime 13.3 LTS+）。Databricks 还推荐以下软件包： AI Bridge 用于常见集成。

实用集成： databricks-openai （OpenAI）， databricks-langchain （LangChain/LangGraph） databricks-dspy （DSPy）和 databricks-ai-bridge （纯 Python 编写的智能体）。利用这些组件，您可以构建从简单智能体到各种智能体。 复杂的管道 带有恢复和工具调用。

如果您已经有一个内置代理，请将其包装在一个继承自以下类的类中： mlflow.pyfunc.ResponsesAgent。 实施 predict 将输入和输出转换为 响应代理模式对于流媒体播放，请依赖 predict_stream, 发射 三角洲 以及最终活动 response.output_item.done 请提供完整答案。

对于流式错误，Mosaic AI 会将故障与最后一个令牌一起传播。 databricks_output.error您的客户应该能够正确地捕获和显示它，从而提高…… 净化体验.

恢复系统、自定义输入和可追溯性

许多代理商使用 恢复者 对于向量索引上的 RAG（随机无序）系统。如果您的检索范围采用不同的方案，您可以将其映射为： mlflow.models.set_retriever_schema声明 primary_key, text_column, doc_uri 以及其他列。因此，AI Playground 将显示 链接至来源 已恢复，评估将适用 相关性评分者 自动。

如果您的代理人需要更多信息（例如， 客户端类型 o SESSION_ID), 用途 custom_inputs 并返回元数据 custom_outputs 这不应污染聊天记录。AI Playground 和评论应用都允许您进入。 自定义输入 从用户界面。

使用 deploy() 进行部署，要求和自动化操作

要将您的代理发布到 Mosaic AI 模型服务平台，请使用以下功能 deploy() Python API。在 MLflow 3 中，安装 mlflow >= 3.1.3 y databricks-agents >= 1.1.0 （如果您在笔记本之外部署）。在 MLflow 2.x 中，最小值会发生变化（例如， mlflow >= 2.13.1 y databricks-agents >= 0.12.0确保 在 Unity 目录中注册代理。 部署前。

拨电至 deploy() 构建一个可扩展的端点 自动平衡，配置 安全认证 对于 Databricks 资源（向量索引、目录函数）——检查所有者权限——并激活 审查申请 为了与利益相关者合作。

它还支持在 MLflow 中进行实时监控（在活动实验和推理表中记录跟踪信息）。在 MLflow 3 中，可以配置带有自动质量评估的生产监控；REST 请求和评论会记录在推理表中（使用现代反馈 API）。

要进行自定义，请传递参数。 deploy() 如 scale_to_zero_enabled=True降低停机后的成本，代价是首次请求的延迟更高。此外，您还可以使用以下实用程序： 列出、获取和删除 通过代理 API 进行部署。

状态、配置和执行模式的良好实践

模型服务是分布式的：避免 本地缓存 并假设不同的回复可以应对对话中的不同回合。它根据以下情况重建状态： 字典 ResponsesAgentRequest 在每个 predict 并将该状态设计为 线程安全的.

初始化内部状态 predict 而不是在代理构造函数中，因为单个副本可以处理来自不同用户的对话。这可以防止这种情况发生。 信息泄露 以及高吞吐量环境下的并发冲突。

用以下方式参数化智能体的行为 ModelConfig （字典或 YAML）。例如，定义如下： model_serving_endpointLLM 参数和提示模板；将该配置加载到开发环境并将其部署到生产环境。 无需修改代码.

避免在代理服务器上引入事件循环或异步帧：Databricks内部会处理并发。请使用同步代码或回调；否则，您可能会遇到“此事件循环已在运行”之类的错误以及异常行为。

Agent Bricks：无需代码即可实现自动化，加速价值创造

Agent Bricks 于 2025 年推出，提供无需编码的无缝代理创建工作流程。您只需用自然语言输入任务，连接数据，平台即可选择模型、生成合成数据、进行评估并不断优化流程，最终交付一个符合Unity Catalog管理规范、可用于生产环境的代理。

它的优势包括端到端自动化、Databricks 的可扩展性（端点在 3 天不活动后可以缩减至零） 、Lakehouse 的使用情况和成本分析以及现成的代理类型（信息提取、自定义 LLM、知识助手和用于复杂编排的多代理主管）。

其局限性包括：生成的代码目前无法下载，这限制了深度定制；模板目录主要面向已集成 Lakehouse 和 Unity Catalog 的组织。部分用户还反映成本指标不够精细。

例如，多智能体和有状态智能体

在官方文档中，您可以找到OpenAI（包含简单的聊天和工具调用，适用于 Databricks 和 OpenAI 托管的模型）、LangGraph（工具调用）和DSPy （单回合工具调用）的笔记本。这些笔记本为使用自定义工具和质量评估扩展功能奠定了良好的基础。

要协调多位专家，您可以使用 Genie 等工具搭建协作系统。如果您对对话记忆感兴趣，Genie 等工具还支持有状态代理，允许设置检查点和持久化聊天记录。

在官方文档中，您可以找到OpenAI（包含简单的聊天和工具调用，适用于 Databricks 和 OpenAI 托管的模型）、LangGraph（工具调用）和DSPy （单回合工具调用）的笔记本。这些笔记本为使用自定义工具和质量评估扩展功能奠定了良好的基础。

Databricks 上的应用：使用 React 构建 UI，使用 FastAPI 构建后端

Databricks Apps提供了一个强大的平台，无需搭建外部基础设施即可交付丰富的界面。它们与 Databricks SQL、Unity Catalog、Model Serving 和 Jobs 原生集成，并继承了平台的安全性和合规性控制。

一种非常实用的模式是使用React创建前端（支持流式传输、消息渲染和 Markdown 用户体验），并使用FastAPI创建后端，作为与代理端点的桥梁。后端将用户的请求路由到模型服务，并将结构化响应返回给客户端。

在 FastAPI 中，子应用程序的组装顺序非常重要： app.mount("/api", api_app) 指导 API 路由（例如， /api/chat）Y app.mount("/", ui_app) 它提供 React 构建后根目录中的静态文件。这种方案维护了 路线清晰度 并将用户界面与端点分离。

配置环境变量（例如， SERVING_ENDPOINT_NAME 或 Unity Catalog 中代理模型的 FQN）来自 Databricks 中的应用程序定义。编译前端（npm run build），同步文件，声明依赖项（requirements.txt）并以 独角兽 + 独角兽 ASGI 的员工。

真实案例：用于制造运营的聊天机器人

在制造运营管理 (MOM) 场景中，Databricks 聊天机器人可以协助生产经理进行瓶颈分析、库存跟踪和报告生成。这些功能以工具的形式（通过 SQL 或 Python）发布在 Unity Catalog 中，聊天机器人会根据上下文调用这些工具。

示例：一个函数 identify_bottleneck_station 它在 Databricks SQL 中运行查询，以检测导致延迟最大的阶段；另一个， check_inventory_levels它返回实时库存信息。该代理商还可以 发电子邮件生成报告并进行情感分析，所有这些都通过工具调用进行协调。

部署模型服务端点充当标准后端。React 应用会使用此端点，以流畅的用户体验显示实时响应，并在 ResponsesAgent 中启用时支持令牌流。

从聊天补全迁移及兼容性

如果您的旧版代理使用 OpenAI 的ChatCompletions API ，您可以迁移到ResponsesAgent，并使用一个容器来转换传入/传出的消息，还可以选择将流式增量映射到ResponsesAgentStreamEvent 。这样可以在不重写核心逻辑的情况下实现遥测和可观测性的现代化。

代理 API 可用于列出和管理部署，您可以列出现有部署、检索特定部署（按名称和版本）以及删除不再需要的端点。请记住使用环境变量和密钥管理外部资源凭据。

Databricks 提供完整的解决方案：从使用AI Playground进行创意构思或使用 Agent Bricks 实现自动化，到代码开发（Mosaic AI、MLflow、LangGraph、DSPy），再到打包、在Unity Catalog中注册、使用deploy()进行部署以及生产环境监控。通过遵循最佳实践，例如正确的模型签名、分布式环境中的安全状态以及参数化配置，您可以交付可靠且受控的代理，并将其集成到平台上的 Web 应用程序中。