嵌入方式
iframe、Kit 组件、Hosted 页和 API 四种嵌入方式怎么选。
把服务型智能体交给你的终端用户有四种方式。它们共用同一套嵌入令牌，差别在谁来渲染界面、你要写多少代码。
| iframe | Kit 组件 | Hosted 页 | API | |
|---|---|---|---|---|
| 谁渲染界面 | Praxis（页内框架） | Praxis 的 <praxis-agent>，在你的页面里 | Praxis（独立页面，用户被跳转过去） | 你自己 |
| 外观在哪配置 | 控制台 | 前端 setOptions（布局、启动按钮、标题、欢迎语、输入框） | 控制台 | 完全自定 |
| 代码量 | 后端签发 + 一行标签 | 后端签发 + 前端十几行 | 后端签发 + 302 跳转 | 后端签发 + 自建全部界面与事件流 |
| 适合场景 | 想最快上线、外观不需要深度定制 | 要和宿主页面融合：浮窗、侧栏、控制打开、监听事件 | 使用独立对话页，由宿主验证身份后跳转 | 自有 App、非网页载体、完全自定义体验 |
| 当前状态 | 可用 | 可用 | 可用 | 可用 |
怎么选
- 最快嵌入网页：用 iframe 加载器；需要在宿主代码里定制组件时用 Kit。
- 用 React：用
@deepractice-ai/praxis-kit-react，它把<praxis-agent>包成<PraxisAgent>和usePraxisAgent()。 - 不是网页，或界面必须完全自己画：用 API，自己签发令牌，用会话和事件接口收发消息。接口见 API 参考。
- 独立对话页：用 Hosted，由后端签发后跳转。
iframe 一行接入
先按快速开始配置来源白名单和后端 POST /api/praxis-token，返回 { token, expires_at }。把下面一行放进宿主页面，将 ABC123 换成智能体短号：
<script src="https://kit-develop.praxisusercontent.com/v1/loader.js" data-agent="ABC123" data-token-endpoint="/api/praxis-token" async></script>加载器用 POST 请求你的令牌接口，并携带浏览器凭据；后端必须从登录态确定用户。API Key 只留在后端。
| 属性 | 用法 |
|---|---|
data-agent | 必填，5–8 位字母数字短号，不是 agent_… ID |
data-token-endpoint | 必填，宿主签发端点，返回 { token, expires_at } |
data-layout | 可选，inline、popup、sidebar、modal |
data-launcher | 可选，bubble、none，或宿主按钮的 CSS 选择器 |
不写 data-layout / data-launcher 时，使用控制台保存的外观；写入时覆盖对应设置。外观尚未设置布局时，加载器默认 popup。
直接 iframe 地址为 https://chat-develop.praxisusercontent.com/a/ABC123。地址本身不提供登录用户凭证；用上面的加载器完成令牌传递。页面的 frame-ancestors 来自来源白名单；宿主还需允许 chat 域名的 frame-src，见安全。
期望：刷新宿主页后看到保存的外观，发送消息后收到回复。
Hosted 托管页
像 Stripe Checkout 一样：宿主后端验证用户身份，签发时设置 hosted: true，再向浏览器返回 302，Location 为返回的 hosted_url。完整示例和一次性凭证规则见嵌入令牌。Hosted 与 iframe 共用控制台保存的外观。
Kit 组件
Kit 是一个自定义元素，界面渲染在 Shadow DOM 里，宿主样式不会影响对话界面。布局有 inline、sidebar、popup、modal，启动按钮有 none、bubble、mascot。接入步骤见嵌入到网页。
React 示例：
import { PraxisAgent, usePraxisAgent } from "@deepractice-ai/praxis-kit-react";
const options = {
api: { url: "https://api-develop.deepraxis.com" }, // 正式地址上线后替换
agent: { name: "好物集客服" },
};
export function Support() {
const { ref, control } = usePraxisAgent();
return (
<PraxisAgent
ref={ref}
options={options}
getToken={async () => {
const response = await fetch("/api/praxis-token", { method: "POST" });
if (!response.ok) throw new Error("Token unavailable");
return (await response.json()).token;
}}
layout="popup"
launcher="bubble"
onReady={() => control.open()}
/>
);
}control 提供 open、close、toggle、sendUserMessage、setThreadId、setComposerValue、showHistory、hideHistory、focusComposer。就绪事件之前调用会抛错。事件有 praxis.ready、praxis.error、praxis.thread.change、praxis.response.start、praxis.response.end、praxis.open、praxis.close 等。
注意
layout 和 launcher 通过属性（props）或 options 设置，在 React 绑定里不要写成 HTML 属性。API
API 方式没有现成界面。你的后端签发令牌，客户端用令牌调用会话与事件接口；终端用户令牌只能访问自己名下的会话。适合需要自画界面的场景。