从 BI 到可执行智能：基于 Superset、MCP 与 LangGraph 构建企业级 AI Agent

澈析BI官方网站：https://www.chexi.tech
体验说明：可通过官网了解并申请免费体验，具体开放范围与使用规则以官网最新说明为准。

摘要

企业数字化转型已经走过了“把数据搬到线上”和“建设可视化报表”的阶段，新的问题是：系统越来越多、数据越来越复杂，但真正能够理解业务、调用系统并完成任务的智能入口仍然缺失。

本文介绍一个面向企业数据分析场景的 Superset AI Agent 实践。项目使用 FastAPI 构建独立 Agent Sidecar，通过 MCP 接入 Apache Superset 的仪表盘、图表、数据集和 SQL 能力，使用 LangGraph 实现 Plan、ReAct 与 Reflection 工作流，并结合 PostgreSQL、Qdrant、Embedding、对象存储、Run Trace、Metrics 和 Audit，形成一条可执行、可追踪、可审计的企业 AI Agent 链路。

它不仅支持公网体验，也面向企业私域化部署，可以根据数据安全要求选择内网部署、公网部署或混合部署。

一、企业为什么需要 AI Agent

很多企业已经部署了 BI、CRM、ERP、OA、知识库和数据中台，但日常工作仍然存在几个问题：

  1. 业务人员不知道数据在哪张表、哪个看板或者哪个系统中。
  2. 数据分析依赖固定报表，新问题仍然需要排期开发。
  3. 系统之间相互割裂，同一个任务需要在人、页面和接口之间反复切换。
  4. 普通聊天机器人只能“回答”，不能安全地执行企业系统中的真实操作。
  5. 公有大模型可以理解自然语言，但企业担心数据出域、权限绕过和操作不可审计。

企业需要的并不是一个悬浮在页面上的通用聊天框，而是一个能够：

  • 理解当前用户和页面上下文；
  • 遵守原系统身份与权限；
  • 调用真实业务工具；
  • 分步骤执行复杂任务；
  • 在失败时纠错或停止；
  • 记录完整执行链路；
  • 支持内网和私域化部署；

的 AI Agent。

二、项目目标：让 Superset 从“看数据”走向“用自然语言执行分析”

Apache Superset 是成熟的开源 BI 平台，能够管理数据库、数据集、图表和仪表盘。但传统 BI 的主要交互方式仍然是点击、筛选和配置。

我们希望增加一个自然语言入口，让用户可以直接提出任务：

请查询现有仪表盘，返回前 5 个仪表盘的名称和发布状态。

根据刚创建的数据集生成一张月度销量趋势图，图表名称使用中文。

帮我分析华东区域本季度销售额下降的主要原因。

创建一个包含销量、销售额、库存和售后质量指标的经营看板。

Agent 不直接猜测答案，而是根据问题选择工具、读取数据、观察结果，再生成最终回答。

项目的核心定位是：

MCP-enabled Agent Sidecar Architecture

中文可以理解为：

基于 MCP 的企业 Agent 旁路服务架构

Superset 继续负责原有账号、权限、数据和 BI 能力，Agent Service 负责智能编排、安全治理、知识检索、长期记忆和运行审计。

三、为什么选择 Sidecar，而不是把 Agent 全部写进 Superset

如果把模型调用、工作流、向量数据库和运行日志全部放入原系统，会快速增加耦合度，也会让升级和扩容变得困难。

Sidecar 架构将职责拆开：

Superset
  负责用户、权限、数据集、图表、仪表盘和 SQL 能力

Agent Service
  负责大模型、任务规划、工具编排、RAG、记忆、安全和审计

整体链路如下：

Superset Web UI
      |
      | Agent Token + 用户问题 + 页面上下文
      v
FastAPI Agent Service
      |
      +-- LangGraph Runtime
      +-- Planner / ReAct / Reflection
      +-- SQL Guard / Policy Guard
      +-- RAG / Long-term Memory
      +-- Run Trace / Metrics / Audit
      |
      v
Superset MCP Server
      |
      +-- Dashboard Tools
      +-- Chart Tools
      +-- Dataset Tools
      +-- Database / SQL Tools

这种方式有几个明显优势：

  • 不需要重写现有 BI 系统；
  • Agent 可以独立部署、升级和扩容；
  • 可以接入多个 MCP Server 或业务系统；
  • 工具调用可以统一治理；
  • Agent 故障不会直接破坏核心业务系统；
  • 更适合企业分阶段试点。

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

四、执行层：Plan + ReAct + Reflection

企业任务往往不是一次模型调用能够完成的，因此项目没有采用简单的“问题进、答案出”模式，而是使用混合工作流。

1. Plan：先确定执行路线

