@rongcloud/embed-agent-studio-sdk

一个用于嵌入融云 ChatAgentStudio 的 JavaScript SDK，支持在网页中动态加载和管理融云 ChatAgentStudio 的 iframe 组件。

安装

npm install @rongcloud/embed-agent-studio-sdk

环境要求

• 现代浏览器，支持 URL、URLSearchParams、fetch 和 postMessage
• SDK 仅支持浏览器环境，不应在 SSR 服务端直接执行 init() 或 open()
• iframe 容器必须具有明确高度，否则嵌入页面可能不可见

快速开始

<div id="agent-studio" style="width: 100%; height: 720px"></div>

import AgentStudioSDK from "@rongcloud/embed-agent-studio-sdk";

AgentStudioSDK.on("ready", () => {
  console.log("Agent Studio 已就绪");
});

AgentStudioSDK.on("authFailed", () => {
  console.log("鉴权失效，请获取新 Token");
});

AgentStudioSDK.on("error", ({ type, message }) => {
  console.error(type, message);
});

AgentStudioSDK.init({
  // 填写 Agent Studio 的实际访问地址；如部署在 /embed 下，应包含该前缀。
  baseUrl: "https://example.com/embed",
  container: "#agent-studio",
  token: "your-token",
  RCAppkey: "your-app-key",
  RCRegion: "domestic",
  appId: "your-app-id",
  authUrl: "https://example.com/auth",
});

AgentStudioSDK.open({
  path: "/agent/agents",
});

初始化参数

init(options) 接收以下参数：

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | baseUrl | string | 是 | Agent Studio 的访问地址，需要包含实际部署前缀 | | container | HTMLElement \| string | 是 | iframe 容器元素或可被 document.querySelector 识别的选择器 | | token | string | 是 | Embed 鉴权 Token | | RCAppkey | string | 是 | 融云 AppKey | | RCRegion | string | 否 | 服务区域，例如 domestic、overseas 或 qa | | appId | string | 否 | AppInfo ID | | authUrl | string | 否 | 自定义鉴权服务地址 |

baseUrl 与 open({ path }) 会直接拼接。建议 baseUrl 不以 / 结尾，并始终让 path 以 / 开头。

API

init(options): void

初始化 SDK 并绑定容器。重复初始化会先销毁当前 iframe、通信监听和事件监听器。

当字符串选择器无法匹配容器时，init() 会抛出异常。

open(params?): void

创建并打开 iframe。

AgentStudioSDK.open();
AgentStudioSDK.open({ path: "/resources/workflows" });

iframe 已打开且传入新 path 时，SDK 会通过 postMessage 通知子应用进行站内导航，不会重新创建 iframe。iframe 已打开但未传入 path 时，会重新创建 iframe。

updateToken(token): void

更新 SDK 内保存的 Token，并通知已打开的子应用：

AgentStudioSDK.updateToken("new-token");

调用前必须已执行 open()。

switchApp(params): void

切换当前应用信息。子应用收到消息后可能刷新页面：

AgentStudioSDK.switchApp({
  RCAppkey: "new-app-key",
  RCRegion: "domestic",
});

调用前必须已执行 open()。

on(event, handler): void

订阅事件：

const handleReady = () => console.log("ready");

AgentStudioSDK.on("ready", handleReady);
AgentStudioSDK.off("ready", handleReady);

destroy(): void

移除 iframe 和跨窗口消息监听，清空初始化参数及全部事件监听器：

AgentStudioSDK.destroy();

状态属性

| 属性 | 类型 | 说明 | | --- | --- | --- | | isInitialized | boolean | 是否已执行初始化 | | isOpened | boolean | iframe 是否已打开 |

事件

| 事件 | 参数 | 说明 | | --- | --- | --- | | ready | 无 | 子应用初始化完成 | | authFailed | 无 | 子应用请求出现 401/403 鉴权失败 | | error | { type: string; message: string } | SDK 调用或菜单请求失败 | | destroyed | 无 | SDK 已销毁；触发后全部监听器会被清空 |

当前错误类型包括：

| 类型 | 说明 | | --- | --- | | not_initialized | 调用方法前未完成初始化 | | not_opened | 调用方法前 iframe 未打开 |

License

MIT