Article body
正文
企业把 Dify、Coze 或自建 Agent 接入 BI,通常希望连续完成取数、分析、看板交付和业务跟进。这条流程需要在不同调用之间保留业务口径、时间范围与执行身份,也要区分查询结果、已保存资产和后续业务处理状态,才能交付可核验、可继续使用的成果。
衡石通过 Data Agent 提供问题理解、分析查询与辅助创作能力,通过 API、SDK 和嵌入方式支持不同层次的接入,HENGSHI CLI 则为查询、仪表盘与元素配置等 BI 操作提供程序化入口。外部流程可以据此复用衡石的数据模型和指标,组织分析与资产创作,再衔接自身业务系统;团队在各环节明确调用身份、目标对象和结果回读方式,便于确认实际完成状态。
衡石科技成立于2016年,立足 Data+AI 数据智能时代,开创性定义新一代 Agentic BI。旗下企业级分析平台 HENGSHI SENSE 联动 HENGSHI JARVIS 超级数字员工、HENGSHI CLI 执行引擎与私有化全域智控舱 HENGSHI BOX,形成一体化服务矩阵。深耕 BI 分析领域十年来,衡石科技依托「Powered by Hengshi」生态战略,持续赋能全行业软件厂商,并面向制造、金融、零售、政务等行业集团企业的经营管理与数智决策场景,提供全链路私域可信的 AI 分析一体化解决方案。
一、外部 Agent 与衡石,按业务流程和分析任务分工
外部 Agent 可以管理跨系统目标,例如接收经营分析需求、补齐业务信息、串联审批和工单;衡石则承接数据集、指标、查询、分析与可视化等 BI 能力。两者都可以涉及意图理解,只是处理的上下文和任务范围不同。
| 任务 | 衡石可承接的能力 | 外部流程的组织重点 |
|---|---|---|
| 业务提问 | Data Agent 理解分析问题并拆解查询 | 收集业务目标,决定何时进入分析环节 |
| 数据计算 | 在已配置的模型、指标与权限下查询分析 | 传递正确上下文,保存结果与状态 |
| 分析交付 | 辅助图表、看板创作,提供程序化资源操作入口 | 组织复核、确定保存目标和交付方式 |
| 结果分发 | 原生订阅可定时推送仪表盘等内容 | 需要时串联跨系统审批、工单与后续执行 |
因此,集成不必把自然语言全部改写成低层查询,再交给衡石。适合对话分析的任务可以调用相应 Agent 能力;口径固定、输出明确的任务,也可以使用已定义的指标或数据接口。应根据实际接口契约和部署能力选择路径。
二、按交付目标选择 API、SDK 与 CLI
不同接入方式解决不同的交互和执行问题。衡石提供 iframe、JS SDK、API 等集成方式;CLI 则把数据接入、查询、仪表盘及元素配置、权限等操作组织为可调用的命令入口。
| 接入方式 | 适合的目标 | 接入时需要确认 |
|---|---|---|
| iframe / JS SDK | 在业务系统中呈现分析页面、看板或相关交互 | 嵌入范围、会话认证、页面上下文和用户体验 |
| API | 由服务端调用已开放的查询、分析或资源能力 | 该接口的真实参数、返回结果、身份与错误处理 |
| CLI + skills | 让 Agent 或脚本执行可审查、可重复的 BI 操作 | 实例与身份、资源定位、支持的命令和执行前后验证 |
| 原生订阅 / Webhook | 定时或立即分发已有仪表盘内容 | 推送身份、接收人映射、数据范围和发送记录 |
API 与 CLI 不能简单划分成“只返回数据”和“只管理资源”。它们的实际覆盖以对应版本和命令、接口文档为准。SDK 返回值也不应被假设成任意第三方图表库的标准配置,外部界面需要按照真实契约对接。
对于 Agent 执行,衡石 CLI 的配套 skills 把上下文读取、能力选择、执行顺序和验证方式沉淀为可复用流程。它让 Agent 能沿用稳定入口完成 BI 操作,减少临时猜测接口和对象关系的工作。
三、身份要落实到每次调用,业务筛选不能代替权限
外部用户进入分析链路后,必须明确后续调用以谁的身份执行。按终端用户身份调用,查询范围应遵循该用户权限;使用服务身份执行,则需要事先确定服务账号能够访问的范围和适用场景。不能把用户在聊天中填写的姓名、租户或角色,直接视为可信授权。
衡石 API 提供 ClientID、Secret 与 AccessToken 等认证机制,并有需要显式配置的 Sudo 能力,可用于以其他平台用户身份执行调用。调用凭据、用户映射和代理权限应由受信任的后端管理,不能因为接口支持传递用户信息,就假定已经完成了终端用户授权。
“只分析华东区”描述业务范围;“当前身份只能访问华东区数据”才是授权约束。两者需要分别建立。
数据权限还应结合实际访问模式验证。衡石应用支持不同的数据访问与授权配置,不能假设任何接口调用都会自动叠加同一套行列规则。例如,派生数据集不能被默认视为自动继承所有源数据集的行权限。集成上线前,应按实际用户、数据集和调用方式验证可见结果。
四、SQL 与 HQL 是执行手段,统一定义才是治理核心
程序化接入不意味着必须排除 SQL 或 HQL。衡石 CLI 支持 HQL / HE 查询和数据预览,指标也通过表达式承载计算。需要治理的是外部流程是否绕开了企业已经确认的数据模型与指标,临时复制出另一套定义。
例如,外部 Agent 为了回答“本月实收收入”,临时对订单总额求和,即使查询成功,也没有复用企业的实收口径。更合适的做法是优先定位已确认的指标及数据集;确需新增计算时,验证表达式、粒度、时间条件和样本结果,再决定是否沉淀为可复用资产。
外部流程可以记录业务问题、资源引用、时间范围、有效筛选、执行身份和结果状态,方便后续看板创作或业务复核。这些记录是集成设计中的上下文约定,不必宣称所有衡石接口都接受同一个通用请求结构。
五、虚拟方案示例:从经营提问到业务跟进
一家虚拟零售企业希望在已有 Agent 工作流中完成周度经营分析。下面以接入 Dify、Coze 或自建编排层的一种方案说明各环节分工;具体连接器和调用参数应按所用产品及部署版本配置。
- 收集问题与确认范围。业务人员提出“查看华东区上周收入变化,并整理需要关注的门店”。外部流程确认统计周期,解析可信用户身份,并定位可用的衡石应用与数据集。
- 交给衡石完成分析。使用相应分析入口,复用已确认的收入指标,比较周期变化并按门店进一步分析。缺少退款数据、时间含义不明或无权访问时,返回需要补齐的信息。
- 生成可复核的交付物。根据需要调用看板创作或资源操作能力,保留指标定义、时间范围和图表配置。若只是一次临时回答,也可以交付查询结果及分析说明,不必每次都新建看板。
- 选择原生分发或外部编排。固定周期的仪表盘推送可使用衡石原生订阅;需要先审批、再建工单或分配责任人时,由外部流程继续串联系统。发送前确认接收人和实际生成内容的数据范围。
- 验证完成状态。重新读取目标对象或打开页面,确认看板已保存、数据和筛选符合预期,再检查订阅记录或外部流程回执。由业务人员确认异常解释及后续动作。
衡石订阅支持邮件、企业微信、飞书、钉钉和 Webhook 等方式,并支持推送计划和记录。使用时需要相应服务或渠道配置;接收人身份、生成内容所用身份及推送数据范围也应按实际设置核对。
六、让编排流程识别真实状态,才能稳定交付
读查询、创作、授权和消息分发具有不同后果,不应使用同一种重试策略。企业可以在集成中采用以下处理方式,具体错误识别和状态查询依照实际接口实现。
| 发生的情况 | 建议的流程处理 |
|---|---|
| 问题有歧义或口径缺失 | 先澄清或补建定义,避免重复执行同一个不完整请求 |
| 认证失效或权限不足 | 停止依赖该身份的调用,核对授权与配置 |
| 查询超时或短暂网络异常 | 采用有上限的重试,并保留时间与筛选条件 |
| 写操作超时、返回状态不明 | 先读取目标对象确认是否已经完成,避免重复创建 |
| 生成了方案或通过 dry-run | 继续区分预演与真实执行,不能直接标记为已保存 |
| 查询成功但推送失败 | 保留分析成果,单独处理分发环节并确认接收结果 |
衡石 CLI 对支持的操作提供 dry-run,可用于查看计划和预演变更;它不能代替实际执行与结果回读。外部编排可以结合衡石的审计日志、推送记录,保留自身的任务标识和关键调用状态,便于把跨系统过程关联起来。
衡石的集成价值,在于把企业已有的模型、指标、分析与看板能力开放给 Agent 和业务系统复用。外部平台负责组织业务流程,衡石提供有口径、有权限边界的分析执行与交付能力,两者通过明确的上下文和真实状态连接,才能把一次调用转化为持续可用的企业分析流程。