开始使用

选择你需要的服务

每项服务都有独立的快速开始、使用指南与 API。

智能体

定义职责、提供资料并运行任务。由智能体服务管理底层能力调用。

模型

通过统一接口调用模型，生成文本、处理多模态输入。

沙箱

在隔离环境中执行代码、操作文件和使用浏览器。

搜索

查询所需信息，获取搜索结果与来源。

管理你的云服务

API

智能体 / 模型 / 沙箱 / 搜索 —— 查阅请求参数、响应结构、错误码与代码示例。需要验证调用时，在当前页面展开调试面板，配置并发送请求。

浏览所有 API →

前提

一个 Praxis 账号。新注册账号自带 $1 免费额度，跑完本页绰绰有余，不需要先充值。

1. 创建 API Key

在 控制台 → API Keys 创建一个 Key。名称必填，有效期默认 90 天，创建后立即复制保存。

2. 发出第一个请求

只需要一个地址：https://api.deepraxis.ai。用你已有的 SDK，把 base_url 指过来即可。

示范模型 deepseek-flash：便宜、快、中英文都好。

curl https://api.deepraxis.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-flash", "messages": [{"role": "user", "content": "你好"}]}'

用你熟悉的语言也行：

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepraxis.ai/openai/v1",
    api_key="sk-praxis-你的Key",
)

completion = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "你好"}],
)
print(completion.choices[0].message.content)

Node

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepraxis.ai/openai/v1",
  apiKey: process.env.PRAXIS_API_KEY,
});

const res = await client.chat.completions.create({
  model: "deepseek-flash",
  messages: [{ role: "user", content: "你好" }],
});
console.log(res.choices[0].message.content);

3. 读懂响应

响应的 choices[0].message.content 是回复文本。usage 里有 token 数——注意 cost 字段直接给出本次调用的费用。

然后打开 控制台 → 用量与费用：你刚才这一次调用已经记在那里了。

下一步

• 接入方式：Claude Code、Codex、Cherry Studio……
• 模型目录：可用模型与定价
• 流式响应 · 错误与重试

Praxis Cloud 提供多个服务域。你的场景决定用哪个——很多场景只需要一个。

模型（Model）

你要做什么：调用大语言模型（对话、写作、翻译、代码、分析）。

怎么用：通过 OpenAI 或 Anthropic 兼容 API 直接调用。把现有代码的 base_url 指向 Praxis 即可。

适合：已有应用要加 AI 能力、写 SDK 代码、接入第三方工具（Cursor、Cherry Studio 等）。

→ 模型快速开始 · 模型目录

智能体（Agent）

你要做什么：让 AI 在云端持续工作——有上下文、有记忆、能调用工具。

怎么用：通过 Agent API 创建会话、发送事件、获取回复。智能体可以记住之前的对话、执行多步任务。

适合：构建 AI 助手、客服机器人、有状态的工作流。

→ 智能体快速开始

沙箱（Sandbox）

你要做什么：在安全隔离的环境中运行代码。

怎么用：通过 Sandbox API 创建沙箱实例，上传代码并执行，获取结果。

适合：代码执行、自动化测试、数据处理管道。

→ 沙箱快速开始

搜索（Search）

你要做什么：给 AI 提供网络搜索能力。

怎么用：通过 Search API 执行搜索，返回结构化结果。

适合：构建有实时信息能力的 AI 应用。

→ 搜索快速开始

怎么选

不确定的话：从模型开始——最简单、最直接，3 分钟就能跑通。

理解这几个概念，使用 Praxis 会更顺手。

一个 Key，所有服务

Praxis Cloud 的所有服务（模型、智能体、沙箱、搜索）共用同一个 API Key。你不需要为不同服务创建不同的 Key——一个 Key 就够了。

兼容协议

Praxis 提供两种协议入口，你已有的代码不需要换库：

• OpenAI 兼容（https://api.deepraxis.ai/openai/v1）——OpenAI SDK 改 base_url 即用
• Anthropic 兼容（https://api.deepraxis.ai/anthropic）——Anthropic SDK 改 base_url 即用

两种协议背后的模型池是同一个——你可以在 OpenAI 协议下调 Claude 模型，也可以在 Anthropic 协议下调 DeepSeek 模型。

模型与路由

Praxis 聚合多家供应商的模型，统一以一个 API 提供。每个模型 ID 背后是具体的供应商路由——你不需要关心用的是哪家的服务，只需要选对模型 ID。

两种模型 ID：

• 滚动入口（如 deepseek-flash）——始终指向最新一代，升级时无需改代码
• 版本快照（如 deepseek-v4-flash）——固定在某一个版本，适合需要可复现性的场景

按次计费

每次 API 调用按实际 token 用量计费。输入和输出 token 分别计价，推理模型的思维链 token 也计费。不调用不收费——没有月费、没有最低消费。

API 响应中的 usage.cost 字段直接返回本次调用的费用，你可以在应用里实时追踪成本。

想深入某个服务？

• 选择服务——四域对比
• 第一个请求——3 分钟跑通
• 术语表——15 个核心术语

让智能体回答产品问题、查询业务数据或完成工具任务。你配置模型、指令与工具，Praxis 管理会话执行和事件记录；你的应用决定谁可以使用、哪些业务操作可以执行。

适用对象与结果

给已有产品接入助手时，可以使用现成对话界面，把用户身份和当前页面带入会话。需要完全自定义交互、后台任务或非网页客户端时，使用 API 创建会话并读取事件。业务数据通过你授权的工具取得，订单权限仍由业务服务器核验。

如果只需要一次模型调用，或希望自己编写模型与工具循环，从模型服务开始。智能体服务适合希望复用配置、持续对话并追踪任务过程的应用。

对象如何关联

服务智能体面向你的客户，每个会话使用独立环境；个人智能体绑定持久电脑。本文的接入指南围绕服务智能体展开，详细关系见智能体与会话。公开智能体 ID 形如 agent_…，应直接使用创建或查询响应中的值。

选择交付形态

React 是使用 Kit 的一种方式。公开资料问答可使用匿名访客接入；需要账户数据时，由宿主后端验证登录身份再签发令牌。完整比较见选择接入方式。

按任务继续

• 修改回答范围、模型和版本：配置智能体。
• 让助手了解当前页面并调用业务能力：传入上下文、配置工具授权。
• 排查客户问题：查看会话与用量、管理终端用户。
• 准备上线：测试嵌入接入、上线检查清单。

下一步：API 参考 · 文档问答配方 · 限制与错误

用 API 建立一段服务智能体对话，并从事件中验证真实回复。本页只在服务端运行，不需要网页组件或嵌入策略。

准备 Bun 或支持原生 fetch 的 Node.js、Develop 组织的 API Key，以及该组织可用的 deepseek-flash 模型和余额。在服务端进程设置 PRAXIS_API_KEY；密钥创建见API Key。如果你的 Key 属于其他环境，先统一 API 地址、组织和模型，不能混用环境。

1. 创建智能体

新建 first-agent.mjs，从下面的代码开始。后续三段 JavaScript 按顺序追加到同一个文件，不要分别执行。助手只回答一个算术问题，便于判断首次调用是否完成；业务工具在接通后再添加。

POST /agent/v1/agents 使用名称、类型、模型和指令创建配置。tools: [] 不声明额外工具。请求辅助函数为每次调用检查状态并设置超时，失败时只输出状态和请求标识，不打印 Key。

import assert from "node:assert/strict";
import { setTimeout as delay } from "node:timers/promises";

