Data Agent 集成总览
在决定使用 iframe、JS SDK 还是 API 之前，建议先把两个问题想清楚：
- 这次数据问答由谁持续推进？
- 你们希望以什么形式把能力接进自己的系统？
第一个问题决定“运行方式”，第二个问题决定“接入方式”。
只有先把运行方式想清楚，后面的前后端职责、会话归属和页面边界才会自然清楚。
第一步：先判断运行方式
Agent 模式
Agent 模式更适合“代理式”的数据问答体验。
它的特点是：
- 一次提问发起后，系统会持续推进这次问答，而不是只做一次简单请求
- 过程中会逐步产生状态变化、推理过程、工具调用和图表结果
- 更适合需要连续执行、逐步反馈、保留 Agent 行为特征的场景
如果你们是在浏览器里直接嵌入聊天能力，那么这部分运行时会随前端嵌入能力一起工作。
如果你们是在后端系统里接入能力，但又希望保留 Agent 模式，我们也提供了 Node.js 版 Agent 服务，用来在服务端承接这类运行方式。
Workflow 模式
Workflow 模式更适合“后端统一托管”的数据问答体验。
它的特点是：
- 一次提问发起后，执行过程主要由后端工作流服务负责推进
- 前端更像是发起请求、读取状态和展示结果的界面层
- 更适合希望由后端统一管理执行逻辑、权限边界和交付稳定性的场景
更容易理解的差别是：
- Agent 模式：更像“一个持续工作的智能代理”
- Workflow 模式：更像“一个由后端托管执行的智能流程”
第二步：再选择接入方式
在运行方式确定之后，再看你们想怎么接入。
1. iframe
适合希望最快复用完整页面的场景。
特点：
- 直接嵌入一个现成可用的完整页面
- 聊天界面、历史记录、结果卡片、图表展示都由衡石提供
- 你们自己的前端改动最少
适合：
- 想最快上线
- 不打算自己实现聊天界面
- 接受直接复用完整页面体验
2. JS SDK
适合希望保留自己页面壳，但复用衡石前端能力的场景。
特点：
- 页面布局、入口、交互壳仍然由你们自己掌控
- 问答结果、图表和聊天窗口能力可以嵌入到你们页面中
- 既可以嵌完整聊天窗，也可以只嵌一条结果卡片
适合：
- 你们已经有自己的业务页面
- 不想自己实现完整的数据问答渲染体验
- 希望在“自有页面”里复用衡石前端能力
3. API
适合希望把衡石作为后端能力接入的场景。
特点：
- 你们自己负责系统编排、页面展示和业务整合
- 衡石负责提供数据问答能力接口
- 前端是否使用衡石现成渲染层，可以单独再决定
适合：
- 已经有自己的后端编排、多 Agent、AI 网关或工作流系统
- 希望把衡石接成一项能力，而不是整页 UI
- 希望自己控制接入链路和产品形态
把两件事合在一起看
| 运行方式 | 接入方式 | 谁主要负责持续推进这次问答 | 你们拿到的是什么 |
|---|---|---|---|
| Agent | iframe | 嵌入页里的 Agent 运行时 | 一整页现成体验 |
| Agent | JS SDK | 页面中嵌入的 Agent 运行时 | 自有页面壳 + 嵌入式聊天能力 |
| Agent | API | 你们部署的 Node.js Agent 服务 | 可在后端调用的 Agent 能力 |
| Workflow | iframe | 衡石后端工作流服务 | 一整页现成体验 |
| Workflow | JS SDK | 衡石后端工作流服务 | 自有页面壳 + 后端托管执行 + 前端结果渲染 |
| Workflow | API | 衡石后端工作流服务 | 纯后端能力接入 |
最重要的不是“选哪个名词”，而是“先选哪种责任边界”
建议按这个顺序判断：
先问：谁来持续推进这次问答？
- 如果你们希望后端统一托管执行，优先考虑 Workflow 模式
- 如果你们希望保留更强的 Agent 行为和连续执行过程，优先考虑 Agent 模式
再问：你们想接入一整页、前端能力，还是后端能力？
最容易混淆的三个问题
1. API 不等于 Workflow
API 只是接入方式。
你们既可以通过 API 接 Workflow 能力，也可以在需要时接入 Node.js 版 Agent 服务，让后端侧同样使用 Agent 模式。
2. JS SDK 不只是“一个渲染器”
JS SDK 承载的是前端嵌入能力。
如果当前使用的是 Workflow 模式，它更像“页面里的结果展示层”。
如果当前使用的是 Agent 模式，它还会承接这次问答在前端侧的运行过程。
3. iframe 不代表运行方式不存在
iframe 只是把复杂性封装在完整页面里。
你们虽然不需要自己实现这些逻辑，但在做方案选型、认证、后端集成和问题排查时，仍然需要知道当前运行的是 Agent 还是 Workflow。