Databricks AI Agent 节点
使用 Databricks AI Agent 节点构建 AI agent[^1],并让运行记录显示在 Databricks 工作区的 MLflow Tracing 中。该节点运行与 AI Agent 节点相同的 agent:使用相同的 chat model、memory、tool[^2] 和 output parser 子节点,并提供相同的选项。它额外提供 Export Traces to MLflow 导出跟踪到 MLflow。启用后,每次运行都会在 MLflow experiment 中创建一条 trace,其中每次模型调用和工具调用各有一个 span。这样,负责 Databricks 工作区的团队便能将 n8n agent 与其他 AI 系统一并检查。
本页面介绍先决条件、设置步骤、节点参数、trace 包含的内容,以及导出失败时的行为。
提示
Credentials 凭据
有关设置身份验证的指南,请参阅 Databricks 凭据。此节点上的凭据可选。agent 使用已连接 chat model 子节点的凭据运行。此节点仅使用自己的 Databricks OAuth2 API 凭据导出 trace,因此启用 Export Traces to MLflow 导出跟踪到 MLflow 时请选择一项凭据。
先决条件
要运行 agent,您需要一个具有自身凭据的 chat model 子节点,例如 Databricks Chat Model 节点。要导出 trace,您还需要:
- n8n 中使用服务主体或用户登录的 Databricks OAuth2 凭据。服务主体必须是工作区成员,并具有 Workspace access 权利。
- 对接收 trace 的 experiment 拥有 CAN EDIT 权限。CAN READ 不足以导出:导出会失败并返回
403,说明该身份无权编辑 experiment。 - 对于节点在
/Shared下创建的默认 experiment,无需额外授权。Databricks 默认向所有工作区用户授予/Shared文件夹中对象的 CAN MANAGE 权限,因此该身份可以创建 experiment 并写入其中。这也意味着每位工作区用户都可以打开和删除这些 trace。对于处理个人或机密数据的工作流,请将 Experiment 实验设为您所控制文件夹中的路径。或者,先创建 experiment 并设置其权限,再启用导出。
权限更改可能需要一分钟或更长时间才能传播到 trace 服务。刚刚更改权限后运行,仍可能使用旧权限。
设置节点
- 将 Databricks AI Agent 节点添加到工作流中,例如放在 Chat Trigger 节点之后。
- 选择 Chat Model 聊天模型连接器上的 +,然后添加 chat model,例如 Databricks Chat Model 节点。按照使用 AI Agent 节点时的方式添加 memory、tool 和 output parser。Databricks Vector Store 节点和 Databricks Genie One MCP server 都可以用作工具。
- 设置 Source for Prompt (User Message) 提示来源(用户消息)和节点选项。
- 要导出 trace,请在 Credential to connect with 要连接的凭据下选择 Databricks OAuth2 凭据,并启用 Export Traces to MLflow 导出跟踪到 MLflow。
- 在 Experiment 实验中,留空名称可让节点为工作流创建 experiment,也可以输入现有 experiment 的路径或 ID。请参阅节点参数。
- 运行工作流。在 Databricks 中,打开侧边栏中的 Experiments,选择 experiment,然后选择 Traces 选项卡。agent 每次运行都会显示为一条 trace,并预览问题和答案。
节点参数
- Source for Prompt (User Message) 提示来源(用户消息):用户消息的来源,可选 Connected Chat Trigger Node 已连接的 Chat Trigger 节点或 Define below 在下方定义。其行为与 AI Agent 节点上的同名字段相同。此节点不提供 Connected Guardrails Node 已连接的 Guardrails 节点来源。
- Require Specific Output Format 要求特定输出格式:启用后可连接用于规定 agent 输出格式的 output parser 子节点。
- Enable Fallback Model 启用备用模型:启用后可连接第二个 chat model,并在主模型失败时使用。
- Export Traces to MLflow 导出跟踪到 MLflow:是否将每次运行发送到此节点所选凭据对应工作区中的 MLflow Tracing。默认关闭。
- Experiment 实验:trace 的存储位置。启用 Export Traces to MLflow 导出跟踪到 MLflow时显示。
- By Name 按名称:experiment 路径,例如
/Shared/my-agent-traces。如果 experiment 不存在,节点会创建它。留空该字段则使用/Shared/n8n-workflows-<workflow-id>,每个工作流使用一个 experiment。 - By ID 按 ID:现有 experiment 的数字 ID,与 Databricks URL 中显示的 ID 相同。不存在的 ID 不会导致运行失败:agent 仍会回答,但导出随后失败,并在 n8n 日志中显示警告。
- By Name 按名称:experiment 路径,例如
节点选项
这些选项与 AI Agent 节点相同。有关 System Message 系统消息、Max Iterations 最大迭代次数(默认为 10)、Return Intermediate Steps 返回中间步骤、Automatically Passthrough Binary Images 自动传递二进制图像、Tracing Metadata 跟踪元数据和 Enable Streaming 启用流式传输,请参阅 Tools Agent。另外还有两个选项:
- Automatically Passthrough Binary PDFs 自动传递二进制 PDF:是否将输入中的二进制 PDF 文档作为消息的一部分传递给模型。默认关闭。请与接受 PDF 输入的模型搭配使用。
- Batch Processing 批处理:Batch Size 批量大小设置 agent 一次处理的输入项数(默认为
1),Delay Between Batches 批次间延迟设置每批之间等待的毫秒数(默认为0)。使用这些选项可避免超出按 token 付费模型服务的速率限制。
节点导出的内容
节点处理的每个数据项都会成为一条 trace。trace 包含一个 span 树:
- 顶层是 agent 运行,以用户消息作为输入,最终答案作为输出。
- 每次模型调用对应一个 span,其中包含发送给模型的完整消息列表,以及 OpenAI 格式的 completion。消息列表包括 system message、从 memory 加载的对话历史记录,以及以 base64 形式传递给模型的所有图像或 PDF。span 还记录工具调用和该次调用的 token 用量。
- 每次工具调用对应一个 span,其中包含参数和结果。Vector Store 工具的 span 会显示其返回的文档。
- 当 Vector Store Question Answer Tool 等工具通过 retriever 查询 Vector Store 时,每次 retriever 调用对应一个 span。
每个 span 都包含开始和结束时间。trace 本身包含:
client_request_id:n8n execution ID,可将工作区中的 trace 映射回 n8n 中的一次执行。- 标签
n8n.source(n8n)、n8n.workflowId和n8n.node(节点名称)。 - 请求预览和响应预览,即问题与答案的前 1,000 个字符,在 trace 列表中显示为两列。
- 该次运行的 token 总用量,无需打开 span 即可在 trace 列表中查看每次运行的成本。
- 状态:
OK;运行失败时为ERROR。模型调用失败会将 trace 标记为ERROR,并在模型 span 中显示 Databricks 错误消息。工具抛出的错误会记录为ERROR工具 span;如果 agent 恢复并给出答案,trace 仍保持OK。
流式运行导出相同的 span,并补全结束时间和 token 计数。取消运行时,导出也会停止。experiment 中可能没有这次运行的 trace,也可能有一条不含 span 的 trace。无论哪种情况,n8n 都会记录导出失败。模型 span 的名称是 ChatOpenAI,而不是模型服务名称,因为 Databricks Chat Model 节点通过 OpenAI 兼容客户端调用网关。
警告
Traces contain your data Trace 包含您的数据
Trace 导出会将每次运行的真实 prompt(包括 system message 和 memory)、模型输出、工具结果和检索到的文档发送到所选凭据对应的 Databricks 工作区。在 span 中,n8n 会隐去常见 token 格式和带标签的密钥(如 password=...),除此之外不会隐去其他内容。trace 列表中显示的问题和答案预览不会被隐去。导出默认关闭,数据仅发送到您自己的工作区,绝不会发送给 n8n 或第三方。如果工作流处理个人或机密数据,请先与安全团队确认,再启用此设置。
导出失败时的行为
Trace 导出只用于可观测性,因此绝不会改变运行结果:
- 如果节点无法准备导出,例如凭据无效、experiment 查找失败或身份缺少权限,agent 仍会运行并回答。n8n 会将
Databricks AI Agent: could not prepare MLflow trace export及原因写入日志。 - 如果运行后写入 trace 失败,运行输出仍然有效,n8n 会记录
Databricks AI Agent: MLflow trace export failed和 Databricks 错误。该警告仅显示在 n8n 服务器日志中,不会显示在执行记录中。 - 可能发生部分导出:Databricks 可以注册 trace,但拒绝上传其中的 span。此时 trace 会显示在列表中,但不含 span。
- 唯一会导致硬失败的情况是缺少凭据。启用 Export Traces to MLflow 导出跟踪到 MLflow但未选择凭据时,节点会在任何模型调用前失败,并显示
Select a Databricks credential to export traces to MLflow。
每条 trace 的导出会发起三次调用:在 experiment 中注册 trace、请求一个签名上传 URL,以及将 span 上传到该 URL。上传 URL 带有自身的短期凭据,因此绝不会向其发送工作区 token。
相关资源
- AI Agent 和 Tools Agent:agent 选项和常见问题
- Databricks Chat Model
- Databricks Vector Store,其中包含 agent 从 Databricks 索引回答问题的完整示例
- Embeddings Databricks
- Databricks Genie One MCP server
- Databricks 凭据
- 从社区包迁移:请参阅从 n8n-nodes-databricks 社区包迁移
- Databricks 文档中的 MLflow Tracing 和 MLflow experiment 权限
查看 n8n 的 Advanced AI 高级 AI 文档。
常见问题
选择用于将 trace 导出到 MLflow 的 Databricks 凭据
已启用 Export Traces to MLflow 导出跟踪到 MLflow,但节点没有凭据。请在 Credential to connect with 要连接的凭据下选择 Databricks OAuth2 凭据,或者关闭该选项。
Experiment 中未显示 trace
运行成功,但 experiment 仍为空。请在 n8n 服务器日志中查找以 Databricks AI Agent: 开头的行,其中会指出原因:403 表示身份缺少 experiment 的 CAN EDIT 权限;带 RESOURCE_DOES_NOT_EXIST 的 404 表示 By ID 按 ID指定的 experiment 不存在;token 错误表示凭据无法访问工作区。授予权限后,请等待一分钟再重新运行。
Trace 不含 span
Databricks 已注册 trace,但拒绝上传 span,因此 trace 列表会显示这次运行,却没有 span 树。请检查 n8n 服务器日志中的上传错误,以及该身份对 experiment 的 CAN EDIT 权限。
Agent 问题
对于 agent 本身的问题,例如模型不调用工具或触发速率限制,请参阅 Databricks Chat Model 页面上的为 agent 选择模型,以及 AI Agent 的常见问题。
[^1]: AI agent 是能够响应请求、做出决策并代表用户执行现实任务的人工智能系统。它使用大语言模型(LLM)解释用户输入,并根据可用的信息和资源决定处理请求的最佳方式。 [^2]: 在 AI 场景中,工具是一种附加资源,AI 在响应请求时可利用它获取特定信息或功能。AI 模型可以使用工具与外部系统交互,或完成具体且专注的任务。