const { PRAXIS_API_KEY } = process.env;
assert(PRAXIS_API_KEY, "Set PRAXIS_API_KEY in the server process");
const base = "https://api-develop.deepraxis.com/agent/v1";
async function request(path, body) {
  const response = await fetch(`${base}${path}`, {
    method: body === undefined ? "GET" : "POST",
    headers: {
      Authorization: `Bearer ${PRAXIS_API_KEY}`,
      "Content-Type": "application/json",
    },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    signal: AbortSignal.timeout(30_000),
  });
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}; request=${response.headers.get("X-Request-Id") ?? response.headers.get("request-id")}`);
  }
  return response.json();
}
const agent = await request("/agents", {
  name: "First support agent", kind: "service", model: "deepseek-flash",
  system: "Answer the user's question briefly. Do not use tools for this exercise.",
  tools: [],
});
assert(agent.id.startsWith("agent_"));
console.log({ agent: agent.id, version: agent.version });

预期结果： 创建响应为 HTTP 200，包含公开 id 和 version。运行脚本时会打印这两个值，后续直接复用，不手写猜测 ID。

2. 建立会话

追加以下代码。POST /agent/v1/sessions 把刚创建的版本固定在会话中。省略 environment_id 使用轻型机器；这一步不需要先创建沙箱。示例显式设置 100 美分的会话预算，不把预算金额当作预计费用。

const session = await request("/sessions", {
  agent: { type: "agent", id: agent.id, version: agent.version },
  title: "First API conversation",
  budget: { type: "limit", max_list_cost: { amount: "100", currency: "USD" } },
});
assert(session.id);
console.log({ session: session.id });

预期结果： HTTP 201，响应包含会话 id。此时还没有发送用户问题；即使状态为 idle，也不代表已经得到回复。预算决定后续请求能否继续，不保证生成特定答案。

3. 发送第一条消息

追加以下代码，调用 POST /agent/v1/sessions/{session_id}/events。events 是输入数组；这里发送一条 user.message，其中只有一个非空文本块。

const accepted = await request(`/sessions/${session.id}/events`, {
  events: [{ type: "user.message", content: [{ type: "text", text: "What is 2 + 2?" }] }],
});
assert(accepted.data.some(event => event.type === "user.message"));

预期结果： HTTP 200，data 中出现已接收的用户事件。这是接收确认；不要把它当作智能体答案，也不要因为暂时没有答案就再次发送同一条消息。

4. 读取并验证回复

追加以下代码，然后执行 node first-agent.mjs 或 bun first-agent.mjs。它用 GET /agent/v1/sessions/{session_id}/events 分页读取事件，先找到 agent.message，再找到其后的 session.status_idle。初始空闲状态不会被误判为成功。

let completed = false;
const deadline = Date.now() + 120_000;
while (Date.now() < deadline) {
  const events = [];
  let page;
  do {
    const query = new URLSearchParams({ order: "asc", limit: "100" });
    if (page) query.set("page", page);
    const result = await request(`/sessions/${session.id}/events?${query}`);
    events.push(...result.data);
    page = result.next_page;
  } while (page && Date.now() < deadline);
  const reply = events.findIndex(event => event.type === "agent.message");
  const idle = events.findIndex((event, i) => i > reply && event.type === "session.status_idle");
  if (reply >= 0 && idle > reply) {
    const text = events.filter(event => event.type === "agent.message")
      .flatMap(event => event.content ?? []).filter(block => block.type === "text")
      .map(block => block.text).join("\n");
    assert(text.trim(), "Expected a nonempty reply");
    console.log({ reply: text, completed: true });
    completed = true;
    break;
  }
  await delay(1500);
}
assert(completed, `No completed reply before timeout; inspect session ${session.id}`);

完成判定： 进程正常退出，输出非空 reply 和 completed: true，答案应表达 4。脚本的 120 秒是本例等待期限，不是服务运行上限。只通过文本非空断言还不足以验证业务答案；上线前为实际问题准备预期结果。

失败时检查

重新运行整份脚本会新建智能体和会话。排错时优先查询已输出的 ID。测试记录可在确认不再需要后按 API 参考处理，不要把仍在运行的会话当作可直接删除的记录。

下一步

继续配置智能体、了解智能体与会话，或用 PraxisKit 接入网页。

交给你的代理：

按 /docs/developers/agent/quickstart 在服务端运行首次对话。
需要我提供 Develop 组织 API Key，并确认 deepseek-flash 可用。
完成标准：收到非空 agent.message，其后出现 session.status_idle。
不要把 Key 放进浏览器或日志；记录智能体 ID、版本和会话 ID。

智能体是一份可复用的配置，会话是使用这份配置开展的一段独立对话。先区分这两个对象，才能判断修改指令会影响谁、消息应该发到哪里，以及如何验证任务结束。

配置与运行对象

服务智能体为每段会话使用独立运行环境。个人智能体绑定持久电脑，适合保留工作目录的任务；两种类型的选择在创建时确定。API 起步使用服务智能体，不需要先准备个人电脑。

版本与会话生命周期

保存智能体配置会创建新版本。创建会话时，agent 可以是 ID 字符串，表示取当时最新版本；也可以是 { type: "agent", id, version }，明确选择版本。会话固定这份配置，之后修改智能体不会把已有会话换到新版本。

会话可以处于 idle、running、rescheduling 或 terminated 状态。idle 表示当前没有运行中的任务，可以继续发送消息；terminated 会话不能继续运行。归档是另一项状态：记录仍可查询，但不能继续发送消息。保留记录与停止接收输入是不同需求，清理前先判断需要哪一种。

发送 user.message 得到成功响应，只说明输入被接收。读取 agent.message 才能取得回复；观察其后的 session.status_idle 才能判断这一轮已经回到空闲。需要用户批准工具时，应处理待确认事件，不能将等待确认误判为接口无响应。

环境与身份边界

API 创建会话省略 environment_id，且未选择电脑时，使用轻型机器；选择环境时使用对应沙箱配置。环境配置在会话创建时固定。会话的文件和工具能力取决于配置，不应仅凭“环境”这个名字推断支持任意运行时。

组织 API Key 留在服务端。面向终端用户的网页使用嵌入令牌，由宿主后端从已验证登录态确定 external_user_id，再为指定智能体签发。令牌限定智能体、版本及终端用户的访问范围；前端自己填写用户 ID 不能建立可信身份。

公开资料问答可使用可公开 key 获取匿名访客令牌。同一浏览器存储延续匿名身份；这不等于登录账户，也不授予访问订单或其他私有资料的权限。用户切换时销毁旧组件并重新取得凭证，不能只清空消息列表。

工具确认表达用户是否同意本次操作。你的订单或业务服务仍须验证调用凭据和当前用户的资源权限；页面上下文、模型参数和“允许执行”按钮都不能代替这一步。指令和上下文也不适合保存秘密。

选择下一步

第一次验证 API，用运行第一个智能体。要修改配置或选择嵌入版本，读配置智能体；创建与更新请求的字段以 API 参考为准。

接入客户产品时，先选交付形态，再按嵌入令牌与用户接好身份。出现执行问题时，从查看会话与用量定位记录，再按限制与错误处理。

选择对话出现的位置，再决定由谁编写界面。PraxisKit、iframe 和 Hosted 提供对话界面；API 适合自己实现界面的应用。

比较接入方式

按任务选择

需要在网页里调整组件、控制打开时机或连接页面交互时，选择 Kit。Kit 是 Web Component，也能在 React 应用里挂载；你在宿主代码中设置界面选项。

只想插入现成对话界面、把外观交给控制台维护时，选择 iframe。这里的“一行”指加载脚本，登录用户的后端签发端点仍需实现。复制一个裸 iframe 地址不能代替身份验证。

希望用户点按钮进入独立页面时，选择 Hosted。宿主后端为当前用户生成短期链接，浏览器立即跳转；不需要在宿主页安装组件。每次进入都重新取得链接，不能把用户的链接作为公共入口分享。

已有自己的聊天界面，或要从非网页应用接入时，选择 API。产品快速开始先带你从服务端跑通一次会话；向终端用户开放时，再按令牌指南隔离每个人的访问权限。

准备身份与配置

登录用户接入需要一个服务智能体、保存的嵌入策略，以及能够验证宿主登录态的后端。API Key 留在后端；浏览器只取得当前终端用户的嵌入令牌。更换界面形态不应改变你为同一个用户分配的稳定标识。

公开问答站不要求登录时，可选 Kit 的匿名访客接入：使用可公开 key，由 Kit 获取匿名令牌。匿名身份不能代替你的账户登录，也不能据此开放订单等账户数据，见嵌入令牌与用户。

嵌入策略和持久化外观目前只能在控制台配置。Kit 的实例外观则由宿主代码设置。先选一种形态跑通真实问答，再增加上下文、工具或主题。

下一步

• 嵌入到网页：完成后端签发、挂载与双用户验证。
• 嵌入令牌与用户：选择身份方式并处理刷新与吊销。
• 智能体 API 参考：查会话与事件操作。
• Cookbook：查看完整应用场景。

在你的网页中加入 PraxisKit，让登录用户与服务智能体对话。本页用本地订单助手跑通后端签发、前端挂载和身份隔离；其他形态见选择接入方式。

准备 Bun、一个可用的服务智能体及运行环境，以及同组织的 API Key。示例连接 Develop，API Key 仅存为后端环境变量 PRAXIS_API_KEY。浏览器登录宿主后，由宿主核验身份、向 Praxis 签发令牌，再把令牌交给 Kit。

1. 准备智能体

在 Develop 控制台进入服务智能体，选择已有智能体。在接入与配置 → 配置 → 指令保存指令；在配置 → 安全选择运行环境，打开允许 localhost，点保存安全设置。本页宿主页为 http://localhost:4242。请使用专用测试智能体，来源白名单暂留空，仅启用 localhost；令牌继承非空 HTTPS 来源列表时，本地请求会被拒绝。上线到 HTTPS 网站时，添加该网站的来源。

嵌入策略目前只能在控制台配置。复制公开智能体 ID（agent_…）备用。页面显示“已保存，不产生新版本”后，继续实际签发；保存提示本身不能证明对话可用。

2. 创建签发端点

新建目录，把代码保存为 server.ts。这是仅绑定本机的演示服务器，用 HTTP Basic 验证两个测试账户。DEMO_PASSWORD 是你自行设置的测试密码，与 Praxis API Key 无关。服务器从验证成功的账户取用户 ID，不读取浏览器提交的用户 ID。

import { timingSafeEqual } from "node:crypto";

const apiKey = process.env.PRAXIS_API_KEY;
const agentId = process.env.PRAXIS_AGENT_ID;
const password = process.env.DEMO_PASSWORD;
if (!apiKey || !agentId || !password) throw new Error("Set the three server variables");
const origin = "http://localhost:4242";
const noStore = { "Cache-Control": "no-store" };
function authenticate(request: Request): string | undefined {
  const supplied = Buffer.from(request.headers.get("Authorization") ?? "");
  for (const id of ["customer_123", "customer_456"]) {
    const expected = Buffer.from("Basic " + Buffer.from(`${id}:${password}`).toString("base64"));
    if (supplied.length === expected.length && timingSafeEqual(supplied, expected)) return id;
  }
}
Bun.serve({
  hostname: "127.0.0.1", port: 4242,
  async fetch(request) {
    const url = new URL(request.url);
    if (url.origin !== origin) return new Response("Use localhost:4242", { status: 403 });
    const userId = authenticate(request);
    if (!userId) return new Response("Sign in", {
      status: 401, headers: { ...noStore, "WWW-Authenticate": 'Basic realm="Local demo"' },
    });
    if (request.method === "GET" && url.pathname === "/") {
      return new Response(Bun.file("index.html"), { headers: noStore });
    }
    if (request.method !== "POST" || url.pathname !== "/api/praxis-token") {
      return new Response("Not found", { status: 404 });
    }
    if (request.headers.get("Origin") !== origin) {
      return new Response("Origin rejected", { status: 403 });
    }
    try {
      const response = await fetch("https://api-develop.deepraxis.com/agent/v1/embed_tokens", {
        method: "POST",
        headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
        body: JSON.stringify({ agent: agentId, external_user_id: userId }),
        signal: AbortSignal.timeout(30_000),
      });
      if (!response.ok) return new Response("Token issuance failed", {
        status: response.status, headers: noStore,
      });
      const data = await response.json();
      if (typeof data.token !== "string" || typeof data.expires_at !== "string") {
        throw new Error("Invalid token response");
      }
      return Response.json({ token: data.token, expires_at: data.expires_at }, { headers: noStore });
    } catch {
      return new Response("Token service unavailable", { status: 502, headers: noStore });
    }
  },
});
console.log(origin);

将三个环境变量放入服务端进程；PRAXIS_AGENT_ID 替换为实际 ID。启动前还需在下一步保存 index.html。

export PRAXIS_AGENT_ID="agent_REPLACE_ME"
# Set PRAXIS_API_KEY and DEMO_PASSWORD in this server process, then run:
bun server.ts

期望：终端输出本地网址。未认证请求被宿主拒绝；已认证且同源的请求才会调用 Praxis。Praxis 签发成功返回 HTTP 201；宿主端点只返回 token、expires_at，并禁止缓存。

接入已有应用时，将 authenticate 替换为应用的会话验证，把路由接在登录与 CSRF 保护之后，保留每次签发的身份核验。不要将本地测试账户机制用于线上登录。有效期和刷新见嵌入令牌与用户。

3. 挂载组件

选择一种前端实现。API 地址、CDN 和智能体必须属于同一环境；以下固定使用 Develop 的 Kit 0.2.8。

<!doctype html>
<html lang="zh">
<meta charset="utf-8">
<title>Order assistant</title>
<script type="module" src="https://kit-develop.praxisusercontent.com/v0.2.8/praxis-kit.js" integrity="sha384-vey+VZZcFIWJq9Fmv/nmLxspKtXRiL8XiDOfg2g2QFvwZi5MA+tkiQvPBtoMS8eU" crossorigin="anonymous"></script>
<praxis-agent style="display:block;height:600px;width:100%"></praxis-agent>
<p id="status" role="status"></p>
<script type="module">
  await customElements.whenDefined("praxis-agent");
  const agent = document.querySelector("praxis-agent");
  agent.addEventListener("praxis.error", () => {
    document.querySelector("#status").textContent = "Chat unavailable. Check your sign-in and configuration.";
  });
  agent.setOptions({
    api: {
      url: "https://api-develop.deepraxis.com",
      getToken: async () => {
        const response = await fetch("/api/praxis-token", {
          method: "POST", credentials: "same-origin", cache: "no-store",
        });
        if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
        const data = await response.json();
        if (typeof data.token !== "string" || !data.token) throw new Error("Missing token");
        return data.token;
      },
    },
    agent: { name: "Order assistant" },
  });
</script>
</html>

期望：页面出现高度为 600 像素的对话区。api.url 指定 API 地址，getToken 返回令牌字符串，agent.name 是界面名称。等待元素注册后再调用 setOptions。praxis.ready 只表示组件挂载；必须收到真实回复才能证明接入成功。

4. 验证接入

1. 打开 http://localhost:4242，用 customer_123 和所设测试密码登录。发送“你好，请介绍你能帮助处理的订单问题”，确认收到回复。
2. 在网络面板检查宿主令牌请求成功，响应没有 API Key；会话请求使用嵌入令牌。不要把令牌复制到日志或截图。
3. 用独立浏览器配置或无痕窗口登录 customer_456，期望看不到第一个账户的会话。不能用两个同登录态的标签页代替此检查。
4. 不带凭据请求本地签发端点，验证宿主返回 HTTP 401。已有应用还应验证退出登录后不能再签发。

curl --silent --output /dev/null --write-out "%{http_code}\n" \
  -X POST http://localhost:4242/api/praxis-token \
  -H "Origin: http://localhost:4242"

失败时检查

以下是接口定义的失败分支，按网络面板中的实际响应检查：

• 签发 HTTP 400：确认已保存嵌入策略，运行环境仍可用。
• 签发 HTTP 404：确认 API Key 与服务智能体属于同组织，ID 已替换正确。
• 对话返回 EMBED_ORIGIN_NOT_ALLOWED（HTTP 403）：核对实际页面来源；本地应启用 localhost，上线应保存 HTTPS 来源。

下一步

• 传入上下文
• 自定义外观
• 智能体 API 参考
• SaaS 嵌入示例

在网页中插入一行加载脚本，显示 Praxis 托管的 iframe 对话界面。外观在控制台保存，用户留在你的网页中对话；“一行”只指前端安装，后端仍需为登录用户签发令牌。

准备 HTTPS 宿主

准备一个可修改页面和后端的 HTTPS 网站、Bun、同组织的 API Key，以及有短号的服务智能体。以下连接 Develop。用于演示的 HTTPS 入口应转发到本机 127.0.0.1:4242，并保留原始 Host 请求头；证书和域名由你的宿主提供。

在 Develop 控制台打开服务智能体 → 你的智能体 → 接入与配置 → 配置 → 安全，选择运行环境，在来源白名单添加实际 HTTPS 来源，例如 https://support.example.com，点保存安全设置。来源不包含路径。嵌入策略目前只能在控制台配置。

仅打开允许 localhost不能授权 iframe 嵌入；本页需要已保存的 HTTPS 来源。若只做本机 HTTP 调试，先使用 Kit 快速开始。

记录两个标识：签发请求使用公开 ID agent_…；脚本的 data-agent 使用控制台顶部可复制的短号，格式为 5–8 位字母或数字。不要把完整 ID 填进短号位置。

提供签发端点

把以下代码保存为 server.ts，放在 HTTPS 入口后。示例使用两个受密码保护的测试账户；上线时将 authenticate 换成宿主登录会话验证，并保留 CSRF 保护。HOST_ORIGIN 填实际 HTTPS 来源，不带末尾斜线。所有环境变量只配置在后端。

import { timingSafeEqual } from "node:crypto";

const apiKey = process.env.PRAXIS_API_KEY;
const agentId = process.env.PRAXIS_AGENT_ID;
const password = process.env.DEMO_PASSWORD;
if (!apiKey || !agentId || !password) throw new Error("Set the three server variables");
const origin = process.env.HOST_ORIGIN;
if (!origin || new URL(origin).protocol !== "https:") throw new Error("Set HOST_ORIGIN to your HTTPS origin");
const noStore = { "Cache-Control": "no-store" };
function authenticate(request: Request): string | undefined {
  const supplied = Buffer.from(request.headers.get("Authorization") ?? "");
  for (const id of ["customer_123", "customer_456"]) {
    const expected = Buffer.from("Basic " + Buffer.from(`${id}:${password}`).toString("base64"));
    if (supplied.length === expected.length && timingSafeEqual(supplied, expected)) return id;
  }
}
Bun.serve({
  hostname: "127.0.0.1", port: 4242,
  async fetch(request) {
    const url = new URL(request.url);
    if (request.headers.get("Host") !== new URL(origin).host) return new Response("Host rejected", { status: 403 });
    const userId = authenticate(request);
    if (!userId) return new Response("Sign in", {
      status: 401, headers: { ...noStore, "WWW-Authenticate": 'Basic realm="Local demo"' },
    });
    if (request.method === "GET" && url.pathname === "/") {
      return new Response(Bun.file("index.html"), { headers: noStore });
    }
    if (request.method !== "POST" || url.pathname !== "/api/praxis-token") {
      return new Response("Not found", { status: 404 });
    }
    if (request.headers.get("Origin") !== origin) {
      return new Response("Origin rejected", { status: 403 });
    }
    try {
      const response = await fetch("https://api-develop.deepraxis.com/agent/v1/embed_tokens", {
        method: "POST",
        headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
        body: JSON.stringify({ agent: agentId, external_user_id: userId }),
        signal: AbortSignal.timeout(30_000),
      });
      if (!response.ok) return new Response("Token issuance failed", {
        status: response.status, headers: noStore,
      });
      const data = await response.json();
      if (typeof data.token !== "string" || typeof data.expires_at !== "string") {
        throw new Error("Invalid token response");
      }
      return Response.json({ token: data.token, expires_at: data.expires_at }, { headers: noStore });
    } catch {
      return new Response("Token service unavailable", { status: 502, headers: noStore });
    }
  },
});
console.log(origin);

在下一节保存 index.html 后启动。DEMO_PASSWORD 是你自己设置的测试账户密码，不是 API Key；浏览器用 customer_123 或 customer_456 登录。

export HOST_ORIGIN="https://support.example.com"
export PRAXIS_AGENT_ID="agent_REPLACE_ME"
# Set PRAXIS_API_KEY and DEMO_PASSWORD in the server process.
bun server.ts

加载器向 data-token-endpoint 发 POST 请求，并携带浏览器凭据。端点必须从已验证登录态取得用户 ID，每次签发都重新核验。Praxis 返回 HTTP 201 后，宿主向加载器返回 token 和 expires_at。不要在 HTML 中写入 API Key，也不要让令牌进入页面 URL。

插入加载脚本

保存为 index.html。把 ABC123 替换为实际短号；若已有宿主页，只需将其中的脚本标签放到需要出现对话的位置。

<!doctype html>
<html lang="zh">
<meta charset="utf-8">
<title>Order assistant</title>
<body>
  <h1>Order support</h1>
  <script src="https://kit-develop.praxisusercontent.com/v1/loader.js" data-agent="ABC123" data-token-endpoint="/api/praxis-token" async></script>
</body>
</html>

加载器自动创建 iframe 并完成令牌传递。直接打开或粘贴一个 iframe 地址不会自动获得宿主登录用户的身份。

未指定布局和启动按钮时使用控制台保存的外观；还没有保存布局时，加载器采用 popup。显式设置脚本属性会覆盖对应选项。如果使用 inline，脚本所在位置就是插入位置，给外层容器预留足够高度。

保存外观

在接入与配置 → 接入方式与外观 → iframe调整名称、欢迎语和布局，点保存。期望显示“已保存，嵌入页刷新后生效”；刷新你的宿主页验证。持久化外观目前只能在控制台配置。

如果选择 data-launcher="none"，浮层没有默认打开按钮。为已有按钮设置 CSS 选择器，或在宿主代码中控制打开，示例如下。按钮需在加载器执行前存在。

<button id="open-support" type="button">Open support</button>
<script src="https://kit-develop.praxisusercontent.com/v1/loader.js" data-agent="ABC123" data-token-endpoint="/api/praxis-token" data-layout="popup" data-launcher="#open-support" async></script>

这是上一节脚本的替代写法，同一智能体在页面中只保留一份加载脚本。

验证与排错

打开 HTTPS 宿主页并登录，确认对话界面或启动按钮出现；发送问题并收到回复。再用独立浏览器登录第二个测试账户，确认无法看到第一个账户的会话。

在网络面板确认加载了 loader.js，iframe 来自 chat-develop.praxisusercontent.com，宿主令牌端点成功返回。API Key 只能出现在宿主到 Praxis 的服务端请求中，不应出现在浏览器网络记录里。

• 框架被浏览器阻止：检查允许来源是否与页面来源一致；宿主 CSP 的 frame-src 要允许 https://chat-develop.praxisusercontent.com，script-src 要允许脚本 CDN。不要禁用整站 CSP 来排错。
• 控制台提示 Invalid Praxis loader configuration：检查短号格式、脚本域名以及签发端点是否填写。
• 宿主端点返回 HTTP 401 或 403：先恢复宿主登录或修正同源检查；不要把重试当成重新登录。

验证来源拒绝时，从另一个不在白名单中的 HTTPS 站点加载同一脚本，期望浏览器阻止嵌入。验证签发保护时，在退出宿主登录后再次访问签发端点，期望宿主拒绝请求；不要只检查按钮是否隐藏。

用户退出或切换账户时，重新加载宿主页，让后端按新登录态签发，避免沿用原账户界面。加载器的打开和关闭只影响界面显示，不是账户退出，也不会替你的宿主结束登录会话。

下一步

• 自定义外观
• 保护嵌入接入
• 智能体 API 参考
• Cookbook

给你的网站添加一个按钮，让已登录用户进入 Praxis 的独立 Hosted 对话页。宿主后端验证用户、签发链接并立即跳转；不需要在宿主页安装聊天组件。

准备智能体

准备 Bun、同组织的 API Key，以及一个已配置指令、运行环境和嵌入策略的服务智能体。智能体必须有短号；在 Develop 控制台的服务智能体中打开它，确认顶部显示短号，并复制公开 ID agent_…。

尚未保存嵌入策略时，进入接入与配置 → 配置 → 安全，选择运行环境，点保存安全设置。嵌入策略目前只能在控制台配置。以下示例使用 Develop API 和本地宿主 http://localhost:4242，对话则在托管域名中打开。

Hosted 是独立页面，不能作为 iframe 嵌进宿主。需要留在当前页面时，选择一行嵌入或 Kit 组件。

签发链接并跳转

把以下完整服务器保存为 server.ts。它只绑定本机，用 HTTP Basic 验证两个测试账户，并检查表单请求来源。PRAXIS_API_KEY 只存在后端；external_user_id 来自通过验证的账户，而不是表单字段。

import { timingSafeEqual } from "node:crypto";

const apiKey = process.env.PRAXIS_API_KEY;
const agentId = process.env.PRAXIS_AGENT_ID;
const password = process.env.DEMO_PASSWORD;
if (!apiKey || !agentId || !password) throw new Error("Set the three server variables");
const origin = "http://localhost:4242";
const noStore = { "Cache-Control": "no-store" };
function authenticate(request: Request): string | undefined {
  const supplied = Buffer.from(request.headers.get("Authorization") ?? "");
  for (const id of ["customer_123", "customer_456"]) {
    const expected = Buffer.from("Basic " + Buffer.from(`${id}:${password}`).toString("base64"));
    if (supplied.length === expected.length && timingSafeEqual(supplied, expected)) return id;
  }
}
Bun.serve({
  hostname: "127.0.0.1", port: 4242,
  async fetch(request) {
    const url = new URL(request.url);
    if (url.origin !== origin) return new Response("Use localhost:4242", { status: 403 });
    const userId = authenticate(request);
    if (!userId) return new Response("Sign in", {
      status: 401, headers: { ...noStore, "WWW-Authenticate": 'Basic realm="Local demo"' },
    });
    if (request.method === "GET" && url.pathname === "/") {
      return new Response(Bun.file("index.html"), { headers: noStore });
    }
    if (request.method !== "POST" || url.pathname !== "/api/praxis-hosted") {
      return new Response("Not found", { status: 404 });
    }
    if (request.headers.get("Origin") !== origin) {
      return new Response("Origin rejected", { status: 403 });
    }
    try {
      const response = await fetch("https://api-develop.deepraxis.com/agent/v1/embed_tokens", {
        method: "POST",
        headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
        body: JSON.stringify({ agent: agentId, external_user_id: userId, hosted: true }),
        signal: AbortSignal.timeout(30_000),
      });
      if (!response.ok) return new Response("Token issuance failed", {
        status: response.status, headers: noStore,
      });
      const data = await response.json();
      if (typeof data.hosted_url !== "string") throw new Error("Missing URL");
      return new Response(null, {
        status: 302, headers: { ...noStore, Location: data.hosted_url },
      });
    } catch {
      return new Response("Token service unavailable", { status: 502, headers: noStore });
    }
  },
});
console.log(origin);

hosted: true 让签发响应额外包含 hosted_url。成功签发的 HTTP 状态为 201；宿主返回 HTTP 302，并把该 URL 放进 Location，浏览器随即进入对话页。宿主不把 API Key 或签发响应中的 token 发给表单页面。

把实际智能体 ID、API Key 和你设置的本地测试密码放入服务端环境。下一节保存页面后，从同目录启动：

export PRAXIS_AGENT_ID="agent_REPLACE_ME"
# Set PRAXIS_API_KEY and DEMO_PASSWORD in this server process, then run:
bun server.ts

期望：终端显示本地地址。未经认证或来源不匹配的请求无法签发。用于已有应用时，将测试账户验证换成你的登录会话验证，把路由置于登录与 CSRF 保护之后；不要把这套测试账户机制用于线上登录。

添加打开按钮

保存为同目录的 index.html。普通表单提交可以直接跟随后端的跳转；不要通过后台 fetch 请求后就假设浏览器已经导航。

<!doctype html>
<html lang="zh">
<meta charset="utf-8">
<title>Order support</title>
<form action="/api/praxis-hosted" method="post">
  <button type="submit">Open order assistant</button>
</form>
</html>

打开 http://localhost:4242，以 customer_123 和所设测试密码登录，然后点按钮。期望：浏览器进入 chat-develop.praxisusercontent.com 下的对话页。每次点击都向宿主重新请求链接，不缓存上一次的结果。浏览器地址变化后，再检查是否出现可输入的对话区。

理解链接寿命

hosted_url 的 #c=… 是一次性兑换凭证，不是嵌入令牌。它在签发后 60 秒内有效，只能成功兑换一次。不要记录、收藏或分享带凭证的链接；每个用户应从宿主验证身份后进入。

托管页读取凭证后先移除 URL 片段，再自动向 POST /agent/v1/embed/exchange 提交 code，取得 token 和 expires_at。你的宿主不需要手动兑换，否则浏览器拿到的链接已被消费。

链接的 60 秒期限与对话令牌有效期是两件事。兑换成功后，页面在令牌到期前使用该令牌；Hosted 不自动刷新令牌。到期或收到吊销错误后，页面会提示回到原网站重新进入。刷新当前托管页也不能重新使用已经移除的一次性凭证，应回宿主重新点击按钮。

验证接入

在服务端可以用下面的请求检查签发形状。它只输出记录 ID、到期时间和是否存在链接，不输出凭证；这是独立的接口检查，不会替你导航浏览器。测试用户 ID 只用于这次受控检查，应用必须使用已验证身份。

set -o pipefail
curl --fail-with-body --silent --show-error \
  -X POST https://api-develop.deepraxis.com/agent/v1/embed_tokens \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"agent":"agent_REPLACE_ME","external_user_id":"customer_123","hosted":true}' \
  | jq '{id, expires_at, has_hosted_url: (.hosted_url | type == "string")}'

再从按钮执行完整路径：网络面板应看到宿主 POST 返回 302，随后托管页兑换成功并显示对话。发送一条订单问题，确认收到真实回复；只看到加载界面不算成功。

用独立浏览器以 customer_456 进入，确认无法读取第一个账户的会话。无凭据访问宿主端点应返回 HTTP 401。验收链接寿命时，使用单独的测试签发，让链接超过 60 秒后再打开，期望要求回到宿主重新进入，不在原链接上反复重试。

失败处理与外观

兑换接口对过期、已用和未知凭证均返回 NOT_FOUND（HTTP 404）。这些情况都应重新从宿主进入。缺少短号或嵌入策略会使签发返回 HTTP 400；在控制台补齐前提后再试。出现 HTTP 429 时按 Retry-After 等待，再由宿主签发新链接。

外观在接入与配置 → 接入方式与外观 → iframe保存，Hosted 共享名称、主题和欢迎语等设置。持久化外观目前只能在控制台配置。Hosted 始终全页显示，不使用浮窗启动按钮。控制台的 Hosted → 打开预览用于预览，不替代宿主对真实登录用户的签发。

下一步

• 嵌入令牌与用户
• 自定义外观
• 智能体 API 参考
• Cookbook

修改服务智能体的指令、模型和工具，再选择向终端用户提供哪一个版本。配置保存与嵌入版本选择是两个动作；固定版本后，保存新配置不会自动升级嵌入。

准备智能体

准备一个已有的服务智能体，以及有权管理它的组织账户。打开控制台「服务智能体 → 选择智能体 → 接入与配置 → 配置」。下面的控件名称对应当前中文控制台。

使用 API 时，从创建或查询响应取得公开 ID agent_…。在服务器设置 PRAXIS_API_BASE 为所用环境的 API 源站地址，PRAXIS_API_KEY 为该组织的 API Key；不要把 Key 放入网页。下例还需 Node.js（支持原生 fetch），并将 PRAXIS_AGENT 设置为真实公开 ID。

修改并保存配置

单独保存嵌入设置

嵌入安全策略、凭据库选择与嵌入版本固定目前只能在控制台配置。

在「配置 → 安全」选择可用运行环境，填写你的网站来源，并设置令牌有效期与预算，然后点击「保存安全设置」。有效期界面单位为分钟，预算单位为美元；不要直接把接口的秒数或美分数填入界面。来源规则见保护嵌入接入。

需要凭据库时，在「MCP 与凭据」勾选后点击「保存凭据库」。预期结果： 两种保存均显示「已保存，不产生新版本」。它们不属于底部保存栏的配置草稿。

选择嵌入版本

进入「接入与配置 → 版本」。点击版本号查看与上一版本的差异，再选择「设为嵌入版本」或旧版本的「回滚到此版本」，确认后检查「嵌入中」标记。需要恢复跟随最新时点击「取消固定」。没有安全策略时，先完成上一步。

签发时显式指定的 version 优先于控制台固定版本；省略时使用固定版本，未固定才取最新版本。已经签发的令牌保持原版本，回滚不会改变它们。验证升级或回滚时，应重新签发令牌并开始新会话。

验证与下一步

进入「试用调试」，选择刚保存的版本，发送一个能区分新旧指令的问题，检查真实回复。随后在宿主网页重新取得令牌，开始新会话，并在「运营与管理 → 会话」核对版本。只看到界面加载不能证明新配置已被使用。

服务智能体目前不支持按消息切换模型、工具模式、语音输入和按终端用户的记忆；「配置 → 开场与外观」仍是占位，外观操作见自定义外观。

下一步：测试嵌入接入 · 智能体 API · Cookbook

嵌入令牌让终端用户访问指定智能体及自己名下的会话。登录用户的令牌由宿主后端签发，浏览器消费；本页说明身份、有效期、刷新和单张令牌吊销。

准备同组织的服务智能体、已保存的嵌入策略和服务端 API Key。策略在控制台的接入与配置 → 配置 → 安全保存，目前只能在控制台配置。示例使用 Develop；完整网页接入见嵌入到网页，一次性跳转见 Hosted。

身份与访问范围

宿主后端用自己的登录系统确认用户，再以 external_user_id 传入稳定标识。同一组织、同一智能体、同一标识对应同一个终端用户；它不是组织成员 ID，也不是昵称。标识长 1–128 字符，仅允许字母、数字、下划线、点、冒号、@ 和连字符。

刷新令牌不会改变用户身份。更换登录账户则应移除旧组件，按新身份重新创建；界面中的确认按钮不能代替工具服务端的账户授权。

签发令牌

生产签发由宿主后端调用 POST /agent/v1/embed_tokens。以下是服务端独立检查，测试用户固定为 customer_123；真实宿主必须从验证后的登录会话取值，不接受浏览器自报身份。控制台的试用调试 → 模拟 → 重新签发只用于调试身份。

set -o pipefail
curl --fail-with-body --silent --show-error \
  -X POST https://api-develop.deepraxis.com/agent/v1/embed_tokens \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"agent":"agent_REPLACE_ME","external_user_id":"customer_123"}' \
  | jq '{id, expires_at, has_token: (.token | type == "string")}'

期望：HTTP 201，响应含 id、token、expires_at。id 标识本次签发，供后续吊销；token 是浏览器凭证；expires_at 是 ISO 8601 UTC 到期时间。示例只输出脱敏检查结果。每次调用都会新建签发记录，重复请求不幂等。

可选 ttl_seconds 省略时取策略默认值；范围从 60 秒到策略上限与 3600 秒中的较小值。budget_cents 不能超过策略单会话预算上限；allowed_origins 只能取策略已有条目的子集。版本按显式 version、策略固定版本、最新版本的次序选择，签发后固定。完整字段见 API 参考。

刷新与结束访问

Kit 调用 getToken(current) 时，首次传入 null，刷新时传入当前令牌。把以下回调放进快速开始的 api.getToken；宿主端点每次都验证用户仍已登录，再返回新令牌。

async function getToken(current) {
  const response = await fetch("/api/praxis-token", {
    method: "POST", credentials: "same-origin", cache: "no-store",
  });
  if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
  const data = await response.json();
  if (typeof data.token !== "string" || !data.token) throw new Error("Missing token");
  return data.token;
}

回调不需要把当前令牌发回宿主来证明身份。Kit 负责调用时机并在内存中持有令牌；不要把一个固定令牌写死在回调中。期望：刷新后仍访问同一用户的会话。

宿主退出登录时，先结束宿主会话，再移除旧 Kit 元素；移除会关闭它的连接，但不会在服务器吊销已签发的令牌。需要立即禁止原凭证访问时，另行吊销。Hosted 没有这条刷新路径，到期后必须回宿主重新进入。

匿名访客

公开问答不要求登录时，在接入与配置 → 密钥 → 可公开 key → 新建可公开 key创建 key，设置匿名限流和预算，并复制只显示一次的完整值。来源仍在配置 → 安全管理。这些设置目前只能在控制台配置；可公开 key 与服务端 API Key 不能互换。

以下是可独立保存的 index.html。替换 PRAXIS_PUBLISHABLE_KEY 为实际可公开 key，并从允许来源的网站提供此文件。它不需要登录用户的宿主签发端点；不要同时配置 getToken。

<!doctype html>
<html lang="zh">
<meta charset="utf-8">
<title>Public documentation assistant</title>
<script type="module" src="https://kit-develop.praxisusercontent.com/v0.2.8/praxis-kit.js" integrity="sha384-vey+VZZcFIWJq9Fmv/nmLxspKtXRiL8XiDOfg2g2QFvwZi5MA+tkiQvPBtoMS8eU" crossorigin="anonymous"></script>
<praxis-agent style="display:block;height:600px;width:100%"></praxis-agent>
<script type="module">
  await customElements.whenDefined("praxis-agent");
  document.querySelector("praxis-agent").setOptions({
    api: {
      url: "https://api-develop.deepraxis.com",
      publishableKey: "PRAXIS_PUBLISHABLE_KEY",
    },
    agent: { name: "Documentation assistant" },
  });
</script>
</html>

Kit 向 POST /agent/v1/embed_tokens/anonymous 提交 publishable_key，后续带上已有的 visitor_secret。接口不需要 API Key，成功返回 HTTP 200、token、expires_at；仅新访客另收到 visitor_secret。浏览器不能选择 external_user_id、预算、指令或 Hosted 选项。

Kit 将访客凭据保存在本地存储，存储不可用时退回页面内存。不要公开或共享它。期望：同一存储中的访客刷新后延续身份；独立浏览器存储产生独立身份。匿名身份不授予读取实名订单等账户数据的权限。

查看与吊销

只吊销需要停止使用的那张令牌。下面两种路径完成同一任务。

期望：单张吊销返回带 revoked_at 的记录；重复吊销返回原记录。该令牌的事件流收到 session.error，错误码为 EMBED_TOKEN_REVOKED，随后关闭；其他令牌不受影响。用户级批量撤销、封禁和解封见管理终端用户。

错误与下一步

到期后重新验证宿主登录；吊销后停止原访问；来源不允许时修正配置；用户被封禁时交由管理者处理。不要无限重签来绕过拒绝。具体错误码、HTTP 状态和恢复条件见嵌入限制与错误。

• 传入上下文
• 管理终端用户
• 打开托管对话
• 智能体 API 参考

把当前课程、选中的订单或用户偏好交给智能体，让回答贴合用户此刻的任务。页面状态用 readables 随消息发送；后端核实的信息用宿主上下文传入。

准备接入

准备一个已能回复的 Kit 页面、服务智能体和嵌入策略。下面的 HTML 由你的宿主网站提供；同源 POST /api/praxis-token 是你按嵌入令牌与用户实现的后端路由，验证登录态后返回 { token }，不是 Praxis 的公开接口。示例使用 Develop 的 Kit 和 API，页面来源须已获准接入。

随消息传入页面状态

把下面的页面保存为网站中的 HTML。下拉框变化时更新登记值，发送消息时 Kit 取当前快照。

<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8" />
<title>课程助手</title>
<label>当前课程
  <select id="lesson">
    <option value="第三课：配送规则">第三课：配送规则</option>
    <option value="第四课：退货流程">第四课：退货流程</option>
  </select>
</label>
<button id="clear">停止传入课程</button>
<praxis-agent style="display:block;height:600px"></praxis-agent>
<script type="module">
  import "https://kit-develop.praxisusercontent.com/v1/praxis-kit.js";
  await customElements.whenDefined("praxis-agent");
  const chat = document.querySelector("praxis-agent");
  const lesson = document.querySelector("#lesson");
  const update = () => chat.setReadable("lesson", { title: lesson.value });
  update();
  lesson.addEventListener("change", update);
  document.querySelector("#clear").addEventListener("click", () => {
    chat.removeReadable("lesson");
  });
  chat.addEventListener("praxis.log", event => console.warn(event.detail));
  chat.setOptions({
    api: {
      url: "https://api-develop.deepraxis.com",
      getToken: async () => {
        const response = await fetch("/api/praxis-token", {
          method: "POST", credentials: "same-origin",
        });
        if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
        const { token } = await response.json();
        if (typeof token !== "string" || !token) throw new Error("Missing token");
        return token;
      },
    },
    agent: { name: "课程助手" },
  });
</script>
</html>

预期结果： 询问「我正在看哪一课」，智能体收到第三课的信息；切换课程再发消息，新消息携带第四课。点击「停止传入课程」后，后续消息不再附带该项。

setReadable(name, value) 接受字符串或可 JSON 序列化的值；名称须匹配 [A-Za-z0-9_.:-]{1,64}。同名登记覆盖当前值，removeReadable(name) 删除登记。非法名称、不能序列化的值会抛错，原登记保持不变。

每条消息最多 32 项，整个上下文 JSON 最多 4096 UTF-8 字节。超出时 Kit 从最早登记的项开始丢弃本次快照中的数据，并通过 praxis.log 发出 warn，data.names 列出丢弃项。登记本身保留；缩小值后可再次发送。

页面上下文附在本轮用户消息里，标记为不可信。每轮取新快照，但移除登记不会抹去旧消息中的信息。它不能证明用户身份、账户余额或订单归属。

传入后端核实的信息

在宿主后端签发令牌时传 system_message。下面是服务端请求：替换公开智能体 ID，测试用户 ID 换成宿主登录态确定的 ID；不要把 PRAXIS_API_KEY 或这段命令放进网页。

curl --fail-with-body https://api-develop.deepraxis.com/agent/v1/embed_tokens \
  -X POST \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent": "agent_example",
    "external_user_id": "customer_123",
    "system_message": [{"type": "text", "text": "客户偏好中文回复。"}]
  }'

预期结果： 响应为 HTTP 201，包含 token、id 和 expires_at。让宿主路由只把所需的短期凭据返回浏览器，用该令牌创建新会话，用户偏好会进入模型上下文。不要把令牌打印到共享日志。

system_message 是 { type: "text", text } 数组，文本合计最多 8192 UTF-8 字节；使用一个文本块可避免分块分隔符增加体积。它是模型可读信息，不是秘密存储。

已经开始的会话可以由 API Key 持有者通过发送事件追加 system.message；更换令牌不会改写已建立会话的上下文。

选择其他输入

覆盖未获准时返回 HTTP 400、EMBED_FIELD_NOT_ALLOWED。先修正策略或去掉覆盖字段，再重新签发；重复同一请求不会解除限制。

验证传入结果

打开浏览器 Network，发送消息，检查请求中的 praxis_context.items：应有 name: "lesson" 和当前课程的字符串值。切换课程、删除登记后各发一次，确认请求随之变化；不要只凭模型回答判断是否传入成功。

后端上下文用新签发的令牌新建会话，询问回复语言并核对签发请求中的文本。模型回复用于体验验证；身份和权限仍由宿主后端及工具服务端校验。

下一步：前端工具 · 保护嵌入接入 · 智能体 API。

让智能体按需读取当前页面，或执行页面上的动作。你在智能体里声明工具，在 Kit 页面实现同名回调；Kit 把结果送回会话，智能体继续回答。

准备接入

准备一个能回复的 Kit 页面、服务智能体的公开 ID（agent_…），以及宿主后端的 API Key。下面以读取课程选择为例，不需要视频、数据库或额外依赖。宿主网站须已有验证登录态的 POST /api/praxis-token 路由，返回 { token }，详见嵌入令牌与用户。它是你的路由，不是 Praxis API。

前端工具适合按需读取。每条消息都需要的小事实，使用页面上下文。

在智能体声明工具

将以下文件保存为 register-tool.ts，替换 agent_example，在已注入 PRAXIS_API_KEY 的服务端运行 bun register-tool.ts。它先读取智能体，再通过公开 API 更新 tools，保留其他工具，并用当前 version 防止覆盖并发修改。

// register-tool.ts — run on the server with: bun register-tool.ts
const key = process.env.PRAXIS_API_KEY;
if (!key) throw new Error("Set PRAXIS_API_KEY on the server");
const url = "https://api-develop.deepraxis.com/agent/v1/agents/agent_example";
const headers = { Authorization: `Bearer ${key}`, "Content-Type": "application/json" };
const currentResponse = await fetch(url, { headers });
if (!currentResponse.ok) throw new Error(`Read failed: ${currentResponse.status}`);
const current = await currentResponse.json();
const tool = {
  type: "custom",
  name: "read_selected_lesson",
  description: "Read the selected lesson when the user asks which lesson is open.",
  input_schema: { type: "object", properties: {}, additionalProperties: false },
};
const tools = [...(current.tools ?? []).filter(
  (item: { type: string; name?: string }) =>
    !(item.type === "custom" && item.name === tool.name),
), tool];
const response = await fetch(url, {
  method: "POST", headers,
  body: JSON.stringify({ version: current.version, tools }),
});
if (!response.ok) throw new Error(`Update failed: ${response.status}`);
const saved = await response.json();
console.log({ id: saved.id, version: saved.version });

预期结果： 终端输出智能体 ID 和新版本。让宿主签发新版本的令牌，再开始新会话；已固定旧版本的令牌或已有会话不会自动换到新定义。若嵌入策略固定版本，在控制台更新接入版本，或签发时明确指定新 version。

工具名须匹配 ^[a-zA-Z0-9_-]{1,64}$，不能与其他自定义工具或内置工具重名。input_schema.type 必须是 object；描述要说明何时调用。仅在页面实现函数，不会把工具自动加入智能体。

实现页面回调

将下面的 HTML 放到宿主网站。它使用 Develop 的 Kit 和 API；页面来源需要在嵌入策略中获准。

<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8" />
<title>课程助手</title>
<label>当前课程
  <select id="lesson">
    <option value="第三课：配送规则">第三课：配送规则</option>
    <option value="第四课：退货流程">第四课：退货流程</option>
  </select>
</label>
<output id="tool-status" aria-live="polite"></output>
<praxis-agent style="display:block;height:600px"></praxis-agent>
<script type="module">
  import "https://kit-develop.praxisusercontent.com/v1/praxis-kit.js";
  await customElements.whenDefined("praxis-agent");
  const chat = document.querySelector("praxis-agent");
  const lesson = document.querySelector("#lesson");
  chat.onClientTool = async ({ name }) => {
    if (name !== "read_selected_lesson") throw new Error(`Unknown tool: ${name}`);
    return { title: lesson.value };
  };
  chat.addEventListener("praxis.tool.change", event => {
    const { name, status, isError } = event.detail;
    document.querySelector("#tool-status").textContent =
      `${name}: ${status}${isError ? " (error)" : ""}`;
  });
  chat.addEventListener("praxis.log", event => console.warn(event.detail));
  chat.setOptions({
    api: {
      url: "https://api-develop.deepraxis.com",
      getToken: async () => {
        const response = await fetch("/api/praxis-token", {
          method: "POST", credentials: "same-origin",
        });
        if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
        const { token } = await response.json();
        if (typeof token !== "string" || !token) throw new Error("Missing token");
        return token;
      },
    },
    agent: { name: "课程助手" },
  });
</script>
</html>

onClientTool 是元素的 JavaScript 属性，不能放进 HTML 属性或 setOptions。回调收到 { id, name, input }，分别是调用编号、工具名和输入；参数应由你的函数校验。对未知工具名抛错，不要返回成功。

字符串返回值原样发送，其他可序列化值转成 JSON 文本，undefined 转成空字符串。抛错、Promise 拒绝或序列化失败会作为错误结果返回。不要在结果里放其他用户的数据或凭据。

验证调用与恢复

询问「请调用工具告诉我正在看哪一课」。预期结果： 页面状态依次显示 start、end，智能体根据工具返回的课程回答。换课后再次提问，返回当前选择。end 表示服务端已接收结果，不代表整轮回复结束。

服务端最多等待 120 秒；超时记入错误结果后继续。Kit 会认领调用编号，并检查历史结果以避免重复执行，但这不是跨标签页事务保证。会改变业务数据的工具必须由后端鉴权并做幂等处理。

授权与下一步

前端 custom 工具不经过平台的工具确认卡。需要用户确认的页面动作，由你的界面处理；真正的数据权限必须在后端检查，不能依赖浏览器或模型参数。

配置工具授权 · 组件参考 · 更新智能体 API。

为已启用的工具选择直接执行或每次询问，让用户在操作发生前确认意图。本页以订单 MCP 的查询和退货工具为例；业务权限仍须由工具服务端校验。

准备工具

准备一个已能接入的服务智能体，并在「配置 → MCP 与凭据」连接名为 orders 的 MCP 服务器。示例要求它提供已启用的 list_orders 和 request_return。替换为你实际的服务器和工具名称，不要用示例名称配置不存在的工具。

确认卡不能代替身份认证。公网 MCP 服务必须先认证平台调用方，再按终端用户限定数据范围，见保护嵌入接入。

选择执行策略

目前支持这两档。不要使用 auto：即使某处类型接受它，运行时也会拒绝执行。需要禁止使用一个工具时，关闭该工具；「每次询问」仍允许用户同意调用。

策略不绕过工具自身的强制交互、安全边界或业务检查。前端 custom 工具由你的页面执行，不经过这套确认策略。

设置工具与默认值

解析顺序为单工具 configs[].permission_policy → 工具集 default_config.permission_policy → 工具默认策略。未设置 MCP 策略时，服务器声明 annotations.readOnlyHint === true 才默认放行，否则默认询问。该提示仅影响缺省，显式配置优先。

内置工具集未设置默认策略时为 always_allow，但工具自身要求的交互仍然存在。对退款、删除和对外发送等动作，明确设置询问，不要仅依赖服务器提示。

验证确认过程

签发使用新版本的嵌入令牌并新建会话；若嵌入策略固定版本，先更新固定版本或在签发时指定新版本。保存智能体不会自动升级已有会话。

先让智能体调用查询工具，再请求一次测试退货。预期： 查询直接返回；退货显示 Kit 确认卡。拒绝后工具服务端不应执行退货；再次提出请求并允许后才执行。以工具服务端记录核实调用是否发生，不要只看智能体的回答。

Kit 自带确认卡，无须另写界面。嵌入用户的允许只针对这次调用，不会保存为永久工具权限。完整测试情境见测试嵌入接入。

下一步

保护工具服务 · 前端工具 · 更新智能体 API。

让聊天的配色、开场和输入区与网站一致。iframe 与 Hosted 使用控制台保存的同一份外观；Kit 组件使用你在网页中传入的选项。

准备接入

先准备能正常回复的服务智能体和嵌入策略。Kit 示例要求宿主网站已提供 POST /api/praxis-token，验证登录态并返回 { token }；这是你的同源路由，详见嵌入令牌与用户。示例使用 Develop 地址，页面来源须获准接入。

保存托管外观

iframe / Hosted 的持久外观目前只能在控制台配置。当前控制台入口为「服务智能体 → 你的智能体 → 接入与配置 → 接入方式与外观 → iframe」。

1. 在「主题」选择配色、强调色、灰阶、圆角和密度。
2. 在「开场」填写欢迎语与推荐问题，在「输入区」设置输入提示和页脚。
3. 点击「保存」。预期： 提示「已保存，嵌入页刷新后生效」。刷新 iframe，或重新打开 Hosted，检查同一组文字和配色。

不要去「配置 → 开场与外观」编辑：该位置目前是提示页。公开外观接口只提供读取，没有公开的保存接口。

设置 Kit 外观

把下面的 HTML 放在宿主网站。它同时设置主题、开场和输入框，并提供一个按钮验证运行中更新。

<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8" />
<title>订单助手</title>
<button id="dark">切换深色</button>
<praxis-agent style="display:block;height:600px"></praxis-agent>
<script type="module">
  import "https://kit-develop.praxisusercontent.com/v1/praxis-kit.js";
  await customElements.whenDefined("praxis-agent");
  const chat = document.querySelector("praxis-agent");
  chat.setOptions({
    api: {
      url: "https://api-develop.deepraxis.com",
      getToken: async () => {
        const response = await fetch("/api/praxis-token", {
          method: "POST", credentials: "same-origin",
        });
        if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
        const { token } = await response.json();
        if (typeof token !== "string" || !token) throw new Error("Missing token");
        return token;
      },
    },
    agent: { name: "订单助手" },
    theme: {
      colorScheme: "light", accent: "#2563eb", grayscale: "cool",
      radius: "lg", density: "normal", fontFamily: "system-ui, sans-serif",
      fontSize: 16,
    },
    header: { title: "订单服务", subtitle: "配送与退货咨询" },
    startScreen: {
      greeting: "今天想了解什么？",
      prompts: [{ label: "配送规则", prompt: "请介绍配送规则。" }],
    },
    composer: { placeholder: "输入订单问题", attachments: { enabled: false } },
    history: { enabled: true },
    footer: "订单信息以商家确认为准。",
  });
  document.querySelector("#dark").addEventListener("click", () => {
    chat.setOptions({ theme: { colorScheme: "dark" } });
  });
</script>
</html>

预期结果： 出现蓝色强调色、欢迎语和「配送规则」按钮；输入框不显示附件入口。点击「切换深色」后颜色切换，当前会话和消息保留。

再次调用 setOptions 会合并嵌套选项，数组整体替换。因此更新 theme.colorScheme 不需要重传令牌回调；更换推荐问题时，传入完整的 startScreen.prompts 数组。

调整主题与文字

保存的外观 JSON 最多 8192 UTF-8 字节；欢迎语 200 字符、推荐问题最多 4 项，每项 label 40 字符、prompt 200 字符，输入提示 80 字符。头像和顶栏图片须使用 HTTPS 地址。只改组件配置时，详细属性边界见组件参考。

验证与下一步

在一个新会话中检查开场文字，点击推荐问题，确认实际发送的是 prompt。在已有消息的会话点击深色按钮，确认消息保留；另开页面检查控制台保存的外观，避免把 Kit 的本地配置误认为已保存。

外观更新不改变智能体指令或工具授权。若保存失败，按字段提示缩短文字、减少推荐问题或修正图片地址后重试。

组件参考 · 保护嵌入接入 · 智能体 API。

把嵌入智能体接到网站时，用宿主登录态确定用户，用来源白名单限制浏览器接入，并在工具服务端检查权限。本页配置这些边界；测试情境与上线验收分别见测试嵌入接入和上线检查清单。

准备与责任

你需要能管理服务智能体的控制台账号、宿主网站的后端，以及修改网站响应头的权限。先完成嵌入策略和令牌签发，再按下面的责任检查接入。

保管身份与凭据

后端用 PRAXIS_API_KEY 签发短期嵌入令牌，浏览器只接收需要的令牌。每次签发和续期都重新验证宿主登录态；不要让请求体中的 external_user_id 决定用户是谁。不要把 API Key、嵌入令牌放进 URL、HTML 或日志。

Kit 的传输层在内存中持有令牌。匿名接入另有 visitor_secret，Kit 会尝试保存在 localStorage 以延续访客身份，存储不可用时回退到页面内存。publishableKey 可公开，visitor_secret 不可公开；匿名身份不等于你网站的登录账户。

登出时停止签发、移除聊天组件，并由后端撤销相应凭据；清空页面并不等于撤销。封禁终端用户会阻止新签发并撤销该用户现有令牌。Kit 可在到期前重新取令牌，Hosted 不自动续期；详见嵌入令牌与用户。

指令、system_message、页面上下文与工具结果都可能被模型复述。仅传入当前用户有权知道的信息，不要把密钥或其他用户的数据当作上下文传入。

限定页面来源

来源白名单目前只能在控制台配置。在当前控制台打开「服务智能体 → 你的智能体 → 接入与配置 → 配置 → 安全」，点击「添加来源」，填写例如 https://shop.example.com，然后点击「保存安全设置」。预期： 显示「已保存，不产生新版本」。

allowed_origins 最多 50 项，只填来源，不含路径、查询参数或片段。普通来源须为 HTTPS；https://*.example.com 只匹配一级子域，不匹配根域名或多级子域，且不支持端口。「允许 localhost」只用于本地 HTTP 调试，默认关闭。

签发时可以用 allowed_origins 选择策略中的非空子集，条目必须与策略完全一致。不要传空数组来表达「禁止所有来源」：令牌校验会回退读取策略白名单。修改策略也不等于撤销已签发令牌，需要立即收回访问时执行撤销。

来源不允许时返回 HTTP 403、EMBED_ORIGIN_NOT_ALLOWED。先修正来源配置再重新接入。来源检查约束浏览器；没有 Origin 的非浏览器请求不受这项检查保护，所以它不能代替令牌认证。

保护工具访问

MCP 服务器先验证平台调用凭据，再读取 X-Praxis-External-User-Id 作为终端用户身份。平台还会附带 X-Praxis-Agent-Id 和 X-Praxis-Session-Id；没有终端用户的会话不带这些身份头。

你的服务必须拒绝缺少所需身份的请求，每次查询都限定该用户的数据，修改订单前再验证归属和业务状态。不要相信模型传入的用户 ID，也不要仅凭公网请求带了身份头就信任它。通过 MCP 配置的 headers 认证调用方，才能使用平台附带的身份。

工具确认卡帮助确认意图；点击允许不会授予数据访问权。前端工具和页面上下文来自浏览器，不能承担权限校验。

配置宿主页保护

以下是 Develop 宿主页的响应头示例。适用于初始化脚本放在同源 JavaScript 文件中、Kit 从 CDN 加载的页面；按网站所需资源收窄图片等来源。若保留内联初始化脚本，须另为该脚本配置 CSP nonce 或哈希。

Content-Security-Policy: default-src 'self'; script-src 'self' https://kit-develop.praxisusercontent.com; style-src 'self' 'unsafe-inline' https://kit-develop.praxisusercontent.com; connect-src 'self' https://api-develop.deepraxis.com https://kit-develop.praxisusercontent.com; frame-src https://chat-develop.praxisusercontent.com; font-src 'self' https://kit-develop.praxisusercontent.com data:; img-src 'self' https: data: blob:; frame-ancestors 'none'; base-uri 'self';

Kit 主题使用内联样式，因此示例允许内联样式。连接来源要与 api.url 一致。frame-src 允许加载托管 iframe；frame-ancestors 'none' 则禁止其他网站嵌入你的宿主页，两者作用不同。

平台 iframe 的 frame-ancestors 来自来源白名单，空白名单禁止嵌入；Hosted 禁止被嵌入。Kit 使用 open Shadow DOM，只隔离样式，同页脚本可以读取它；不要把不可信脚本与聊天组件放在同一页面。

若使用 CDN 完整性校验，复制控制台生成的实际固定版本地址与 integrity，保留 crossorigin="anonymous"。不要给浮动的 /v1/ 地址配固定哈希，也不要把示意哈希当作发布值。

验证与下一步

保存后从获准的网站重新加载嵌入页，确认能发送消息。用浏览器 Network 检查宿主页响应中的 CSP，Console 中不应出现 Kit 加载或 API 连接被 CSP 阻止的错误。检查签发路由只返回短期凭据，工具日志中的用户范围与登录用户一致。

测试嵌入接入 · 上线检查清单 · 嵌入限制与错误。

按宿主应用的用户 ID 查找终端用户，并在需要时停止或恢复其嵌入访问。操作范围是当前组织、当前智能体下的这个用户。

准备与选择操作

准备已有嵌入策略的服务智能体、组织管理权限，以及签发时使用的 external_user_id。先用隔离测试用户验证操作；撤销和封禁会中断其正在进行的对话。

只想撤销一张令牌时，使用令牌管理，不要执行用户级批量撤销。

查找并管理用户

验证访问边界

撤销后，用旧令牌再次访问，应被拒绝；宿主重新确认登录身份后可以签发新令牌。封禁后，宿主的签发请求应收到 EMBED_USER_BLOCKED（HTTP 403）。解封后重新签发并发送消息，确认恢复；不要以旧令牌重试成功作为解封标准。

同时用另一个用户访问同一智能体，确认其访问未被本次操作影响。用户身份不能取自浏览器任意提交的 ID，应由宿主后端的登录态确定。

处理失败

查不到用户时，核对组织、公开智能体 ID 和签发时的完整用户 ID；控制台试用调试的数据不会进入客户用户列表。仅有前缀相似不能证明是同一个用户。

若封禁返回失败，重新读取状态后再决定是否重试：封禁状态可能已经保存，而撤销步骤尚未完成。不要在这种情况下显示“封禁完成”。记录 HTTP 状态和请求 ID，按限制与错误处理。

下一步

查看会话与用量 · 测试嵌入接入 · 智能体 API · Cookbook

从会话、用户和花费判断嵌入是否正常工作，再打开具体会话检查发生了什么。本页适合已经产生真实宿主访问的服务智能体。

准备检查记录

使用有权管理该智能体的组织账户，打开控制台「服务智能体 → 选择智能体 → 运营与管理」。下文使用当前中文控制台的控件名称。准备要检查的时间、终端用户 ID 和宿主接入方式。

先在宿主网页发送一条可识别的测试消息并收到回复，再查运营数据。控制台「试用调试」的记录不会进入客户运营统计，不能用它证明客户流量或花费已经入表。

查看概览

进入「概览」，选择 24 小时、7 天或 30 天。概览统计目前只能在控制台查看，没有对应的公开聚合 API。

预期结果： 选择的时间范围内出现会话趋势和版本分布；没有对应样本的指标显示「—」，不是零。24 小时趋势按小时展示，其他范围按天展示。运行错误、来源拦截和工具计数按所选范围覆盖的 UTC 自然日汇总，首尾不足一天时也包含整日计数。

查找与回放会话

检查用量与预算

进入「用量与预算」，查看本月花费、月度上限和触顶动作，再选择 7、30 或 90 天的每日花费。下方展示预算与限流、本月来源拆分及花费最高的终端用户 Top 20。本月按 UTC 自然月计算，界面金额为美元。

这些聚合报表与预算设置目前只能在控制台查看或配置。「修改上限」进入「配置 → 安全」；保存后返回核对。触顶动作为「停止新会话」时会拒绝新建会话；「只告警」不会拦截。「花费构成」尚未提供，不能从占位区域推断费用拆分。

验证与后续处理

用同一用户、会话和时间范围核对宿主消息、回放及来源。若版本与预期不符，先检查令牌签发时的版本；固定或回滚版本不改变已签发令牌。没有数据时先核对环境、组织和时间范围，不要反复创建测试会话来填充统计。

出现来源拦截或预算拒绝时，记录响应中的 X-Request-Id、时间、HTTP 状态和错误码；不要附上 API Key 或令牌。用户级处理见管理终端用户。

下一步：嵌入限制与错误 · 智能体 API · Cookbook

上线前，用真实宿主网页验证正常对话和拒绝路径。下面列的是要执行的验收情境；控制台出现组件或触发 praxis.ready 只证明挂载，不证明认证和模型回复成功。

准备测试环境

准备隔离的服务智能体、可用模型与运行环境、已保存的嵌入策略，以及已经完成接入的宿主页面。将该页面的实际来源加入白名单，设置可承受的预算。使用两个宿主测试账户 A、B，分别由后端登录态得到不同的 external_user_id。

先在「服务智能体 → 选择智能体 → 接入与配置 → 试用调试」选择版本、发送问题，排除配置本身的问题。随后执行下表中的宿主测试；控制台模拟不替代宿主登录、域名和令牌端点测试，也不进入客户运营统计。

按情境验收

可用下面的独立脚本验证有效期下限。在服务器设置 PRAXIS_API_BASE（API 源站）、PRAXIS_API_KEY（组织 API Key）和 PRAXIS_AGENT（真实 agent_… ID）。用支持原生 fetch 的 Node.js 保存并执行 node test-token-limit.mjs。智能体必须已配置好策略，否则会先因缺少配置失败。

import assert from 'node:assert/strict';

const { PRAXIS_API_BASE, PRAXIS_API_KEY, PRAXIS_AGENT } = process.env;
assert(PRAXIS_API_BASE && PRAXIS_API_KEY && PRAXIS_AGENT, 'Set the three environment variables');
assert(PRAXIS_AGENT.startsWith('agent_'), 'Use the public agent ID');
const response = await fetch(`${PRAXIS_API_BASE.replace(/\/$/, '')}/agent/v1/embed_tokens`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${PRAXIS_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ agent: PRAXIS_AGENT, external_user_id: 'docs_test_a', ttl_seconds: 59 }),
});
assert.equal(response.status, 400, 'Invalid TTL must be rejected');
console.log({ status: response.status, requestId: response.headers.get('X-Request-Id') });

预期结果： 脚本正常退出并输出 status: 400；这里只验证拒绝状态，错误体应另核对 INVALID_PARAMS 和有效期字段提示。脚本不打印凭证，也不替代成功签发和真实回复测试。

验证身份与生命周期

1. A 开始会话后退出，销毁 A 的组件。B 登录并新建组件，检查历史里没有 A 的会话；用 B 的令牌读取 A 的会话也必须被拒绝。只清空界面不等于切换身份。
2. A 保持登录跨过一次令牌刷新，确认 getToken(current) 重新检查宿主身份，后续消息仍属于 A。单独用已过期令牌请求，应得到 EMBED_TOKEN_EXPIRED（401）。
3. 在「运营与管理 → 签发记录」撤销 A 当前令牌，确认旧访问失败，组件不自动绕过撤销继续刷新。用户级批量撤销、封禁与解封按管理终端用户验证。
4. 匿名接入用独立浏览器存储测试两位访客，再刷新同一访客页面检查身份延续；不要把 visitor_secret 分享给另一位访客。
5. Hosted 接入分别测试兑换链接超过 60 秒、重复兑换，以及已打开页面的令牌到期；前两者被拒绝，后者不会自动刷新，应从宿主重新获取链接。

排错与清理

记录每项的时间、环境、组件版本、预期与实际结果，以及失败响应的 X-Request-Id、状态和错误码。错误事件可能只有 message；从浏览器网络面板补齐响应信息，记录中不含 Key、令牌或访客凭据。

完成后撤销本轮测试令牌，归档不再使用的测试会话，恢复临时修改的限额和封禁状态。归档不会删除记录。再用正常配置执行一次成功对话，确认清理没有留下访问障碍。

下一步：上线检查清单 · 限制与错误 · 智能体 API

在嵌入首次对外开放，或更换域名、身份接入方式、组件版本后执行本清单。先完成测试嵌入接入，每项保存可复查的结果，再开放访问。

确认上线条件

• 配置与版本一致。 控制台「接入与配置 → 版本」显示预期嵌入版本；宿主新签发令牌产生的会话使用该版本。若签发请求显式传 version，确认它没有覆盖你的版本选择。
• 身份来自宿主登录态。 未登录请求无法从宿主取得令牌；A、B 两个测试用户互相看不到会话。API Key 仅在服务器，浏览器源码和响应中没有 PRAXIS_API_KEY 的真实值。
• 匿名凭据使用正确。 若启用匿名访问，页面只公开 publishable key，已设置相应限额；不同浏览器存储的访客相互隔离，visitor_secret 不被分享。
• 目标来源已验证。 用实际 HTTPS 域名加载并完成回复；白名单外来源失败。iframe 在目标页面可显示；Hosted 使用独立页面，不能嵌入 iframe。上线配置关闭不再需要的 localhost 访问。
• 组件交付可重复。 已记录并验证使用的 Kit 版本、脚本地址及适用的完整性值；从空缓存加载成功。页面能发送消息并收到真实回复，而非仅收到 praxis.ready。
• 拒绝路径可恢复。 到期、撤销、封禁和来源拒绝均已测试。宿主退出后销毁旧组件；Hosted 到期后能从宿主获取新链接，不循环使用失效链接。
• 工具只执行允许的操作。 已测试有效输入、无效输入和无业务权限的用户；「每次询问」不会替代工具服务端鉴权。
• 预算与监控可用。 核对美元预算、有效期、请求与活跃会话上限；月度触顶动作符合业务预期。在「运营与管理」能找到宿主测试会话、来源和用量。

准备回滚与支持

保留已验证的宿主部署和组件版本。配置异常时，在「版本」选择旧版本并点击「回滚到此版本」，重新签发后验证；已签发令牌不变。需要立即停止某个用户访问时，使用封禁或批量撤销，并确认旧令牌已失败。

为支持人员保存故障时间、环境、公开智能体 ID、会话 ID、HTTP 状态、错误码与 X-Request-Id，不保存令牌或 API Key。按限制与错误选择恢复动作，再从宿主完成一次对话验证。

相关参考：配置智能体 · 组件参考 · 智能体 API

<praxis-agent> 在网页中呈现智能体对话。入口为 element.setOptions(options)；本页按属性、方法、事件排列，完整接入步骤见嵌入到网页。

初始化

首次设置必须包含 api.url、agent.name，以及 api.getToken 或 api.publishableKey。缺少时抛出 TypeError。登录用户选择 getToken，匿名访客选择 publishableKey，请二选一；同时提供时使用 publishable key，不调用 getToken。

下面是 Develop 的匿名页面示例。先在该环境创建可公开 key、保存嵌入策略并允许宿主来源，再替换 PRAXIS_PUBLISHABLE_KEY，从该来源提供 HTML。公开 key 不是服务器 API Key。脚本地址、版本和完整性值须使用同一发布版本。

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Course assistant</title>
<script type="module"
  src="https://kit-develop.praxisusercontent.com/v0.2.8/praxis-kit.js"
  integrity="sha384-vey+VZZcFIWJq9Fmv/nmLxspKtXRiL8XiDOfg2g2QFvwZi5MA+tkiQvPBtoMS8eU"
  crossorigin="anonymous"></script>
<praxis-agent style="display:block;height:600px;width:100%"></praxis-agent>
<p id="status" role="status"></p>
<script type="module">
  await customElements.whenDefined('praxis-agent');
  const agent = document.querySelector('praxis-agent');
  const status = document.querySelector('#status');
  agent.addEventListener('praxis.ready', () => { status.textContent = 'Interface mounted'; });
  agent.addEventListener('praxis.error', () => { status.textContent = 'Check the failed network request'; });
  agent.setOptions({
    api: {
      url: 'https://api-develop.deepraxis.com',
      publishableKey: 'PRAXIS_PUBLISHABLE_KEY',
    },
    agent: { name: 'Course assistant' },
    locale: 'en',
  });
</script>
</html>

预期结果： 页面显示聊天界面，发送问题后收到真实回复。Interface mounted 只表示挂载；验证还要检查回复和用户隔离。

属性

api 与 agent

布局与内容

theme

未设置 accent 时，浅色默认 #167A43，深色默认 #30a46c。颜色前景按对比度选择。

React 属性

React 的 PraxisAgent 使用以下属性。当前 React 绑定仍要求顶层 getToken，即使 options.api 的类型包含 publishableKey；匿名接入可直接使用上面的 Web Component。

方法

React 控制句柄包含上表从 sendUserMessage 到 toggle 的方法。onReady 前或卸载后调用会抛出未就绪错误，不会排队。React 页面上下文与工具用 usePraxisReadable、usePraxisTool，需要共享注册范围时使用 PraxisProvider，见下方指南。

事件

事件均为可冒泡、可穿过 Shadow DOM 的 CustomEvent。React 回调收到同一个事件对象，通过 event.detail 读取内容。

默认行为与生命周期

setOptions 递归合并对象、整体替换数组；显式 undefined 重置字段。api.url 和 api.publishableKey 初始化后不能改，变更会抛 TypeError；换后端或用户时销毁旧元素并重新创建。移除元素会释放连接与刷新计时器，不会撤销已签发令牌。

页面上下文快照最多 32 项、4096 UTF-8 字节，超出时从最早注册项开始省略并发出 log。Kit 的这些运行时选项与控制台保存的 iframe/Hosted 外观不是同一个配置入口，持久化外观有自己的字段与大小限制。

使用指南

嵌入令牌与用户 · 传入上下文 · 接入前端工具 · 自定义外观

本页适用于嵌入令牌、Kit、iframe 与 Hosted。表中的「来源」区分固定校验、控制台策略和组件行为；策略值以该智能体保存的配置为准。

限制

月度触顶动作 stop_new_sessions 拒绝新会话，alert_only 不拦截。控制台金额输入为美元，API 的预算字段为美分。会话预算耗尽后不能继续提交新的工作；保留工具确认和中断入口。

服务端错误

下列状态用于普通 HTTP 失败响应。事件流已经建立后，错误通过流内事件到达，不能再更改已发送的 HTTP 状态。「可重试」指原请求；修复配置或换取合法凭证后属于新的尝试。

EMBED_TOKEN_EXPIRED

401 · 访问阶段 · 不可直接重试。 令牌到期。可刷新 Kit 会重新取令牌，并对到期响应最多重放一次请求；Hosted 不刷新，须从宿主获取新链接。

EMBED_TOKEN_REVOKED

401 · 访问/事件流 · 不可重试。 令牌已撤销，Kit 停止刷新。结束旧访问，由宿主重新核验是否仍允许该用户进入；不要自动重签绕过撤销。

EMBED_ORIGIN_NOT_ALLOWED

403 · 来源检查 · 不可重试。 当前来源不被允许。核对实际 scheme、host、port，以及策略和签发时收紧的来源列表；修改后重新签发再验证。

EMBED_USER_BLOCKED

403 · 签发/新建会话 · 不可重试。 用户已封禁。由管理者在「运营与管理 → 终端用户」核查；确需恢复时解封并签发新令牌。

EMBED_RATE_LIMITED

429 · 请求/新建会话/匿名签发 · 可延后重试。 请求频率、活跃会话数或匿名每日会话额度触顶。分别等待限流窗口恢复、运行结束或下个 UTC 日；不能统一立即重试。

EMBED_BUDGET_EXHAUSTED

402 · 会话工作/匿名签发 · 不可重试。 会话预算或匿名每日花费用尽。由管理者核对预算；获准后以新令牌、新会话继续，或等待每日额度恢复，不循环重签规避上限。

EMBED_MONTHLY_CAP_REACHED

402 · 新建会话 · 不可重试。 月度上限已到且策略要求停止新会话。由管理者决定是否调整上限或触顶动作，或等到下个 UTC 月。

EMBED_FIELD_NOT_ALLOWED

400 · 签发/新建会话 · 不可重试。 使用了不允许的字段或初始事件。移除未获准的 agent_override；嵌入会话创建仅传 title、time_zone、initial_events，初始事件为纯文本 user.message（可带页面上下文）。

其他拒绝

会话权限、归档和事件内容错误见智能体限制与错误。

Kit 错误与重试

praxis.error 的 detail 可能是含 code、status、retryable、message 的 KitError，也可能只有 { message }。status: 0 表示没有 HTTP 响应。

非 Hosted 取令牌仅对可重试失败按 1、2、4 秒退避，最多重试 3 次；撤销或预算拒绝停止该重试。传输层自行恢复事件流时最多重连 5 次；界面可能接管恢复，不应另叠无限重试。

诊断入口

保留失败时间、环境、公开 agent_… ID、HTTP 状态、错误码和 X-Request-Id，不记录凭证。在「运营与管理 → 签发记录」核对令牌状态，再用会话回放定位发生阶段。修复后按测试嵌入接入复测；字段契约见智能体 API。

本页用于排查智能体配置和会话 API。嵌入令牌、来源、匿名配额与前端组件另见嵌入限制与错误；组织余额与配额见用量与费用。

请求与运行限制

预算对象使用 type: "limit"，max_list_cost.currency: "USD"，max_list_cost.amount 为正整数字符串，单位是美分；null 移除预算。它控制后续模型请求，不是费用预测。字符串长度按 JavaScript 字符串长度校验，非所有字符都占一个单位；工具 schema 的大小则按 UTF-8 字节计算。

按错误处理

原生 API 的错误体包含 error.type、error.message 和 request_id。服务端已分类的错误还可提供 error.code 与 error.retryable；请求解析阶段可能只有类型和消息。下列代码以实际响应为准，不能假设每个相同 HTTP 状态都表示同一个原因。

INVALID_PARAMS

HTTP 400。请求字段、格式或不支持的选项不合法。按错误消息修正请求，原样重试不会解决。

UNAUTHENTICATED

HTTP 401。凭证缺失或无效。确认当前环境和组织的 Key，重新认证后再请求。

SESSION_FORBIDDEN

HTTP 403。当前身份无权访问该会话。核对所属用户与组织，不自动重试，也不要通过换 ID 探测其他用户。

AGENT_NOT_FOUND

HTTP 404。智能体或版本不存在，或对当前身份不可见。使用创建响应中的 ID，并确认版本。

SESSION_NOT_FOUND

HTTP 404。会话不存在或不可见。核对返回的会话 ID 与调用身份，不能靠重试创建响应来恢复。

MODEL_NOT_ALLOWED

HTTP 400。选择的模型不在固定版本允许的模型集合中。使用允许的模型，或更新配置后创建新会话。

SESSION_CONFLICT

HTTP 409。会话状态与当前操作冲突。重新读取会话或待确认工具，再决定是否提交；不要重复提交已完成的工具结果。

SESSION_ARCHIVED

HTTP 409。会话已归档，不能继续发送消息。保留历史用于查询，新对话创建新会话。

INVALID_STATE

HTTP 409。当前状态不允许操作，例如删除仍在运行的会话。先中断或等到空闲、终止，再核对状态后操作。

INVALID_PAGE_TOKEN

HTTP 400。分页游标无效或不匹配当前查询。重新从第一页开始；后续原样传回 next_page，并保持筛选条件。

UPSTREAM_UNAVAILABLE

HTTP 502。上游暂时不可用，可在退避后重试。对创建或发消息先查询已有结果，避免重复产生任务。

SANDBOX_UNAVAILABLE

HTTP 503。运行环境暂时不可用，可在退避后重试。持续失败时记录请求标识并联系支持。

何时重试

error.retryable: false 时先处理原因。收到 HTTP 429 时读取 Retry-After，不要无间隔循环；临时上游或环境错误可以退避后重试。网络断开不能证明请求未执行，创建资源和发送消息前应先查询已知会话及事件。

事件流已经开始后，运行失败可能通过事件返回，不能只看建立连接时的 HTTP 成功状态。检查回复、工具待确认和会话状态；不要把接收消息成功等同于任务完成。

记录诊断信息

保留发生时间、环境、智能体与会话 ID、HTTP 状态、错误类型与代码，以及 X-Request-Id；若响应仅提供 request-id 或 request_id，同时记录该值。不要记录 Key、嵌入令牌或访客凭据。

随后查看会话与用量，对照 API 参考检查请求。需要复现时，从快速开始的最小请求缩小范围。

自动化把平台能力组合成脚本或工作流，由你主动运行，或由触发器自动启动。

选择入口

一次计算、批量处理或组合 API 调用，用脚本；跨时间等待、需要步骤检查点的任务，用工作流。把多个编排都会使用的能力封装成动作。动作没有独立运行入口，在脚本或工作流里调用它。

脚本失败后重跑会重新执行整段代码；已发生的效果不会回滚。需要自动执行时，在已发布目标上配置触发器。

先运行一次

在 Develop Console 创建 API Key，设置为 PRAXIS_API_KEY。在装有 curl 和 jq 的 Bash 中执行，使用 Bearer 认证完成一次加一计算，不调用模型：

export PRAXIS_API_URL="https://api-develop.deepraxis.ai"
: "${PRAXIS_API_KEY:?Set PRAXIS_API_KEY to your develop API Key}"
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"source":"export default async (input: { n: number }) => ({ answer: input.n + 1 });","language":"ts","input":{"n":41},"wait":60}' \
  | jq '{id,status,output,error}'

期望：status 为 completed，output 为 {"answer":42}。若仍在排队或运行，将返回的 id 存为 RUN_ID，再读取结果。继续按快速开始保存和发布脚本。

下一步

• 快速开始：用 curl 得到第一个结果，再发布脚本。
• 概念：版本、运行树、幂等与费用。
• 编写脚本：输入输出、平台能力、动作和日志。
• 触发器：定时与 webhook。
• 限制与错误：容量、超时和排错。

API 参考 → · Cookbook →

本教程使用 develop、Bash、curl 和 jq。所有命令在同一个 Bash 会话中按顺序执行；不需要安装 SDK。脚本只做加法，不调用计费能力。

1. 创建 API Key

打开 Develop Console → API Keys，创建 Key，并将其保存到环境变量 PRAXIS_API_KEY。Key 的管理说明见平台管理。

export PRAXIS_API_URL="https://api-develop.deepraxis.ai"
: "${PRAXIS_API_KEY:?Set PRAXIS_API_KEY to your develop API Key}"
command -v curl
command -v jq
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs?limit=1" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" | jq -e '.data | type == "array"'

期望：两个命令都能找到，最后输出 true，退出码为 0；这同时验证 Key 能访问自动化运行列表。

2. 临时运行脚本

创建运行接受源码和输入。wait 表示本次 HTTP 请求等待运行终态的最长秒数，范围 0–60，默认 0。wait: 60 最多等待 60 秒，运行提前结束就提前返回；等待结束不会取消运行。HTTP 200 表示已到终态（也可能失败），202 表示仍在排队或执行，两者都要检查 status。

SOURCE='export default async (input: { n: number }) => ({ answer: input.n + 1 });'
RUN=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg source "$SOURCE" \
    '{source:$source,language:"ts",input:{n:41},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
jq -e '.id | startswith("run_")' <<< "$RUN"

期望：输出 true，RUN_ID 是新运行的 ID。源码接收 n: 41，返回 answer: 42。

HTTP 202 的响应仍是 Run 对象。下面是字段节选（id 以实际响应为准）：

{
  "id": "run_...",
  "status": "running",
  "output": null,
  "error": null
}

保留 RUN_ID，按下一节 GET /automation/v1/runs/$RUN_ID，直到 completed、faulted 或 cancelled。不要因为等待结束就重复创建运行。

3. 读结果

用读取运行检查终态。下面的函数在约 3 分钟内轮询；脚本失败时打印真实错误并返回非零退出码。

read_result() {
  local result
  for attempt in $(seq 1 90); do
    result=$(curl --fail-with-body -sS \
      "$PRAXIS_API_URL/automation/v1/runs/$1" \
      -H "Authorization: Bearer $PRAXIS_API_KEY") || return 1
    case "$(jq -r '.status' <<< "$result")" in
      completed) jq -e '.output.answer == 42' <<< "$result"; return $? ;;
      faulted|cancelled) jq '{status,error}' <<< "$result"; return 1 ;;
    esac
    sleep 2
  done
  echo 'Still pending: retrieve the run again using its ID' >&2
  return 1
}
read_result "$RUN_ID"

期望：输出 true 且退出码为 0，证明运行已 completed，输出确实为 42。若仍未完成，保留 RUN_ID，再次读取；不要因为客户端等待结束就重复创建运行。

4. 保存为脚本并发布

把同一份源码保存为脚本草稿，读取当前 draft.revision 后发布版本。每次教程使用不同的名称。

命名空间由你自行取名，例如自己的项目名。下面的 docs-samples 只是示例；修改 NAMESPACE 后，后续请求会使用同一个命名空间。

NAMESPACE="docs-samples"
SCRIPT_NAME="hello-$(date +%s)-$RANDOM"
SCRIPT=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/scripts" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg namespace "$NAMESPACE" --arg name "$SCRIPT_NAME" --arg source "$SOURCE" \
    '{namespace:$namespace,name:$name,draft:$source}')")
jq -e '.id | startswith("scr_")' <<< "$SCRIPT"
DRAFT=$(curl --fail-with-body -sS \
  "$PRAXIS_API_URL/automation/v1/scripts/$NAMESPACE/$SCRIPT_NAME" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" | jq -er '.draft.revision')
curl --fail-with-body -sS \
  "$PRAXIS_API_URL/automation/v1/scripts/$NAMESPACE/$SCRIPT_NAME/versions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg revision "$DRAFT" \
    '{version:"1.0.0",expected_draft_revision:$revision}')" \
  | jq -e '.version == "1.0.0"'

期望：两次检查均输出 true；版本 1.0.0 已发布。若返回 PRECONDITION_FAILED，报错原文「草稿已修改」，重新读取草稿，确认内容后用最新 revision 发布。

5. 按版本运行

TARGET="$NAMESPACE/$SCRIPT_NAME@1.0.0"
RUN=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg target "$TARGET" \
    '{target:$target,input:{n:41},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
read_result "$RUN_ID"

期望：再次输出 true，结果仍为 42。保留 TARGET，下一步可以给它添加触发器。用完后可归档脚本；归档会保留名称和历史。

API 参考 → · Cookbook →

脚本和工作流描述要做什么；运行记录某一次执行；触发器决定何时执行。动作是执行期间调用的可复用能力。

定义、版本与标签

脚本与工作流共用 namespace/name，一个名字只能属于其中一种。草稿可以修改；发布的版本不可变，版本号不能复用。同版本同内容再次发布会返回已有版本。弃用版本保留历史，不等于删除。

版本和 dist-tag 遵循 npm 的引用方式：docs-samples/hello@1.0.0 固定版本，@^1.2.0、@~1.2、@1.x 选择范围，@latest 跟随标签。省略 @ 等价于 @latest。每次运行记录实际解析的版本。

正式版发布会按版本选择规则更新 latest；发布较低版本不会自动把它退回。预发布版本需显式指定标签，例如 beta。stable、beta 等标签可以移动；标签名不能是版本号或版本范围；latest 不能删除。移动标签影响之后解析它的运行，不改写已发布版本。

用发布版本管理不可变内容，用设置标签把标签指向已有版本。写标签不需要 If-Match。修改草稿则需要最新 ETag，发布草稿需要 expected_draft_revision。

动作没有语义版本号：兼容更新立即生效，调用记录保存实际修订。输入输出不兼容时使用新名字，避免破坏既有调用方。工作流发布时锁定脚本和子工作流依赖的精确版本，动作不锁定。

运行生命周期