---
url: /v6.2/copilot-sdk.md
---
# Data Agent 集成总览

在决定使用 `iframe`、`JS SDK` 还是 `API` 之前，建议先把两个问题想清楚：

1. 当前数据问答由谁持续推进？
2. 你们希望以什么形式把能力接进自己的系统？

第一个问题决定“运行方式”，第二个问题决定“接入方式”。

只有先把运行方式想清楚，后面的前后端职责、会话归属和页面边界才会自然清楚。

## 第一步：先判断运行方式

### Agent 模式

Agent 模式更适合“代理式”的数据问答体验。

它的特点是：

* 一次提问发起后，系统会持续推进当前问答，而不是只做一次简单请求
* 过程中会逐步产生状态变化、推理过程、工具调用和图表结果
* 更适合需要连续执行、逐步反馈、保留 Agent 行为特征的场景

如果你们是在浏览器里直接嵌入聊天能力，那么这部分运行时会随前端嵌入能力一起工作。

如果你们是在后端系统里接入能力，但又希望保留 Agent 模式，我们也提供了 Node.js 版 Agent 服务，用来在服务端承接这类运行方式。

### Workflow 模式

Workflow 模式更适合“后端统一托管”的数据问答体验。

它的特点是：

* 一次提问发起后，执行过程主要由后端工作流服务负责推进
* 前端更像是发起请求、读取状态和展示结果的界面层
* 更适合希望由后端统一管理执行逻辑、权限边界和交付稳定性的场景

更容易理解的差别是：

* Agent 模式：更像“一个持续工作的智能代理”
* Workflow 模式：更像“一个由后端托管执行的智能流程”

## 第二步：再选择接入方式

在运行方式确定之后，再看你们想怎么接入。

### 1. iframe

适合希望最快复用完整页面的场景。

特点：

* 直接嵌入一个现成可用的完整页面
* 聊天界面、历史记录、结果卡片、图表展示都由衡石提供
* 你们自己的前端改动最少
* 如果父页面已经使用 Copilot JS SDK，也可以只把仪表盘放进 iframe，并由父页面 Copilot 接管 iframe 内的智能助理能力

适合：

* 想最快上线
* 不打算自己实现聊天界面
* 接受直接复用完整页面体验

### 2. JS SDK

适合希望保留自己页面壳，但复用衡石前端能力的场景。

特点：

* 页面布局、入口、交互壳仍然由你们自己掌控
* 问答结果、图表和聊天窗口能力可以嵌入到你们页面中
* 既可以嵌完整聊天窗，也可以只嵌一条结果卡片
* 可以作为父页面 Copilot，接管 iframe 仪表盘里的“智能解读”和 Agent 操作

适合：

* 你们已经有自己的业务页面
* 不想自己实现完整的数据问答渲染体验
* 希望在“自有页面”里复用衡石前端能力

### 3. API

适合希望把衡石作为后端能力接入的场景。

特点：

* 你们自己负责系统编排、页面展示和业务整合
* 衡石负责提供数据问答能力接口
* 前端是否使用衡石现成渲染层，可以单独再决定

适合：

* 已经有自己的后端编排、多 Agent、AI 网关或工作流系统
* 希望把衡石接成一项能力，而不是整页 UI
* 希望自己控制接入链路和产品形态

## 把两件事合在一起看

| 运行方式 | 接入方式 | 谁主要负责持续推进问答 | 你们拿到的是什么 |
|---|---|---|---|
| Agent | iframe | 嵌入页里的 Agent 运行时 | 一整页现成体验 |
| Agent | JS SDK | 页面中嵌入的 Agent 运行时 | 自有页面壳 + 嵌入式聊天能力 |
| Agent | JS SDK + iframe 仪表盘 | 父页面 Copilot SDK | 自有页面壳 + iframe 仪表盘 + 父页面统一接管智能助理 |
| Agent | API | 你们部署的 Node.js Agent 服务 | 可在后端调用的 Agent 能力 |
| Workflow | iframe | 衡石后端工作流服务 | 一整页现成体验 |
| Workflow | JS SDK | 衡石后端工作流服务 | 自有页面壳 + 后端托管执行 + 前端结果渲染 |
| Workflow | API | 衡石后端工作流服务 | 纯后端能力接入 |

## 最重要的不是“选哪个名词”，而是“先选哪种责任边界”

建议按这个顺序判断：

### 先问：谁来持续推进问答？

* 如果你们希望后端统一托管执行，优先考虑 Workflow 模式
* 如果你们希望保留更强的 Agent 行为和连续执行过程，优先考虑 Agent 模式

### 再问：你们想接入一整页、前端能力，还是后端能力？

* 想最快复用完整页面：看 [iframe 集成](copilot-sdk-iframe.md)
* 想保留自己的页面壳：看 [JS SDK 集成](copilot-sdk-js.md)
* 想把衡石接成后端能力：看 [API 集成](copilot-sdk-api.md)

## 最容易混淆的三个问题

### 1. API 不等于 Workflow

API 只是接入方式。

你们既可以通过 API 接 Workflow 能力，也可以在需要时接入 Node.js 版 Agent 服务，让后端侧同样使用 Agent 模式。

### 2. JS SDK 不只是“一个渲染器”

JS SDK 承载的是前端嵌入能力。

如果当前使用的是 Workflow 模式，它更像“页面里的结果展示层”。

如果当前使用的是 Agent 模式，它还会承接当前问答在前端侧的运行过程。

### 3. iframe 不代表运行方式不存在

iframe 只是把复杂性封装在完整页面里。

你们虽然不需要自己实现这些逻辑，但在做方案选型、认证、后端集成和问题排查时，仍然需要知道当前运行的是 Agent 还是 Workflow。

## 推荐阅读顺序

1. 先读这篇总览，理解“运行方式”和“接入方式”是两件事
2. 再读 [API 集成](copilot-sdk-api.md)，理解后端接入时的边界
3. 再读 [JS SDK 集成](copilot-sdk-js.md)，理解前端嵌入时的边界
4. 最后读 [iframe 集成](copilot-sdk-iframe.md)，理解完整页面嵌入的边界