嵌入到网页

五分钟把服务型智能体放进你的网页：后端签发令牌，前端加载 Kit 组件。

本页带你把一个服务型智能体放进自己的网页，让登录用户直接在页面里和它对话。你需要一个 Praxis API Key、一个网站后端和一个前端页面。

本页用 Kit 组件完成接入。一行 iframe 和 Hosted 跳转的用法见嵌入方式。所有示例使用 develop 环境。

工作方式

浏览器里的页面不持有 API Key。你的后端用 API Key 为当前登录用户签发一张短期令牌，前端的 Kit 组件拿这张令牌与智能体对话。

浏览器 ──(你的登录态)──▶ 你的后端 ──(API Key)──▶ POST /agent/v1/embed_tokens
   ▲                                                      │
   └──────────── { id, token, expires_at } ◀──────────────┘
浏览器（Kit）──(token)──▶ Praxis API

1. 在控制台准备智能体

在 Console 新建一个服务型智能体，写好指令并保存。
为它设置嵌入策略：选择运行环境，在允许的来源里添加你的网站来源（如 https://shop.example.com）；本地调试可允许 localhost。
记下智能体的 id（形如 agent_…）或短号。

期望：嵌入策略保存成功，来源列表里能看到你的网站。没有嵌入策略的智能体不能签发令牌。

2. 后端签发令牌

用 API Key 调 POST /agent/v1/embed_tokens。API Key 只放在后端，不要写进前端代码。

// 你的后端，以 fetch 为例
const API = "https://api-develop.deepraxis.com"; // 正式地址上线后替换

export async function issueToken(userId: string) {
  const response = await fetch(`${API}/agent/v1/embed_tokens`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PRAXIS_API_KEY}`, // 占位：你的 API Key
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent: "agent_xxx",       // 换成你的智能体 id 或短号
      external_user_id: userId, // 你系统里这位用户的稳定 ID
    }),
  });
  if (!response.ok) throw new Error("token request failed");
  const { token, expires_at } = await response.json();
  return { token, expires_at };
}

把它挂在你自己的登录保护之后，例如 POST /api/praxis-token：先确认用户已登录，再用登录态里的用户 ID 签发，不要信任前端传来的用户 ID。

期望：Praxis 返回 HTTP 200 和 { id, token, expires_at }；你的宿主端点返回 { token, expires_at }，expires_at 为 ISO 8601 时间。字段规则见嵌入令牌与终端用户。

3. 前端加载 Kit

<script type="module">
  import "/praxis-kit.js"; // Kit 的构建产物，由你的站点提供

  const agent = document.createElement("praxis-agent");
  agent.setAttribute("layout", "popup");
  agent.setAttribute("launcher", "bubble");
  agent.setOptions({
    api: {
      url: "https://api-develop.deepraxis.com", // 正式地址上线后替换
      getToken: async (current) => {
        const response = await fetch("/api/praxis-token", { method: "POST", credentials: "same-origin" });
        if (!response.ok) throw new Error("客服暂时不可用，请稍后重试");
        return (await response.json()).token;
      },
    },
    agent: { name: "好物集客服" },
    startScreen: { greeting: "你好，有什么可以帮你？" },
  });
  document.body.appendChild(agent);
</script>

api.url 填 API 域名，也可以是完整的 /agent/v1 地址。
getToken(current) 由 Kit 在需要令牌时调用，参数是当前令牌（首次为 null），返回令牌字符串。令牌只保存在内存里。
setOptions 把字段合并进当前配置；移除元素会取消进行中的流。
在 React 里使用 @deepractice-ai/praxis-kit-react 的 <PraxisAgent>，见嵌入方式。

期望：页面右下角出现气泡，点开后能发送消息并收到回复；浏览器里没有 praxis.error 事件。

完整样例

仓库里的「好物集」演示站（apps/kit-demo）是一个可运行的完整宿主：假登录、/api/praxis-token 签发端点、把会员等级作为上下文随令牌传入，以及挂载 Kit 的前端。

常见问题

签发返回「Agent not found」：智能体必须是服务型、未归档、属于你的 API Key 所在组织。
签发返回 INVALID_PARAMS「embed policy not configured」：智能体还没有嵌入策略。
签发返回 EMBED_USER_BLOCKED：该 external_user_id 在智能体的封禁名单里。
组件无法对话：确认页面来源在「允许的来源」里，且 api.url 与签发令牌用的是同一个环境。

下一步：选择嵌入方式 · 令牌细节 · 传入上下文