Agent 外部嵌入
将 Poco Agent 的完整对话、历史记录与产物预览安全嵌入第三方系统。
适用场景
Agent 外部嵌入用于把 Agent 工作台中已经配置好的 Agent 放入业务系统。嵌入窗口复用 Poco 的消息渲染与产物预览能力，并自动适配宿主容器大小。
它与“API 访问”是两套独立能力：API 访问提供协议接口；外部嵌入提供可直接使用的对话页面、历史对话和产物浏览。
权限和数据边界
- 第三方页面必须为当前用户提供有效的 Poco 登录 token。任何未禁用的已登录用户都可以成为 Agent 使用者，不要求是 Agent 创建者。
- 对话历史按
Agent + 访问用户隔离。访问用户只能读取自己通过外部嵌入创建的会话。 - Agent 指令、模型、MCP、技能、浏览器和产物读取使用 Agent 创建者已经配置的能力与权限，执行用量计入创建者。
- 外部嵌入会话不参与长期记忆的保存、检索或提示词注入，也不会进入普通对话列表、工作台、自动发布、产物推荐和 WebHook。
- SDK 通过
postMessage将登录 token 交给 Poco iframe，iframe 直接使用该 token 调用外嵌接口。token 只保存在 iframe 内存中，不会写入 URL 或浏览器存储。
在 Agent 工作台启用
- 打开 Agent 工作台，在目标 Agent 的“更多”菜单中选择“外部嵌入”。
- 设置欢迎语。
- 添加允许嵌入的完整来源，例如
https://portal.example.com。 - 开启“启用外部嵌入”并保存。
- 在“效果预览”确认欢迎页、历史对话、消息和产物预览。
允许来源只接受 http 或 https origin，不能包含路径、查询参数、用户凭据、片段或通配符。默认端口会被归一化，例如 https://example.com:443 等价于 https://example.com。
Script 标签接入
<script src="https://poco.example.com/embed/poco-agent-embed.js"></script>
<script>
const widget = PocoAgentEmbed.mount({
agentId: "<agent-id>",
getAccessToken: () => window.yourAuth.getAccessToken(),
});
// widget.open();
// widget.close();
// widget.destroy();
</script>通过 Poco 域名加载脚本时，SDK 会自动推断 baseUrl。
npm 接入
包发布后安装：
pnpm add @ripperts/poco-agent-embedimport { mountAgentEmbed } from "@ripperts/poco-agent-embed";
const widget = mountAgentEmbed({
baseUrl: "https://poco.example.com",
agentId: "<agent-id>",
getAccessToken: () => yourAuth.getAccessToken(),
theme: "system",
position: "bottom-right",
defaultOpen: false,
draggable: true,
});仓库中的 npm 包源码位于 frontend/packages/agent-embed。发布静态脚本前执行：
cd frontend
pnpm sync:agent-embed-sdk固定容器模式
传入 target 后，SDK 不创建悬浮按钮，iframe 会填满指定容器：
<div id="agent-chat" style="height: 640px"></div>
<script>
PocoAgentEmbed.mount({
agentId: "<agent-id>",
target: "#agent-chat",
getAccessToken: () => window.yourAuth.getAccessToken(),
});
</script>SDK 参数
| 参数 | 必填 | 说明 |
|---|---|---|
agentId | 是 | Agent 工作台中的 Agent ID |
getAccessToken | 是 | 返回当前用户 Poco 登录 token 的同步或异步函数 |
baseUrl | npm 必填 | Poco Web 地址；Script 方式可从脚本地址自动推断 |
target | 否 | DOM 元素或选择器；设置后使用固定容器模式 |
language | 否 | 页面语言，默认读取宿主页面 lang |
theme | 否 | light、dark 或 system |
position | 否 | 悬浮入口位置，默认 bottom-right |
defaultOpen | 否 | 是否默认展开悬浮窗口 |
draggable | 否 | 是否允许拖动悬浮入口，默认允许 |
openIcon / closeIcon | 否 | 图片 URL、DOM Node 或返回 Node 的函数 |
onError | 否 | 鉴权或嵌入错误回调 |
getAccessToken 会在首次鉴权以及接口返回 401 后调用。第三方系统应返回当前用户仍然有效的最新 Poco 登录 token，不要返回 Agent 创建者 token，也不要把 token 固定写在前端代码中。通过 OpenAPI 获取的登录 token 默认有效期为 24 小时，普通网页登录 token 也可以直接使用。
CSP 和反向代理
宿主系统使用 CSP 时，至少允许 Poco 来源：
Content-Security-Policy: script-src 'self' https://poco.example.com; frame-src https://poco.example.com反向代理必须转发以下路径：
/embed/poco-agent-embed.js/{language}/embed/agents/{agent_id}/api/v1/agent-embeds/*
嵌入页面的 API 和 SSE 都从 iframe 内同源访问 Poco，不要求把每个客户域名加入后端 CORS。
如果反向代理统一添加了 X-Frame-Options 或 Content-Security-Policy: frame-ancestors 'self'，需要对 /{language}/embed/agents/* 路径移除该限制，否则浏览器会拒绝第三方页面加载 iframe。