Planner 将用户目标转换为结构化步骤。

例如用户提出：

根据销售数据创建一个区域经营看板。

Planner 可以拆成：

1. 确认数据库和目标数据集
2. 检查数据集字段与时间字段
3. 生成区域销售额图表
4. 生成月度趋势图表
5. 创建仪表盘
6. 将图表加入仪表盘
7. 返回仪表盘地址和执行结果

项目还提供 AGENT_GUIDED_MODE 开关。开启后，缺少数据库、数据集、图表类型或看板名称时，Agent 会先向用户提问，而不是盲目调用工具。

2. ReAct：边执行、边观察、边决策

ReAct 的核心循环是：

Reason -> Act -> Observe -> Reason

模型先判断需要什么信息，然后调用 MCP 工具，读取返回结果，再决定下一步。

例如：

Reason：需要先确认有哪些可用数据集
Act：调用 list_datasets
Observe：发现“销售订单”和“月末库存”数据集

Reason：需要读取销售订单字段
Act：调用 get_dataset_info
Observe：包含 order_date、region、transaction_amount

Reason：字段满足建图条件
Act：调用 generate_chart
Observe：图表创建成功并返回 chart_id

3. Reflection：关键节点自检和纠错

Reflection 不等于无限重试，而是在关键节点进行有限度检查：

  • 工具是否真正执行成功；
  • 参数错误是否可以修正；
  • SQL 是否危险；
  • 返回信息是否足够支持结论；
  • 权限错误是否应该立即停止；
  • 是否已经达到最大步骤或超时时间。

当前 Runtime 会在工具执行后检查 observation。权限拒绝和危险 SQL 会停止执行；可恢复的参数或工具错误可以交回模型修正一次，避免陷入无休止循环。

在这里插入图片描述

五、MCP：把企业系统能力变成 Agent 工具

MCP 的价值不只是统一“工具调用格式”，更重要的是为 Agent 与业务系统之间建立清晰边界。

Superset MCP 可以向 Agent 暴露：

  • 仪表盘查询、创建、更新和布局管理；
  • 图表查询、创建、预览和加入仪表盘；
  • 数据集查询、创建和字段读取；
  • 数据库、Schema 和表结构发现；
  • SQL 查询与 SQL Lab 能力；
  • 标签、主题、报表等扩展能力。

前端不会直接接触这些工具，而是先请求 Agent Service。Agent Service 校验身份、执行安全检查，再携带当前用户 Token 调用 MCP。

这样可以保留 Superset 原有权限模型，避免 Agent 变成绕过权限的“超级管理员”。

六、身份认证与数据权限

企业 AI Agent 最大的风险之一，是模型知道“用户是谁”，但工具并没有按这个用户执行。

本项目采用以下链路：

1. 用户登录 Superset
2. Superset 后端签发短期 Agent Token
3. 前端携带 Agent Token 请求 Agent Service
4. Agent Service 调用 Superset 验证接口
5. Agent 获取可信 user_id 和权限上下文
6. Agent 将用户 Token 传递给 Superset MCP
7. MCP 按当前用户权限执行工具

这里有几个安全原则：

  • 不信任浏览器直接传入的用户名和角色；
  • Token 设置较短有效期；
  • Token 不放在 WebSocket URL 中，避免进入访问日志和浏览器历史；
  • 生产环境使用 HTTPS 和 WSS；
  • Agent 不自行伪造管理员角色；
  • 业务工具权限优先委托给 Superset MCP；
  • SQL Guard 继续限制危险 SQL 和返回行数。

在这里插入图片描述

七、RAG 与长期记忆不是一回事

企业引入 Agent 后，很快会遇到两个需求：

  1. 让 Agent 理解企业自己的制度、指标口径、产品文档和操作手册；
  2. 让 Agent 记住用户上一轮创建的数据集、图表和看板。

这两个需求分别对应 RAG 和长期记忆。

RAG：检索企业知识

当前方案使用：

通义 text-embedding-v4
        +
Qdrant
        +
PostgreSQL
        +
阿里云 OSS

原始 Word、Excel、PDF、CSV、Markdown 等文件保存到对象存储；文档元数据和切片信息保存到 PostgreSQL；文本向量写入 Qdrant。检索时按用户和访问范围过滤，再把相关片段加入模型上下文。

长期记忆：跨会话找回历史上下文

每轮对话可以向量化后写入 Qdrant，并按 user_id + tenant_id 隔离。

例如用户先说：

用销售订单创建一个数据集。

下一轮再说：

根据刚才的数据集生成一张中文名称的柱状图。

Agent 可以从语义记忆和资源上下文中寻找最近的 dataset_id，减少用户重复输入。

企业版还需要继续扩展部门、项目空间、文档级 ACL、审批和知识有效期管理。

