← 返回 技术博客

技术文章

让外部 Agent 调用企业级 BI:衡石的 API、CLI 与分析交付实践

通过 API、SDK、CLI 与原生订阅连接外部 Agent,保留指标、身份和真实执行状态,交付可核验的分析结果。

2026/11/17技术博客HENGSHI4 分钟阅读
Agentic BIHENGSHI SENSE

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 或自建编排层的一种方案说明各环节分工;具体连接器和调用参数应按所用产品及部署版本配置。

  1. 收集问题与确认范围。业务人员提出“查看华东区上周收入变化,并整理需要关注的门店”。外部流程确认统计周期,解析可信用户身份,并定位可用的衡石应用与数据集。
  2. 交给衡石完成分析。使用相应分析入口,复用已确认的收入指标,比较周期变化并按门店进一步分析。缺少退款数据、时间含义不明或无权访问时,返回需要补齐的信息。
  3. 生成可复核的交付物。根据需要调用看板创作或资源操作能力,保留指标定义、时间范围和图表配置。若只是一次临时回答,也可以交付查询结果及分析说明,不必每次都新建看板。
  4. 选择原生分发或外部编排。固定周期的仪表盘推送可使用衡石原生订阅;需要先审批、再建工单或分配责任人时,由外部流程继续串联系统。发送前确认接收人和实际生成内容的数据范围。
  5. 验证完成状态。重新读取目标对象或打开页面,确认看板已保存、数据和筛选符合预期,再检查订阅记录或外部流程回执。由业务人员确认异常解释及后续动作。

衡石订阅支持邮件、企业微信、飞书、钉钉和 Webhook 等方式,并支持推送计划和记录。使用时需要相应服务或渠道配置;接收人身份、生成内容所用身份及推送数据范围也应按实际设置核对。

六、让编排流程识别真实状态,才能稳定交付

读查询、创作、授权和消息分发具有不同后果,不应使用同一种重试策略。企业可以在集成中采用以下处理方式,具体错误识别和状态查询依照实际接口实现。

发生的情况建议的流程处理
问题有歧义或口径缺失先澄清或补建定义,避免重复执行同一个不完整请求
认证失效或权限不足停止依赖该身份的调用,核对授权与配置
查询超时或短暂网络异常采用有上限的重试,并保留时间与筛选条件
写操作超时、返回状态不明先读取目标对象确认是否已经完成,避免重复创建
生成了方案或通过 dry-run继续区分预演与真实执行,不能直接标记为已保存
查询成功但推送失败保留分析成果,单独处理分发环节并确认接收结果

衡石 CLI 对支持的操作提供 dry-run,可用于查看计划和预演变更;它不能代替实际执行与结果回读。外部编排可以结合衡石的审计日志、推送记录,保留自身的任务标识和关键调用状态,便于把跨系统过程关联起来。

衡石的集成价值,在于把企业已有的模型、指标、分析与看板能力开放给 Agent 和业务系统复用。外部平台负责组织业务流程,衡石提供有口径、有权限边界的分析执行与交付能力,两者通过明确的上下文和真实状态连接,才能把一次调用转化为持续可用的企业分析流程。

HENGSHI SENSE

丰富的资源 完整的生态

邀您成为衡石伙伴

立即加入

企业级部署、产品集成与试用咨询均可快速响应