集成与上线
网页嵌入
把一个智能体、一个集群或一个仪表板发布到你自己的站点上——那里的访客是匿名的，这会改变你需要考虑的问题。
打开 配置 → 网页嵌入。你创建一枚 嵌入密钥 ，对应一个智能体、集群或仪表板，把它限定到你掌控的域名，再把代码片段粘贴到你的页面里。
如何配置
- 1
选择要暴露什么
每枚密钥对应一个智能体、一个集群或一个已发布的仪表板。不同投放位置用不同密钥——它们可以各自独立撤销。 - 2
限定域名
精确列出允许加载它的来源——www.example.com,docs.example.com。凡是背后有真实数据的密钥，绝不要把这一项留空。 - 3
设置过期时间
密钥可以带过期日期，之后也能撤销或轮换。一次活动用的密钥，应该比活动本身多活几天，而不是几年。 - 4
复制代码片段
一个 iframe 或 script 标签。把它粘贴到组件该出现的位置。
html
<iframe
src="https://your-instance.example.com/embed/agent/emk_xxxxxxxxxxxxxxxx"
style="width:100%;height:600px;border:0"
title="Support assistant"
></iframe>密钥前缀为 emk_。URL 路径段与资源类型对应： /embed/agent/<key>, /embed/swarm/<key> 或 /embed/bi/<key>.
嵌入密钥的每个字段
| 字段 | 默认值 | 说明 |
|---|---|---|
| 名称 | — | 1 到 80 个字符。你自己的标签；不会展示给访客。 |
resource_type | — | 取值为 agent, swarm, bi_dashboard之一。创建时确定，之后不可改。 |
allowed_domains | empty | 允许加载它的来源。留空表示不做任何域名限制——请务必填写。 |
allow_ai | false | 仪表板嵌入专用：查看者是否可以使用「问 AI」追问。默认关闭，因为每个问题都是一次记在你账上的模型调用。 |
is_active | true | 关掉它即可停用该投放位置，而不必删除密钥。 |
transcript_retention_days | 30 | 1 到 3650。嵌入会话在被定时清理之前保留多久。 |
expires_at | null | 可选的过期时间。 |
use_count | 0 | 已服务的请求数——只读，便于发现被遗弃的投放位置。 |
last_used_at | null | 只读。 |
匿名访客能触及什么
这部分值得说准确。
| 方面 | 行为 |
|---|---|
| 身份 | 没有。不存在登录；每个访客都是匿名的。 |
| 数据访问 | 访客自己没有任何数据权限。智能体运行在所有者的知识与数据上，并被显式限定在该所有者范围内。 |
| 模型成本 | 计入密钥所有者的工作区，走所有者的提供商密钥。 |
| 工具 | 仅限底层智能体已启用的那些——嵌入不会增加任何能力。 |
| 护栏 | 该智能体的护栏照常生效，包括对输入和输出的个人敏感信息处理。 |
嵌入是一个公开面
智能体能读到的一切，访客都可以要求它说出来——包括通过写一段试图把它劝离原有指令的提示词。发布之前先问自己：如果一个陌生人向这个智能体索取它知道的全部内容，会返回什么？只挂上可以对外公开的集合和表，只启用外人可以触发的工具。
访问控制是怎么强制的
- 域名白名单
- 请求会带上由浏览器设置的 Origin 请求头，页面脚本无法伪造它；不在你的清单里就会被拒绝。这能阻止你的密钥被人抄走用在别人站点上——但它是浏览器层面的控制，不是身份认证：非浏览器客户端想发什么请求头都可以。
- 密钥生命周期
- 密钥会记录最后一次使用的时间和来源 IP，可以设过期，也可以撤销或轮换。轮换会保留新旧之间的关联，这样你能看出是谁替换了谁。
- 速率与并发限制
- 按密钥的限制能削弱抓取行为和失控循环。
- 预算上限
- 密钥可以带自己的消费上限——参见 预算。在公开端点上，这就是「糟糕的一天」与「糟糕的账单」之间的区别。
会话记录与保留期
嵌入会话会被记录下来，方便你看到大家问了什么、智能体怎么答的。每枚密钥都有一个 会话记录保留期 窗口（默认 30 天，可设 1 到 3650）；定时清理会删掉更早的记录。
请慎重设置。访客可能把个人信息敲进一个公开的对话框，而在仍能满足你需要的前提下，窗口越短越对。脱敏护栏可以在数据被保存或发给提供商之前把可识别的个人信息剔掉——参见 护栏与 PII.
嵌入的仪表板
一个已发布的 仪表板 也可以用同样的方式嵌入。组件在输出时会被净化，因此底层查询和连接细节不会暴露——但页面上的每个数字，谁加载了这个页面谁都看得到。
嵌入中的可视化回答
如果该智能体启用了 可视化 BI 回答 ，嵌入的对话可以在文字之外返回一张图表。由于访客没有任何数据权限，图表是在服务端用所有者的数据生成的，并以所有者作为强制的租户边界。
单个访客能消耗多少
发布前值得了解，因为正是这些数字挡在一个好奇的访客——或一个发现了这个组件的爬虫——与你的提供商账单之间。它们在服务端强制执行、在 Postgres 里计数，因此在所有应用实例间统一生效，而不是各进程各算一份。
| 上限 | 取值 | 范围 |
|---|---|---|
| 对话请求 | 每分钟 30 次，超出返回 429 | 按嵌入密钥 |
| 仪表板「问 AI」请求 | 每分钟 10 次，超出返回 429 | 按嵌入密钥 |
| 解析（组件加载） | 每分钟 60 次 | 按嵌入密钥 |
| 单次会话中的消息数 | 60 | 按请求计 |
| 会话体量 | 20 万字符 | 按请求计 |
| 消费 | 你设的上限，超出返回 402，前提是 ENFORCE_BUDGET_CAP 已开启 | 按嵌入密钥，也按用户 |
速率限制约束的是速度，不是总量
每分钟三十次对话请求，如果有东西持续猛打，一天大约是 43000 次。速率限制挡住的是突发；真正能管住整个月的只有 给密钥设的预算上限 。两个都要设——而且要在嵌入可访问之前就设好上限，不是等第一次被账单惊到之后。
集群嵌入是在访客浏览器里编排的
图在客户端运行，但每个节点的调用只带上该节点的 id ——服务端会从你保存的集群里重新读取该节点真实的提供商、模型、提示词和工具。访客无法选择更贵的模型、无法改动提示词，也碰不到你没发布的节点。含人工审批步骤的集群会被直接拒绝嵌入，因为匿名访客永远没法放开那道关卡。
发布前检查清单
- 域名已限定到你掌控的站点。
- 智能体上只挂了可对外公开的知识集合与表。
- 工具已收窄到陌生人可以触发的范围。
- 护栏已开启；如果访客可能输入个人信息，还要开启个人敏感信息脱敏。
- 已给该密钥设了预算上限。
- 会话记录保留期是你能说清理由的那个值。
- 已在嵌入里实测过：要求该智能体说出它的指令和它知道的一切，看会返回什么。