八、SQL Guard：模型生成 SQL 也必须有边界

模型能够生成 SQL，不代表 SQL 可以直接执行。

当前 SQL Guard 使用 sqlglot 解析 AST，主要限制包括：

  • 只允许只读查询；
  • 拒绝 INSERT、UPDATE、DELETE、DROP 等写操作；
  • 拒绝多语句堆叠；
  • 限制最大返回行数；
  • 拒绝无法静态约束的动态 LIMIT；
  • 避免仅通过字符串关键词造成误判。

对于生产环境，还应结合：

  • 数据库只读账号；
  • Schema 白名单；
  • 查询超时；
  • 敏感字段脱敏；
  • 行列级权限；
  • 高风险操作人工审批。

应用层 Guard 和数据库权限要同时存在，不能只依赖 Prompt。

九、可观测性：企业 Agent 必须知道“它做了什么”

普通聊天系统通常只保存问题和答案，但企业 Agent 还需要保存执行过程。

当前项目持久化：

agent_runs
agent_run_events
agent_metrics
agent_audit_logs
agent_evaluation_cases
agent_evaluation_results

可以记录：

  • 用户问题和最终回答；
  • Plan、工具发现、工具请求和工具结果；
  • Reflection 和参数修正；
  • 输入、输出和总 Token；
  • 模型、延迟、成本和错误；
  • 权限拒绝和 SQL 安全拦截；
  • 自动评估分数与证据。

这些数据既可以在单次 Run Trace 中查看，也可以接入 Superset 制作长期 Usage Dashboard，分析：

  • 每日 Agent 使用量；
  • 成功率和平均耗时；
  • 哪个模型使用最多；
  • Token 与成本趋势；
  • 哪些 MCP 工具最容易失败；
  • 哪类问题质量得分较低。

在这里插入图片描述

十、技术栈

层级 技术
Web/API FastAPI、Pydantic v2、Uvicorn、WebSocket
Agent Runtime LangGraph、OpenAI-compatible Chat API
模型 当前可使用 DeepSeek，接口层支持兼容模型切换
工具协议 Superset MCP、Streamable HTTP/SSE
数据访问 SQLAlchemy Async、asyncpg
数据库迁移 Alembic
运行数据 PostgreSQL
向量检索 Qdrant
Embedding 通义 text-embedding-v4
文件存储 阿里云 OSS，也可替换为 MinIO 或企业对象存储
缓存 Redis
SQL 安全 sqlglot
网关部署 Nginx、Docker Compose

十一、面向企业数字化转型的三种部署方式

企业不应该被迫在“全上云”和“完全离线”之间二选一。

方案一：公网体验或 SaaS 部署

适合：

  • 产品演示；
  • 非敏感公开数据；
  • 快速 PoC；
  • 中小团队验证场景。

优点是上线快、运维简单。缺点是需要严格控制上传内容和接口权限。

方案二：企业内网私域化部署

将以下组件部署在企业内网：

Superset
Agent Service
MCP Server
PostgreSQL
Qdrant
Redis
MinIO / 内部对象存储
企业模型或本地推理服务

业务数据、文档、向量和对话记录都保留在企业控制域内，适合对数据出域有严格要求的组织。

方案三：混合部署

将 Superset、MCP、数据库、向量库和知识文件保留在内网，仅通过受控网关调用外部模型 API。

在模型调用前执行：

  • 敏感字段脱敏；
  • 数据聚合；
  • 文档片段过滤；
  • 出站请求审计；
  • Token 与成本限额；
  • 允许模型白名单。

这是一种常见的折中方案：保留外部模型能力，同时尽可能减少原始数据外发。

方式 上线速度 数据控制 运维成本 适用场景
公网/SaaS 快 中 低 免费体验、PoC、公开数据
内网私域化 中 高 高 核心业务、强合规场景
混合部署 中 较高 中 大多数企业渐进式落地

十二、数据安全设计要点

AI Agent 的数据安全不能只看“模型是否私有”，还要看完整链路：

  1. 身份安全：用户身份必须由 Superset 或企业 SSO 验证。
  2. 权限安全：MCP 工具按当前用户执行，不能默认使用管理员账号。
  3. 传输安全：生产环境使用 HTTPS/WSS，Token 不进入 URL。
  4. 存储安全：数据库、向量库和对象存储均使用独立密钥和最小权限账号。
  5. 内容安全：RAG 文档和长期记忆按租户、用户、部门或项目空间隔离。
  6. 执行安全：SQL Guard、工具白名单、超时、限流和审批共同控制。
  7. 审计安全：谁在什么时间调用了什么工具、访问了什么资源，都应该可追踪。
  8. 密钥安全：密钥只放在服务器环境变量或 Secret Manager 中，不进入代码和 Git。

