跳到主要内容

在 Super App 中嵌入智能体

概述

在观远 BI 超级应用(Super App)中嵌入智能体后,成员无需离开应用即可提问。例如,在销售分析页打开助手,查询销售表现并进一步分析原因。

本文使用组织 API 接入:组织配置一次,每个应用通过 Agent ID 选择智能体,对话按当前登录的 BI 用户权限执行。无需为每个智能体再生成一套凭证。若要让第三方后端持有只绑定一个智能体的凭证,参见 配置单个智能体的 API 接入。

前提条件

  • 确认目标 BI 环境已开放超级应用,并已在 DecideX 中 配置组织 BI 环境。
  • 目标 BI 环境需为 8.2 及以上版本,且已更新至支持「Agent 接入」功能的版本。具体版本要求可联系观远数据售后支持人员确认。

配置组织接入

如果目标 BI 环境的「Agent 接入」已启用,可直接 准备智能体和 SDK。

  1. DecideX 组织拥有者进入「设置 > 系统集成 > 外部接入」,填写接入名称并点击「创建接入」。

  2. 在该接入的「访问令牌」区域点击「生成新 Token」,立即复制并妥善保存,供 BI 管理员配置。令牌明文只展示一次。

  3. BI 管理员进入目标环境的「数据应用 > 超级应用 > Agent 接入」,点击「配置」,填写以下配置项后打开「启用」开关并点击「保存」。

    说明

    若页面未显示「Agent 接入」选项,请先确认满足 前提条件。

    • Decidex 地址:填写或核对目标 DecideX 实例地址,确保与生成组织访问令牌的实例一致。
    • 调用凭证:填入上一步生成的组织访问令牌。
    • 每分钟调用上限:按业务调用需求设置。

准备智能体和 SDK

  1. 确认目标智能体已发布,并已向应用使用者 授予使用权限。在 BI 的「超级应用 > Agent 接入」页面,从「当前用户可用的 Agent」列表找到目标智能体,复制 Agent ID。如果找不到,先核对 BI 环境、当前账号和智能体授权。

  2. 返回 DecideX 的智能体配置页面,在配置页的「渠道入口 > API 接入」点击「查看接入文档」。这里只需获取资料,无需点击「添加 API 接入」。

  3. 在「Agent API 接入文档」中点击「下载 SDK」和「下载文档」,保留两份文件供下一步构建。构建时参考下载的接入文档,并使用步骤 1 中复制的 Agent ID。

在应用中嵌入智能体

根据页面布局和使用需求,可选择以下嵌入形式:

  • 悬浮助手(BiAgentChatDock):适合在页面中按需展开。
  • 内嵌聊天框(BiAgentChat):适合在页面固定区域展示。

两种形式均可通过下列任一方式构建。

如果需要智能体结合页面筛选条件回答,应在应用中通过 buildContext 读取并传递实际筛选状态。SDK 不会自动识别页面上的地区、月份等筛选条件;传入上下文也不会扩大当前用户的数据权限。

通过 DecideX 对话构建

  1. 在 DecideX 新建对话,说明要修改哪个超级应用。若还没有应用,先描述要创建的页面、数据集和筛选条件,例如「用销售明细数据集创建销售分析应用,展示月度销售额,支持按大区和月份筛选」。

  2. 在同一对话上传 SDK 和接入文档,提供 Agent ID、助手位置及需要传给智能体的页面信息。例如:

    在销售分析页右下角添加悬浮助手。使用附件中的 DecideX SDK,Agent ID 为「替换为实际 ID」。每次提问时,把页面当前选中的大区和月份一起传给智能体。

  3. 应用构建并发布后,从回复中的应用链接打开结果,使用业务成员账号 验证接入效果。

使用 Codex 等工具构建

  1. 用编程工具打开 Super App 工程。若需新建工程,先按 超级应用快速入门 准备本地环境和发布账号。

  2. 将 SDK 和接入文档放入工具可读取的目录,要求它按当前实例的示例安装 SDK、嵌入组件并传入实际 Agent ID。例如:

    在销售概览页右侧嵌入聊天框,Agent ID 为「替换为实际 ID」。按接入文档使用 BiAgentChat;通过 buildContext 将页面上已选的地区传给智能体。

    |370

  3. 完成构建和打包,将应用发布到目标 BI 环境。本地预览可用于检查布局;登录身份、实际对话和权限需在已发布应用中验证。

验证接入效果

发布后,使用实际业务成员账号登录目标 BI 环境并打开应用,依次检查:

  1. 提问与续聊:打开悬浮助手或内嵌聊天框,发送一个简单问题,确认能收到回复;在同一会话中继续追问,确认能延续对话。
  2. 页面筛选条件:如果已配置 buildContext,切换地区、月份等筛选条件后再次提问,核对智能体使用的条件是否与当前页面一致。若不一致,检查应用是否在每次发送时读取最新筛选状态。
  3. 成员权限:分别使用具有不同智能体使用权限、BI 数据权限的业务账号验证。获授权成员应能正常对话和访问权限范围内的数据;未获授权成员不应获得相应智能体或数据的访问权限。

若无法开始对话,先检查 BI「Agent 接入」中的实例地址、调用凭证和启用状态,再核对当前账号的智能体授权及 BI 环境配置。