Databricks Genie One MCP 服务器
n8n MCP 服务器注册表中的 Databricks Genie One 卡片会将 AI 智能体连接到 Databricks 工作区中的 Genie One MCP 服务器。Genie One 是 Databricks 为业务用户提供的助手。它会将每个问题路由到工作区中相关的 Genie Agent;如果没有匹配的智能体,则路由到其他受治理的数据资产,然后生成并运行 SQL 来回答问题。如需通过 Agent ID 调用某个特定 Genie Agent(原 Genie 空间),请改用 Databricks 节点。智能体会在使用了 Genie One 的回复后附加 Powered by Databricks Genie 标签,每个答案都会链接回 Databricks 中的对话。有关哪些智能体会添加该标签以及何时会跳过,请参阅 Genie 归属标识。
本页面介绍通过 n8n 智能体使用 Genie 所需的先决条件、设置步骤、智能体设置和已知问题。
提示
Credentials 凭据
此节点使用通过用户登录连接的 Databricks OAuth2 凭据。它不支持服务主体或个人访问令牌。
先决条件
- Databricks 账户管理员已创建自定义 OAuth 应用连接,且其 scope 涵盖此卡片的请求。卡片请求
ai-gateway和offline_accessscope。只包含这两个 scope 的应用连接是权限最小的设置;当连接仅用于 Genie 时,n8n 建议采用此设置。All APIs 不包含ai-gateway。只有同一应用连接还服务于需要该 scope 的 Databricks 节点或 Databricks Chat Model 节点时,才应同时使用它。如果连接失败并显示ai-gatewayscope 错误,管理员需要为应用连接添加ai-gatewayscope。 - 你对 Genie One 可用于回答的每个 Genie Agent 拥有 CAN RUN 权限,对至少一个 SQL 仓库拥有 CAN USE 权限,并且对
system.ai.genie_one_mcp拥有 EXECUTE 权限。请参阅所需 Databricks 权限。 - 能可靠调用工具的聊天模型。n8n 建议使用 Databricks Chat Model 节点及 Llama 3.3 70B 或 Qwen 3.5。请参阅为智能体选择模型。
将 Genie 连接到智能体
Genie MCP 服务器只使用一种身份验证类型:用户登录。智能体会以连接凭据的 Databricks 用户身份向 Genie 提问,因此每位 n8n 用户都需要创建自己的凭据。
- 在画布上打开 AI Agent 智能体节点,然后选择其 Tool 工具连接器上的 +。
- 搜索
Databricks Genie One,或打开 MCP Servers 部分浏览注册表。 - 选择 Databricks Genie One 卡片。n8n 会向智能体添加名为 Databricks Genie One MCP 的节点并打开其设置。
- 在 Credential to connect with 用于连接的凭据下,选择 Create new credential 创建新凭据。
- 将工作区 URL 输入为 Host 主机,例如
https://adb-1234567890123456.7.azuredatabricks.net。 - 输入管理员所创建自定义 OAuth 应用连接的 Client ID 客户端 ID和 Client Secret 客户端密钥。
- 选择 Connect 连接并登录 Databricks。
- 在 Tools to Include 要包含的工具中保留 All 全部,使智能体能够提问、轮询、获取结果和取消请求。请参阅工具。
- 将智能体的 Max Iterations 最大迭代次数选项设置为 30 或更高。请参阅针对 Genie 配置智能体。
向智能体发送有关数据的问题,例如「trips 表中有多少次行程?」。回复会包含 Genie 的答案和 Explore in Databricks 链接。
工具
Genie One 向 n8n 提供四种工具。Databricks 会将每个问题路由到 Genie Agent;如果没有匹配的智能体,则路由到其他工作区数据,因此无需智能体参数。下表显示 Databricks 的工具短名称。在 n8n 中,智能体看到的每个名称都带有节点名称前缀;例如,默认节点名称对应 Databricks_Genie_One_MCP_genie_ask。重命名的节点,或在卡片重命名之前添加的节点,会保留自身的名称作为前缀,例如 Databricks_Genie_MCP_genie_ask。不要在提示词中引用短名称。
Databricks 还列出 view_ask,它只提供给 MCP Apps 客户端,用来代替 genie_ask,因此 n8n 的 agent 看不到它。
| 工具 | 作用 |
|---|---|
genie_ask |
使用问题开始 Genie 对话,或使用 conversation_id 继续对话。它会返回状态,而不等待答案。 |
genie_poll_response |
检查 Genie 是否已完成。Databricks 建议每次轮询间隔 2 到 5 秒。 |
genie_get_query_result |
当答案摘要不够用时,获取 Genie 所运行 SQL 的完整结果行。 |
genie_cancel_response |
取消正在运行的 Genie 回合。 |
针对 Genie 配置智能体
Genie 采用异步回答方式。智能体先调用 genie_ask,然后持续调用 genie_poll_response,直到 Genie 报告已完成。每次轮询会消耗一次智能体迭代:包括一次 genie_poll_response 调用,以及模型决定是否再次轮询的一次回合。Databricks 表示 Genie 回合通常需要 70 到 260 秒完成,并建议每次轮询间隔 2 到 5 秒,因此一个答案可能需要 14 到 130 次迭代。
- 提高 Max Iterations 最大迭代次数。 AI Agent 智能体的默认值 10 无法满足真实问题。请将 Max Iterations 最大迭代次数设置为 30 或更高。耗时接近 Databricks 所述上限的问题仍可能达到限制;如果看到截断,请继续提高此值。
- 了解达到限制时的表现。 AI Agent 节点版本 3 会使执行失败,并显示
Max iterations (30) reached。较旧的 AI Agent 版本会成功执行并回复Agent stopped due to max iterations.,这看起来像答案,但实际并不是。达到限制后,Genie 仍会继续在 Databricks 端运行该回合。 -
引导模型。 类似以下内容的系统消息可以让循环保持紧凑,并保留归因链接:
text To answer data questions, ask Genie the question, then poll until the status is completed. Fetch the full result rows only if you need them. Include any [Explore in Databricks](url) link from the tool result in your reply, verbatim.不要在系统消息中写出工具名称。严格按提示执行的模型会尝试调用短名称,但这些名称与 n8n 注册的名称不匹配,因此不会运行任何工具。
-
留意聊天模型速率限制。 在 n8n 的测试中,Genie 本身没有限流,但按 token 计费的模型端点会限流。三个并发智能体运行就足以因聊天模型的速率限制导致执行失败。请使用预置吞吐量端点或保持较低并发量。
Genie 归因
Databricks 要求采用 Genie 的集成明确标识 Genie。在 n8n 中:
- 当执行调用了 Genie One 工具时,AI Agent 节点(版本 3 或更高)和 n8n Agents 会在回复后附加 Powered by Databricks Genie 标签。n8n 会在模型回答后通过代码添加该标签,因此系统消息无法移除它。启用 Require Specific Output Format 要求特定输出格式 时,AI Agent 节点会跳过该标签,因为结构化输出必须保持可解析。
- 每个已完成的 Genie 答案都包含 Explore in Databricks 链接,用于在工作区的 Genie 中打开该对话,使用户可以检查 SQL 和结果。Genie 会指示模型逐字呈现此链接,n8n 也会原样传递工具结果。不要在系统消息或输出解析中移除该链接。
相关资源
- Databricks 凭据,其中包括管理员所需的
ai-gatewayscope 设置 - Databricks Chat Model 聊天模型节点
- 用于不借助 AI 智能体直接调用 Genie Agent REST API 的 Databricks 节点
- 了解注册表工作方式的 MCP 服务器
- Databricks 文档中的 Genie One MCP 服务器
常见问题
警告
2026 年 10 月 30 日的端点变更
Databricks 将于 2026 年 11 月 30 日停用 beta 版 Genie MCP 端点,改为通过 AI Gateway 端点提供 Genie One。从 2026 年 10 月 30 日起,该卡片调用 AI Gateway 端点,需要 ai-gateway scope。
该怎么做: Databricks 账户管理员把 ai-gateway scope 加到应用连接上。然后每个用户打开自己的凭据,选择 Switch account 切换账户,并用同一个 Databricks 账户登录。请参阅为 Genie One MCP 服务器添加 ai-gateway scope。
新凭据因 ai-gateway scope 错误而失败
在部分 Databricks 账户上,在凭据中选择 Connect 连接会失败并显示:
access_denied: Scopes 'ai-gateway' are not assigned to the client <client-id>
在其他 Databricks 账户上,连接会成功,但 agent 一开始运行就失败并显示 Invalid scope, required scopes: ai-gateway,因为 n8n 连接 Genie One 来加载它的工具。两种情况下,自定义 OAuth 应用连接都没有 ai-gateway scope,而且 All APIs 不能代替它。Databricks 账户管理员需要在账户控制台的范围选择器中,或通过 Databricks CLI,为应用连接添加 ai-gateway scope。
现有凭据因 ai-gateway scope 错误而失败
以前可用的凭据会让 agent 一开始运行就失败,并显示:
Could not connect to your MCP server. Authentication failed. Streamable HTTP error: Error POSTing to endpoint: Invalid scope, required scopes: ai-gateway
该凭据持有的是卡片改用 AI Gateway 端点之前、带有 genie scope 的 token。Databricks 只会签发应用连接允许的 scopes,因此修复分两部分:Databricks 账户管理员添加 ai-gateway scope,然后用户打开凭据,选择 Switch account 切换账户,并用同一个 Databricks 账户登录。
达到最大迭代次数
执行失败并显示 Max iterations (10) reached,或智能体回复 Agent stopped due to max iterations.。Genie 尚未完成时,智能体已用完迭代次数。请在 AI Agent 智能体节点上将 Max Iterations 最大迭代次数提高到 30 或更高。请参阅针对 Genie 配置智能体。
智能体从不调用 Genie
智能体用完所有迭代次数,却没有调用一次工具。执行日志中,以下两个原因看起来相同:
- 系统消息中写出了工具名称,例如
genie_ask。模型会调用短名称,但它们与 n8n 注册的带前缀名称不匹配,因此工具不会运行。请像针对 Genie 配置智能体中的示例一样描述流程,而不要写出工具名称。 - 聊天模型没有返回智能体可以执行的工具调用。请切换到能可靠调用工具的模型,例如通过 Databricks Chat Model 聊天模型节点使用 Llama 3.3 70B 或 Qwen 3.5。
Genie 报告 SQL 或权限错误
Genie 会返回自己的错误文本,例如 [TABLE_OR_VIEW_NOT_FOUND] The table or view samples.nyctaxi.does_not_exist cannot be found,智能体则会转发该错误。请在 Databricks 中修复底层数据或授权问题。连接的用户需要对回答问题的 Genie Agent 拥有 CAN RUN 权限,并对其使用的表拥有 Unity Catalog 权限。