# 嵌入方式 (/docs/cloud/services/agent/embed/methods)



把服务型智能体交给你的终端用户有四种方式。它们共用同一套[嵌入令牌](/docs/cloud/services/agent/embed/tokens)，差别在谁来渲染界面、你要写多少代码。

|        | 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 参考](/docs/api/native/agent)。
* **独立对话页**：用 Hosted，由后端签发后跳转。

## iframe 一行接入 [#iframe-一行接入]

先按[快速开始](/docs/cloud/services/agent/embed/quickstart)配置来源白名单和后端 `POST /api/praxis-token`，返回 `{ token, expires_at }`。把下面一行放进宿主页面，将 `ABC123` 换成智能体短号：

```html
<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`，见[安全](/docs/cloud/services/agent/embed/security)。

期望：刷新宿主页后看到保存的外观，发送消息后收到回复。

## Hosted 托管页 [#hosted-托管页]

像 Stripe Checkout 一样：宿主后端验证用户身份，签发时设置 `hosted: true`，再向浏览器返回 302，`Location` 为返回的 `hosted_url`。完整示例和一次性凭证规则见[嵌入令牌](/docs/cloud/services/agent/embed/tokens)。Hosted 与 iframe 共用控制台保存的外观。

## Kit 组件 [#kit-组件]

Kit 是一个自定义元素，界面渲染在 Shadow DOM 里，宿主样式不会影响对话界面。布局有 `inline`、`sidebar`、`popup`、`modal`，启动按钮有 `none`、`bubble`、`mascot`。接入步骤见[嵌入到网页](/docs/cloud/services/agent/embed/quickstart)。

React 示例：

```tsx
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` 等。

<Callout title="注意">
  `layout`

   和 

  `launcher`

   通过属性（props）或 

  `options`

   设置，在 React 绑定里不要写成 HTML 属性。
</Callout>

## API [#api]

API 方式没有现成界面。你的后端签发令牌，客户端用令牌调用会话与事件接口；终端用户令牌只能访问自己名下的会话。适合需要自画界面的场景。

下一步：[嵌入到网页](/docs/cloud/services/agent/embed/quickstart) · [嵌入令牌与终端用户](/docs/cloud/services/agent/embed/tokens)