私域化部署不是“把服务装进内网”就结束了，而是让身份、权限、执行、存储、网络和审计形成闭环。

十三、当前实现能力与后续方向

当前版本已经具备：

  • Superset Agent Token 校验；
  • HTTP 和 WebSocket 实时对话；
  • DeepSeek 兼容模型调用；
  • Superset MCP 工具发现与调用；
  • LangGraph Planner、ReAct 和 Reflection；
  • 引导式创建任务；
  • SQL Guard 与 Policy Guard；
  • PostgreSQL Run Trace；
  • RAG 与长期语义记忆；
  • Metrics、Audit 和自动评估；
  • Usage Dashboard 数据基础；
  • Docker、Nginx 和 Alembic 部署配置。

继续企业化时，还需要重点完善：

  • 多模型路由、故障降级、限流和熔断；
  • 部门、角色、项目空间和文档 ACL；
  • 高风险写操作人工审批；
  • 更完整的固定评估集和版本回归；
  • 集中式日志、告警、备份和灾备；
  • Token 成本归因与上下文压缩；
  • 更多业务 Skill 和跨系统工作流。

这也是企业 Agent 与普通聊天 Demo 的区别：Demo 关注一次回答，企业系统关注长期稳定运行。

十四、一个适合车企的测试场景

以车企经营分析为例，可以准备：

  • 车型维度；
  • 经销商维度；
  • 销售订单；
  • 生产月报；
  • 月末库存；
  • 售后质量。

导入 Superset 后，可以让 Agent 逐步完成：

1. 查询现有数据集
2. 识别日期、区域、车型和金额字段
3. 创建销量与销售额趋势图
4. 创建区域和经销商排行图
5. 创建库存健康分析图
6. 创建售后问题帕累托图
7. 将图表加入经营分析看板
8. 返回创建结果和执行轨迹

这类任务能够同时验证 MCP 工具调用、权限、建图参数、长期记忆、错误恢复和 Run Trace。

十五、写在最后

企业数字化转型的下一步，不只是增加更多系统和报表，而是让系统能力可以被安全地理解、组合和执行。

AI Agent 真正产生价值，需要同时具备四个条件：

能理解业务
能调用真实系统
能遵守企业权限
能解释和审计每一步

Superset、MCP、LangGraph 与 Sidecar 架构提供了一条务实路线：保留企业已经建设好的数据与权限体系，在旁边增加一层可独立演进的智能执行能力。

项目支持公网体验思路，也面向企业私域化、内网和混合部署。希望免费体验的读者，可以访问官方网站了解当前开放方式：

澈析BI官网：https://www.chexi.tech

说明：免费体验范围、部署服务和功能开放情况可能调整，请以官网最新信息为准。体验环境请勿上传企业敏感数据、生产 Cookie、Token 或密钥。

# 人工智能 # graphql # AIGC # 大数据 # fastapi # 安全架构
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

端侧 AI 的 2026 下半年展望：从边缘推理到浏览器原生 AI 的能力边界

L1/L2 能力会成为标配。翻译、摘要、OCR、语音识别——这些基础 AI 能力会像今天的拼写检查一样，成为操作系统的内置功能。Chrome 的内置 AI API 就是这个趋势的一个缩影。"端云协同"是真实方向。不是"端侧替代云端"，而是"简单任务端侧、复杂任务云端"。浏览器原生 AI 处理翻译，但写一篇 3000 字的技术文章还是需要云端大模型。前者免费且即时响应，后者要 API 但提供真正的智

avatar AI Agent技术社区

API Key 创建与 OpenAPI 接入指南：让视频问答进入你的系统

这是一篇面向开发者的最小接入指南，介绍如何为 Open Video Intelligence Platform / Video AI Agent 创建 API Key，并通过最小 OpenAPI 完成视频问答、任务创建、状态查询、产物查询和用量查询。当前版本适合做系统接入验证、开发者调试台、试点项目和内部原型。它不应被理解为完整的产品 API，也不建议在对外材料中承诺成熟的大规模企业级视频处理流水

avatar AI Agent技术社区

内容涵盖关键概念、方法和实用资源：

监督学习：通过标注数据训练模型，常见任务包括分类（如SVM、决策树）和回归（如线性回归）。无监督学习：处理无标注数据，典型方法有聚类（K-Means）和降维（PCA）。隐马尔可夫模型（HMM）：包含隐含状态和观测序列，用于语音识别。强化学习：通过奖励机制优化策略，应用于游戏AI和机器人控制。根据具体需求可进一步深入特定领域（如深度学习或概率图模型）。马尔可夫性质：未来状态仅依赖当前状态。

avatar AI Agent技术社区