开始使用

选择你需要的服务

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

智能体

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

模型

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

沙箱

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

搜索

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

管理你的云服务

API

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

浏览所有 API →

（待补充）

（待补充）

Core concepts

智能体服务封装模型调用、工具执行等能力：你定义职责、提供资料与文件、配置工具与协作，由智能体服务管理底层能力调用，通过智能体 API 完成业务任务。

与其他服务的关系

智能体建立在模型、沙箱、搜索等云能力之上；这些能力也向构建者独立开放，见选择服务。

出口

API 参考 → · Cookbook →

（待补充）

本页带你把一个服务型智能体放进自己的网页，让登录用户直接在页面里和它对话。你需要一个 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. 在控制台准备智能体

1. 在 Console 新建一个服务型智能体，写好指令并保存。
2. 为它设置嵌入策略：选择运行环境，在允许的来源里添加你的网站来源（如 https://shop.example.com）；本地调试可允许 localhost。
3. 记下智能体的 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 与签发令牌用的是同一个环境。

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

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

怎么选

• 最快嵌入网页：用 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-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 等。

API

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

下一步：嵌入到网页 · 嵌入令牌与终端用户

嵌入令牌是你的后端为一位终端用户签发的短期凭证。用它的人只能以这位用户的身份与指定智能体对话。

签发

POST /agent/v1/embed_tokens，用 API Key 鉴权，只在后端调用。

curl https://api-develop.deepraxis.com/agent/v1/embed_tokens \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_xxx",
    "external_user_id": "customer_123",
    "ttl_seconds": 900,
    "system_message": [{ "type": "text", "text": "当前用户会员等级：金卡" }]
  }'

示例域名为 develop 环境，正式地址上线后替换。期望：HTTP 200。

每次调用都会产生一份新的签发记录，签发不是幂等的。

返回：

{ "id": "emb_…", "token": "…", "expires_at": "2026-10-19T08:00:00.000Z" }

id 是这次签发的标识，用于吊销与查询；token 交给前端；expires_at 是 ISO 8601 UTC 时间。

跳转到 Hosted

验证用户登录后调用以下函数，userId 必须来自服务端登录态：

export async function openHosted(userId: string) {
  const response = await fetch("https://api-develop.deepraxis.com/agent/v1/embed_tokens", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PRAXIS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent: "agent_xxx", external_user_id: userId, hosted: true }),
  });
  if (!response.ok) throw new Error("Hosted issuance failed");
  const { hosted_url } = await response.json();
  return new Response(null, { status: 302, headers: { Location: hosted_url } });
}

期望：浏览器跳转后进入托管对话页。hosted_url 的 #c=… 片段携带60 秒内有效、只能用一次的凭证，不是嵌入令牌。托管页自动向 POST /agent/v1/embed/exchange 提交 { "code": "…" }，取得 { token, expires_at }。凭证已用、过期或无效时返回 NOT_FOUND（404），应重新签发，不要复用或分享这个链接。兑换凭证的期限与令牌有效期是两回事。

匿名访客

访客没有宿主登录态时，可向 POST /agent/v1/embed_tokens/anonymous 提交 { "publishable_key": "PRAXIS_API_KEY" }。这里的 PRAXIS_API_KEY 是可公开 key 的占位符，不能填服务器 API Key。响应含 { token, expires_at }，新访客还会收到 visitor_secret；后续请求带上这个 visitor_secret 可延续访客身份。它是私有访客凭证，不要公开。

接口验证浏览器来源白名单，并执行可公开 key 的匿名限额。不接受调用方指定 external_user_id、指令、预算或 Hosted 选项。每日会话与花费上限按 UTC 自然日计算，统计实际会话，不把令牌刷新计为新会话。

刷新

Kit 需要令牌时调用你提供的 getToken(current)：首次 current 为 null，更换时传入当前令牌。在里面请求你自己的后端，由后端重新签发并返回新令牌字符串即可。重新签发前先确认用户仍然登录。令牌只保存在浏览器内存里。

吊销

吊销单张令牌：

curl -X POST https://api-develop.deepraxis.com/agent/v1/embed_tokens/emb_xxx/revoke \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

期望：返回带 revoked_at 的签发记录。该令牌立即失效，它打开的事件流会收到 session.error（EMBED_TOKEN_REVOKED）后关闭，其他令牌不受影响。重复吊销返回同一条记录。上游吊销失败时返回错误，记录保持未吊销，可重试。

GET /agent/v1/embed_tokens 列出签发记录，可按 agent_id、external_user_id 过滤，用 limit（1–100，默认 20）和 page 翻页。记录里不包含令牌本身。

封禁终端用户

在智能体的嵌入策略里维护封禁名单（blocked_end_users）：名单里的 external_user_id 不能再获得令牌，签发返回 EMBED_USER_BLOCKED。名单在 Console 的嵌入设置里管理。

按终端用户管理（API 参考 为准）：

• POST /agent/v1/agents/{agent_id}/end_users/{external_user_id}/revoke_tokens：一次吊销该用户当前所有有效令牌，进行中的对话随即中断；
• POST .../block：封禁，同时立即吊销现有令牌，之后宿主为他签发新令牌会返回 EMBED_USER_BLOCKED；
• POST .../unblock：解封。

Console「运营与管理 · 终端用户」页提供同样的操作（见 Console：运营与管理）。

终端用户只能访问自己的会话

用嵌入令牌调用 API 的是终端用户，不是你的组织。他只能创建和读取自己名下的会话，看不到同一智能体下其他用户的会话，也不能调用签发、吊销、列出令牌这类宿主接口（调用会得到 404）。身份来自令牌，不来自请求里的任何参数。

智能体需要知道「这位用户是谁、他在看什么、能调用你的什么系统」。有五个渠道，按可信度和稳定性选用。

1. 智能体指令

在控制台配置，写智能体的角色、口吻和边界，所有会话共享。适合不随用户变化的内容。

2. 覆盖指令

签发令牌时传 agent_override: { "system": "…" }，替换这张令牌所属会话的指令；null 表示清空。仅当嵌入策略允许覆盖时可用，否则签发失败（EMBED_FIELD_NOT_ALLOWED）。适合按客户、按租户换一套话术。

3. system.message

宿主向智能体传入的可信事实，例如用户姓名、会员等级、语言。有两种写入方式：

• 签发令牌时：system_message 字段，文本块数组，合计不超过 8192 字节。会话开始后，这些内容在下一次模型请求里出现。
• 会话进行中：用 API Key 向会话发送 system.message 事件，内容为文本块数组。每次不超过 8192 字节，同一会话累计不超过 65536 字节；会话已归档时被拒绝。

多次写入会累积为宿主上下文，在系统提示里放在智能体指令之后，包在 <host_context> 标签中，压缩历史时也不会丢。

{ "type": "system.message", "content": [{ "type": "text", "text": "用户刚完成了订单 A1024 的支付" }] }

只有持有 API Key 的宿主能发 system.message；终端用户令牌不能。

4. 页面上下文

Kit 会在每条用户消息里附带页面登记的上下文（例如正在看的课程），体积上限 4096 字节、最多 32 项，并标记为不可信：它来自浏览器，用户可以改。需要可信事实时请用渠道 3。登记方法见前端工具与页面上下文。

5. 工具

智能体可以通过 MCP 调用你的系统，查订单、发起退货。平台在调用时会附带三个请求头：

只有会话属于某位终端用户时才带这些头。你的工具必须按 X-Praxis-External-User-Id 限定数据范围，例如只返回这位用户自己的订单。不要依赖模型传来的参数确定用户：它可以被诱导。「好物集」演示站的订单 MCP 就是这样做的。

选哪个

• 所有用户都一样：用渠道 1。
• 按用户或租户变化的事实，必须可信：用渠道 3。
• 需要换一整套指令：用渠道 2。
• 要读写你的数据：用渠道 5，并在工具里鉴权。

智能体在对话里常常需要「此刻页面上的东西」：视频播到了哪里、表单填了什么、选中了哪一行。这些数据只在浏览器里，你的后端看不到。Kit 给了两个入口：

前端工具

分三步：在智能体里声明工具，在页面里实现它，智能体调用时 Kit 把结果送回去。

1. 在智能体定义里声明

在智能体的 tools 里加一项 type: "custom"。智能体只看得到名字、描述和输入结构，执行在你的页面里。

{
  "type": "custom",
  "name": "read_playback_progress",
  "description": "读取用户当前视频的播放进度，单位秒。用户问「我看到哪了」时调用。",
  "input_schema": { "type": "object", "properties": {} }
}

• name 必须匹配 ^[a-zA-Z0-9_-]{1,64}$，不能与其他自定义工具或内置工具重名。
• description 决定智能体何时调用它，写清楚用途和何时用。
• input_schema 是 JSON Schema，type 必须是 object。

2. 在页面里实现（Web Component）

把处理函数赋给元素的 onClientTool 属性。它是 JavaScript 属性，不是 HTML 属性，也不是 setOptions 的选项。

<video id="lesson-video" src="/lessons/3.mp4" controls></video>
<praxis-agent style="display:block;height:600px"></praxis-agent>

<script type="module">
  import "/praxis-kit.js";

  const video = document.querySelector("#lesson-video");
  const agent = document.querySelector("praxis-agent");

  agent.setOptions({
    api: {
      url: "https://api-develop.deepraxis.com",
      getToken: async () => {
        const response = await fetch("/api/praxis-token", { method: "POST" });
        if (!response.ok) throw new Error("暂时无法使用");
        return (await response.json()).token;
      },
    },
    agent: { name: "课程助手" },
  });

  // 前端工具：智能体调用时执行
  agent.onClientTool = async ({ id, name, input }) => {
    if (name !== "read_playback_progress") throw new Error(`未知工具：${name}`);
    return { positionSeconds: video.currentTime, durationSeconds: video.duration };
  };

  // 页面上下文：随每条用户消息附带
  agent.setReadable("lesson", "正在看第 3 课");
  agent.setReadable("playback", { positionSeconds: 83 });
  // 之后可以移除
  agent.removeReadable("playback");

  // 可选：观察调用与日志
  agent.addEventListener("praxis.tool.change", e => console.log(e.detail));
  agent.addEventListener("praxis.log", e => console.warn(e.detail));
</script>

处理函数收到 { id, name, input }：id 是这次调用的编号，name 是工具名，input 是智能体按 input_schema 传来的参数。Kit 不维护工具注册表，所有自定义工具都进这一个函数，所以对不认识的名字必须抛错。

返回值的处理：

2'. 在页面里实现（React）

React 绑定提供两个 hook：usePraxisTool 注册工具，usePraxisReadable 提供页面上下文。它们要在 <PraxisAgent> 的子树里，或在外层 <PraxisProvider> 里使用。

import { useMemo, useRef } from "react";
import {
  PraxisAgent, usePraxisTool, usePraxisReadable,
} from "@deepractice-ai/praxis-kit-react";

function LessonBridge({ lesson, videoRef }) {
  // 页面上下文：lesson 变化时自动更新，卸载时自动移除
  usePraxisReadable("lesson", `正在看第 ${lesson.number} 课：${lesson.title}`);

  // 前端工具：卸载或改名时自动取消注册
  usePraxisTool("read_playback_progress", () => ({
    positionSeconds: videoRef.current?.currentTime ?? 0,
    durationSeconds: videoRef.current?.duration ?? 0,
  }));
  return null;
}

export function LessonPage({ lesson }) {
  const videoRef = useRef<HTMLVideoElement>(null);
  const options = useMemo(() => ({
    api: { url: "https://api-develop.deepraxis.com" },
    agent: { name: "课程助手" },
  }), []);

  return (
    <>
      <video ref={videoRef} src={lesson.src} controls />
      <PraxisAgent
        options={options}
        getToken={async () => {
          const response = await fetch("/api/praxis-token", { method: "POST" });
          if (!response.ok) throw new Error("暂时无法使用");
          return (await response.json()).token;
        }}
        onToolChange={e => console.log(e.detail)}
      >
        <LessonBridge lesson={lesson} videoRef={videoRef} />
      </PraxisAgent>
    </>
  );
}

要点：

• usePraxisTool(name, handler)：handler 收到 (input, call)，可返回值或 Promise。handler 更换时自动使用最新的函数，不会重新注册。同名工具重复注册时，最后挂载的生效，开发模式下会警告；它卸载后恢复上一个。
• usePraxisReadable(name, value)：挂载时设置，JSON.stringify(value) 变化时更新，卸载时移除。值要能 JSON 序列化，变化要触发 React 渲染。
• 没有用 hook 注册的工具名，会交给 <PraxisAgent onClientTool={…}>；两者都不处理时，调用以 unknown tool <name> 报错返回给智能体。
• 想在 <PraxisAgent> 之外的组件里注册，把整棵树包在 <PraxisProvider> 里。
• options 请保持引用稳定（useMemo），见组件参考。

页面上下文

setReadable(name, value)（React 里是 usePraxisReadable）登记一条页面事实。此后每一条用户消息发出时，Kit 都会附带当前所有登记项的快照，包括首条消息、输入框发送、sendUserMessage 和推荐问题。

• name 匹配 [A-Za-z0-9_.:-]{1,64}；值是字符串或可 JSON 序列化的值。非法的名字或值会抛出 TypeError，且不会覆盖原来的值。
• 更新同名项保持它原来的位置；移除后重新登记会排到最后。
• 没有登记项时不附带任何内容。

服务端把它渲染成附在本轮用户消息末尾的一段文本，并明确标记为不可信：

<page_context untrusted="true">
<item name="lesson">正在看第 3 课</item>
<item name="playback">{"positionSeconds":83}</item>
</page_context>

它不进系统提示，也不会延续到下一轮：下一条消息带的是那一刻的新快照。所以页面状态变了，智能体下一轮自然看到新值，你不需要清理旧值。

超时、错误与未注册的工具

同一个调用编号只执行一次：Kit 在执行前先认领编号，并检查历史里是否已有结果。切换会话、断线重连、重新挂载都不会让已经回答过的调用重跑；还没有结果的历史调用在页面重新打开时可以被执行。这不是跨标签页的事务保证，同一会话在两个标签页打开时，不要让工具产生副作用。

事件

在元素上监听，都会冒泡并穿过 Shadow DOM。

React 里对应 onToolChange 和 onLog。

限制

给智能体看的数据要精简：只放这一轮可能用到的事实，大块数据用前端工具按需读取。

常见问题

• 工具没被调用：确认智能体定义里有同名的 custom 工具，并且 description 说明了何时用。
• 总是收到「not available」：onClientTool 要赋给元素的属性，且在智能体调用之前赋好；放在 setOptions 里无效。
• 上下文没有出现：确认值已登记且没有超过限制，留意 praxis.log 的警告。

下一步：工具授权 · 安全 · 组件参考

智能体能调用你的系统：查订单、改地址、申请退货。这一页讲两件事：哪些调用要先让用户确认，以及真正的权限在哪里卡住。

两档策略

每个工具有一个权限策略，只有两档：

没有第三档。写入 auto 会被拒绝（auto 尚未支持）。

策略写在智能体定义的 tools 里，MCP 工具集可以设整体默认，也可以逐个工具覆盖：

{
  "type": "mcp_toolset",
  "mcp_server_name": "orders",
  "default_config": { "permission_policy": { "type": "always_ask" } },
  "configs": [
    { "name": "list_orders", "permission_policy": { "type": "always_allow" } },
    { "name": "request_return", "permission_policy": { "type": "always_ask" } }
  ]
}

优先级：单个工具的 configs[].permission_policy，然后是 default_config.permission_policy，都没写则使用默认值。

默认值

此缺省规则适用于所有智能体的 MCP 工具。hint 来自 MCP 服务器，是不可信的提示，只影响缺省；单工具和工具集的显式配置始终优先。询问同样不是安全手段。给每个工具设策略时，按「用户自己能不能撤销、做错了代价多大」来决定：查询类放行，退款、删除、发送类保留询问。

确认卡

当某个调用的策略是 always_ask，对话会暂停，Kit 在对话里显示确认卡。终端用户选择允许或拒绝：

• 允许：调用继续，结果回到智能体。
• 拒绝：调用不执行，对话继续。

确认卡由 Kit 自带，你不需要写界面。会话预算用完后，会话不再接收新的任务，但仍然接收工具确认和中断。需要在自有界面里处理确认的宿主，可以用 API 发送 user.tool_confirmation 事件，字段为 tool_use_id 和允许 / 拒绝，详见 API 参考。

真正的安全：在工具服务端鉴权

智能体调用你的 MCP 服务器时，平台会带上三个请求头，说明这次调用代表谁：

这三个头只在会话属于某位终端用户时才带；没有终端用户的会话不带，你的服务要把缺失当作拒绝。它们来自平台对令牌的验证，不是模型可以填写的参数，所以是你唯一应该信任的身份来源。

规则：

1. 身份只取请求头。不要让工具接收 user_id 之类的参数再相信它：模型可以被诱导填任何值。
2. 每次查询都按用户限定范围。查询条件里带上用户，而不是查出来再过滤；操作一个具体对象（订单、地址）前先确认它属于这个用户。
3. 缺少身份就拒绝，返回错误，不要退化成匿名访问。
4. 服务本身也要认证调用方。MCP 服务器是公网地址，请求头可以被伪造；在智能体定义里为 MCP 服务器配置 headers（例如 Authorization: Bearer …），服务端先校验这个凭据，再信任 X-Praxis-* 头。
5. 危险动作在服务端再检查一遍业务规则（订单是否已签收、是否超过退货期），不要依赖「用户在确认卡上点过允许」。

示例：一个按终端用户限定范围的订单查询和退货工具（与 MCP 实现无关的部分）。

// 你的 MCP 服务器：每个请求先认证，再按终端用户执行
type Caller = { userId: string };

function authenticate(request: Request): Caller | Response {
  // 1) 认证 Praxis：智能体定义里为这个 MCP 服务器配置的 Authorization 头
  if (request.headers.get("authorization") !== `Bearer ${process.env.PRAXIS_MCP_SECRET}`) {
    return new Response("Unauthorized", { status: 401 });
  }
  // 2) 终端用户身份：只信平台附带的请求头
  const userId = request.headers.get("X-Praxis-External-User-Id");
  if (!userId) return new Response("Missing end-user identity", { status: 403 });
  return { userId };
}

// list_orders：只读，没有任何用户可选的参数
async function listOrders(caller: Caller) {
  return db.orders.findMany({ where: { userId: caller.userId } }); // 范围在查询里
}

// request_return：参数 order_id 来自模型，必须再校验归属和业务规则
async function requestReturn(caller: Caller, input: { order_id: string; reason: string }) {
  const order = await db.orders.findFirst({
    where: { id: input.order_id, userId: caller.userId }, // 不属于该用户就查不到
  });
  if (!order) return { isError: true, text: "订单不存在" }; // 与「不属于你」不作区分
  if (order.status !== "delivered") return { isError: true, text: "只有已签收的订单可以退货" };
  return db.returns.create({ data: { orderId: order.id, reason: input.reason } });
}

db 表示你自己的数据访问层。要点是：userId 永远来自 X-Praxis-External-User-Id，order_id 虽然由模型提供，但在带着 userId 的查询里才有效，别人的订单号查不出东西。

仓库里的「好物集」演示站（apps/kit-demo）的订单 MCP 就是这样做的：list_orders 声明 readOnlyHint: true，request_return 声明 destructiveHint: true，两者都从同一个请求头取用户。

选择策略的建议

下一步：安全 · 传入上下文

嵌入把一个智能体放进你的页面，页面的访问者就是智能体的使用者。这一页说明平台替你守住了什么、哪些要你自己守，以及宿主页怎样配置。

责任划分

隔离边界

• 令牌的主体是终端用户，不是你的组织。持有令牌的人只能创建和读取自己名下的会话，看不到同一智能体下其他用户的会话，也不能调用签发、撤销、列出令牌这类宿主接口（返回 404）。身份来自令牌，不来自请求参数。
• 跨用户、跨智能体一律 404，而不是 403：不告诉访问者「这个东西存在但不属于你」。
• API Key 永远不进浏览器。后端用它签发令牌；浏览器只拿令牌。令牌的签发与撤销见令牌与终端用户。

令牌

• 令牌有效期 60 到 3600 秒。设短一些：被截获的令牌价值有限。getToken 会在到期前被再次调用，换发时再确认一次用户仍处于登录状态。
• 令牌只存在于内存，不要自己写进 localStorage、Cookie 或页面 HTML。
• 发现泄露或用户登出时，按签发记录的 id 撤销，令牌立即失效，进行中的事件流会收到 EMBED_TOKEN_REVOKED 并关闭。
• 对某个用户启用封禁（blocked_end_users），他就拿不到新令牌。

来源白名单

嵌入策略里的 allowed_origins 限定哪些页面来源可以使用令牌。签发令牌时可以再收窄（传 allowed_origins，必须是策略白名单的子集）。来源不在名单上时，请求返回 EMBED_ORIGIN_NOT_ALLOWED（403）。

• 只接受 https 来源；https://*.example.com 形式的通配只匹配一级子域名，不含端口。
• 本地开发才打开 allow_localhost，上线前关掉。
• 来源由浏览器写入请求，它挡住的是别的网站拿你的令牌去用，挡不住拿到令牌的非浏览器客户端。令牌本身仍要妥善保管。

哪些不是秘密

下面这些内容，模型可能被用户要求复述，请当作公开信息对待：

• 智能体的指令（Console 里写的 instructions）。
• 覆盖指令（agent_override.system）。
• system.message 里的宿主上下文。
• 页面上下文和前端工具的返回值。
• 工具的名字、描述和输入结构。

所以不要在这些地方放密钥、内部规则、不想让用户看到的话术或别人的数据。需要保密的数据放在你的工具服务端，用终端用户身份控制谁能取到。

提示注入与不可信上下文

智能体读到的内容里，凡是来自浏览器或第三方的，都可能含有试图操纵它的指令：用户输入、页面上下文、网页内容、工具返回的文本。

• 页面上下文是不可信的。服务端把它放进附在本轮用户消息末尾的 <page_context untrusted="true"> 块里，不进系统提示，也不延续到下一轮。值里的 <、>、& 和引号会被转义，不能伪造出新的标签。详见前端工具与页面上下文。
• 可信事实走 system.message。只有持有 API Key 的后端能写入它，终端用户令牌不能。
• 不要靠指令里的「不要……」守住边界。真正要禁止的事，在工具一侧不提供，或者在服务端拒绝。
• 智能体可以调用的工具越少越安全：只为这个场景开需要的工具，写入类工具保留 always_ask，并在服务端校验。

iframe 与 Hosted

iframe 页的 frame-ancestors 来自智能体的来源白名单；白名单为空时禁止所有网站嵌入。Hosted 是独立页面，使用 frame-ancestors 'none'。平台托管的 chat 页从自身可信来源请求 API；宿主来源由 iframe 策略和跨窗口通信校验。

使用一行加载器时，宿主 CSP 还需在 frame-src 放行 https://chat-develop.praxisusercontent.com。加载器同时校验跨窗口消息的来源和发送窗口。Hosted 凭证只能使用一次，见嵌入令牌。

Shadow DOM

<praxis-agent> 渲染在 open Shadow DOM 里：宿主页的样式不会漏进对话，对话的样式也不会影响宿主页。这是样式隔离，不是安全边界：open 的 Shadow DOM 可以被页面脚本读取，同一页面上的任何脚本都能访问对话内容。不要把智能体嵌入你不信任的第三方脚本也在运行的页面里，需要强隔离时使用 iframe。

内容安全策略（CSP）

如果你的页面设置了 CSP，需要放行 Kit 脚本所在的来源，以及 Kit 连接 API 的来源。

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://kit-develop.praxisusercontent.com;
  connect-src 'self' https://api-develop.deepraxis.com;
  frame-src https://chat-develop.praxisusercontent.com;

要点：

• connect-src 里的 API 地址要和 setOptions 的 api.url 一致，也就是签发令牌的那个环境。
• 如果你自己托管 Kit 的构建（如快速开始里的 /praxis-kit.js），script-src 'self' 就够了，不需要放行 CDN。
• Kit 会向 Shadow DOM 里插入 <style> 元素（用于主题）。设置了严格 style-src 的页面，需要允许内联样式，例如 style-src 'self' 'unsafe-inline'。
• 头像、启动图片等你通过选项传入的图片地址，要放行 img-src。
• 宿主页面被别人嵌入的保护由宿主自己的 frame-ancestors 决定。

子资源完整性（SRI）

从 CDN 加载时，用不可变路径并加上 integrity，浏览器会校验文件内容，CDN 被篡改时拒绝执行：

<script
  type="module"
  src="https://kit-develop.praxisusercontent.com/v0.1.0/praxis-kit.js"
  integrity="sha384-…"
  crossorigin="anonymous"
></script>

• integrity 的值（sha384-…）由发布 Kit 版本时给出，路径里的版本号（v0.1.0）对应一次不可变的发布，内容不会改变。
• 必须带 crossorigin="anonymous"，否则浏览器不会校验。
• 浮动路径 https://kit-develop.praxisusercontent.com/v1/praxis-kit.js 会随新版本更新内容，不要配 integrity，配了会在下次发布后加载失败。需要锁定内容时请用不可变路径。

上线前检查清单

• API Key 只在后端，页面和仓库里找不到。
• external_user_id 来自你的登录态。
• allowed_origins 只有你的站点，生产环境没有开 allow_localhost。
• 令牌有效期合理，登出时撤销令牌。
• 指令和 system.message 里没有秘密。
• 工具服务端按 X-Praxis-External-User-Id 鉴权，并认证调用方。
• 页面 CSP 放行了 Kit 与 API，CDN 加载使用不可变路径和 SRI。

相关：工具授权 · 令牌与终端用户 · 限制与错误

服务型智能体是放进你自己的网站或应用、替你的用户回答问题和办事的智能体。每个智能体有两个工作台：接入与配置用来把它做好、接上线；运营与管理用来看它跑得怎么样，见运营与管理。本页讲前者。

打开 Console，进入「服务型智能体」，点「新建服务型智能体」，或点列表里已有的智能体。页面顶部显示名称、版本徽标（如 v3）、状态标记和短号，短号旁边的按钮可以复制。两个工作台在页签栏左侧切换：「接入与配置」「运营与管理」。接入与配置有五个页签：

页面右上角的「发布新版本」会带你到「版本」页签。

试用调试

先在「配置 · 安全」里保存嵌入策略，才能试用；没有策略时页面会提示「先在『配置 → 安全』里设置嵌入策略，才能试用」，点「去配置」直达。

• 形态：顶部的 inline、popup、sidebar、modal 切换智能体在页面里的样子，与网站嵌入时的布局一一对应。
• 版本：下拉选择试用哪一版，默认是嵌入策略固定的版本，没有固定则是最新版。切换版本会重新签发令牌并开始新对话。
• 调试面板有三个页签：
  • 「上下文」：当前版本的指令（只读）和宿主传入的上下文（host_context）。「页面上下文」可添加、删除名称和值，每条用户消息会带上这些内容。
  • 「事件」：嵌入组件触发的事件列表（ready、error、thread.change、response.start、response.end、open、close 等），点一条展开详情。
  • 「模拟」：填写 external_user_id 和 system_message，点「重新签发」，用这个身份开始新对话。用来检查「不同用户看到不同内容」。

期望：点「重新签发」后对话区重置，「上下文」页签里 host_context 显示你填的 system_message，「事件」页签出现 ready 事件。这与你的后端签发令牌是同一件事，见嵌入令牌与终端用户。

配置

左侧是配置分组，右侧是内容。

保存与版本

「基本」「指令」「模型」「工具与授权」「MCP 与凭据」里的修改是一份草稿，页面底部的保存栏会列出改动过的分组。点保存会生成新版本；已固定版本的嵌入不会自动升级，见下文「版本」。离开页面前有未保存的改动会提示。

「安全」和「凭据库」是另外保存的：各有自己的保存按钮，保存后显示「已保存，不产生新版本」。

工具与授权

「授权方式」列出已启用的工具，每个选「自动执行」或「每次询问」。每次询问会在对话里弹出确认卡。询问确认只是帮终端用户确认意图，不是安全手段，工具应按终端用户在服务端鉴权，见工具授权。MCP 服务器可以设置默认授权，也可以逐个工具设置。

MCP 与凭据

在这里添加智能体要调用的 MCP 服务器。页面上的说明提醒：平台调用 MCP 时会附带 X-Praxis-External-User-Id、X-Praxis-Agent-Id、X-Praxis-Session-Id 三个请求头，工具应据此按终端用户鉴权。

下方「凭据库」勾选后保存：会话按凭据的「允许的主机」或 MCP 地址自动匹配凭据来调用 MCP 服务器。还没有创建嵌入策略时，这里会提示先到「安全」创建。

安全

这是嵌入策略，决定谁能签发令牌、令牌能做什么。

第一次保存会创建嵌入策略；没有策略时不能签发令牌。每一项的详细含义见嵌入令牌与终端用户和安全。

版本

「版本」页签左侧是版本列表：版本号、创建时间、相对上一版的改动摘要，当前被嵌入使用的那一版带「嵌入中」标记。点版本号 vN，右侧显示它与上一版的对比。

嵌入使用哪一版由嵌入策略决定：

• 未固定：列表顶部显示「未固定，跟随最新」，之后新签发的令牌用最新版本。
• 固定：点某一版右侧的「设为嵌入版本」（最新版）或「回滚到此版本」（更早的版本），确认后新签发的令牌使用这一版。已固定时，列表顶部出现「取消固定」，确认后恢复跟随最新。

已经签发的令牌不变：确认框里会写明「已签发的令牌不变」，旧令牌到期前仍使用签发时的版本。没有嵌入策略时这些按钮不可用，页面会提示先到「配置 · 安全」设置。「近 7 天会话数」一列目前显示「—」。

接入方式与外观

进入「接入方式与外观 → iframe」，在实时预览旁调整外观，点「保存」。期望：显示「已保存，嵌入页刷新后生效」，刷新宿主页面验证。未配置来源白名单时，iframe 会被所有网站拒绝，请先到「配置 → 安全」设置。

保存的外观作用于 iframe 与 Hosted。Kit 组件的外观写在宿主代码里。Hosted 页签提供「打开预览」和后端跳转示例；接入代码见嵌入方式。

可保存的外观

图片（agent.avatar、header.icon、launcher.image）必须使用 HTTPS。保存对象最多 8 KB；名称最多 40 字符，问候语 200 字符；推荐问题最多 4 个，每个标签最多 40 字符、问题最多 200 字符；输入框占位文字最多 80 字符，免责声明 200 字符，页脚 120 字符。保存外观不能包含凭据或可执行回调。

GET /agent/v1/embed/appearance 通过嵌入令牌或可公开 key 确定智能体并读取外观，不接受智能体 ID、短号或其他寻址参数；嵌入令牌放在 Authorization: Bearer <token>，可公开 key 放在 Praxis-Publishable-Key: PRAXIS_API_KEY（占位符）；组织 API Key 不能通过此端点读取。未保存外观时返回 {}。iframe 与 Hosted 页会自动加载。

密钥

签发令牌用的 API key：你的后端用 API key 为自己的登录用户签发嵌入令牌，key 只放在服务器上。页面给出一个签发示例命令和「复制」按钮，旁边「去 API Keys 创建」带你去创建 key。下方「最近用于签发本智能体令牌的 key」基于最近 50 条签发记录，显示每个 key 最近一次用于签发的时间和次数；还没有时显示「还没有用 API key 签发过」。

可公开 key：这一栏可以新建、编辑、停用、启用和删除可公开 key，并设置名称、匿名每分钟上限、单会话预算、每日会话数上限和每日花费上限（金额单位为元，留空表示不限）。新建后完整的 key 值只显示一次，请立即复制。可公开 key 可以出现在网页源码里，保护依赖「配置 · 安全」的来源白名单和这里的各项上限。匿名访客可通过 POST /agent/v1/embed_tokens/anonymous 换取令牌，见嵌入令牌。可公开 key 与服务器上的 API Key 是两种凭据。

期望：新建可公开 key 后弹出「只显示这一次」对话框，列表里出现这把 key 的前缀、状态「启用」和各项上限。

下一步：运营与管理 · 嵌入到网页

智能体上线之后，在「运营与管理」工作台看它跑得怎么样，并处理个别用户的问题。打开 Console「服务型智能体」，选中一个智能体，点页签栏左侧的「运营与管理」。五个页签：

接入与配置见接入与配置。

概览

右上角选时间范围：24 小时、7 天、30 天。

• 指标：会话、活跃终端用户、花费、每会话花费、好评率、首字延迟 P50、错误率。没有对应样本时显示「—」。首字延迟、错误率、工具调用与需要关注的计数来自平台统计，无需配置 Observability。
• 会话量：24 小时按小时、其余按天的趋势图。没有会话时显示「暂无会话」。
• 来源分布：会话来自哪里——嵌入 · Kit 组件、嵌入 · iframe、托管对话页、API、自动化。
• 版本分布：各版本的会话数和占比，当前版本带「当前版本」标记。想看新版本发布后流量是否切过去，用它。
• 花费趋势：24 小时按小时，其余按天。
• 需要关注：所选时间范围内的「来源被拦」「预算触顶」次数。
• 工具调用 Top 5：按调用次数显示工具排行；没有调用时显示「暂无工具调用」。

会话

列表列出这个智能体的所有会话：标题、终端用户、来源、版本、最后活跃和状态（空闲、运行中、重试中、已结束、已归档）。消息数、花费、反馈三列目前显示「—」。

• 筛选：输入终端用户 ID 点「筛选」，或在「来源」下拉选 Kit、iframe、托管页面、API、自动化。
• 回放：点一行，右侧展开只读的对话回放，头部显示终端用户、来源、版本和创建时间。回放里不能发送消息，也不会改动会话。
• 归档：回放头部的「归档」会让会话不能再继续发送消息，对话记录仍可查看，需确认。
• 列表较长时点「加载更多」。

期望：点开一个会话，右侧出现完整对话；点「关闭回放」收起。

终端用户

终端用户是宿主在签发令牌时给出的 external_user_id。表格列出终端用户 ID、首次出现、最后活跃、会话数、花费和状态（正常或已封禁），可按用户 ID 前缀搜索。点用户 ID 打开详情抽屉，里面有基本信息和最近会话，点最近会话会跳到「会话」页签。

每行有两个操作，点后都会弹出确认框：

已封禁的用户行上显示「解封」，其余显示「封禁」。「配置 · 安全」里显示的封禁人数与这里一致，封禁名单在这里管理。被封禁用户的签发请求会收到 EMBED_USER_BLOCKED，见限制与错误。

用量与预算

页面显示本月花费、月度上限与触顶动作、7/30/90 天的每日花费、预算与限流、本月来源拆分，以及花费最高的终端用户 Top 20。本月统计按 UTC 自然月计算。点「修改上限」进入「配置 · 安全」。「花费构成」仍显示「即将上线」。

签发记录

每次宿主后端签发嵌入令牌都会留下一条记录：签发时间、终端用户、版本、签发者（成员或 API Key，显示前 8 位）、来源 origin、过期时间和状态（有效、已过期、已吊销）。记录里不包含令牌本身。

• 按终端用户 ID 筛选，点「筛选」；在「状态」下拉选全部、有效、已过期或已吊销。
• 有效的令牌右侧有「吊销」：确认后这张令牌立刻失效，正在进行的对话被中断，宿主可以重新签发，页面提示「令牌已吊销。」。只吊销这一张，同一用户的其他令牌不受影响；要一次吊销某个用户的全部令牌，用「终端用户」页签。
• 还没有记录时显示「还没有签发记录」，宿主通过 API 签发令牌后会出现在这里。

签发记录是排查「用户说打不开」的第一站：先找到该用户最近一条记录，看状态是不是已过期或已吊销，再看来源 origin 是否在来源白名单里。

下一步：接入与配置 · 嵌入令牌与终端用户

<praxis-agent> 是一个 Web Component，把智能体对话界面嵌入你的页面。本页列出它的选项、方法和事件，以及对应的 React 组件。

选项

通过 setOptions 传入。首次调用必须包含 api.url、api.getToken 和 agent.name，缺任何一项会抛出 TypeError。

launcher

header

theme

未设置 accent 时使用默认绿色（浅色 #167A43，深色 #30a46c）。

startScreen

更新选项

setOptions(partial) 把传入的字段合并进当前配置：嵌套对象逐层合并，数组整体替换，显式传 undefined 会重置该字段。api.url 不能改。

方法

在元素上直接调用。

事件

事件都是冒泡、可穿过 Shadow DOM 的 CustomEvent。

const agent = document.querySelector("praxis-agent");
agent.addEventListener("praxis.thread.change", event => {
  console.log(event.detail.threadId);
});

React

React 组件来自 @deepractice-ai/praxis-kit-react，需要 React 18 或 19。

import { PraxisAgent, usePraxisAgent } from "@deepractice-ai/praxis-kit-react";

export function Chat({ options, getToken }) {
  const { ref, control } = usePraxisAgent();
  return (
    <PraxisAgent
      ref={ref}
      options={options}
      getToken={getToken}
      layout="popup"
      launcher="bubble"
      onReady={() => control.open()}
    />
  );
}

属性

layout 和 launcher 请通过属性或 options 设置，不要写成 HTML 属性。更新 options 时请保持嵌套对象引用稳定（例如 useMemo），否则每次渲染都会触发更新。

控制句柄

ref 暴露的句柄包含 sendUserMessage、setThreadId、setComposerValue、showHistory、hideHistory、focusComposer、open、close、toggle，参数与上文方法一致。在 onReady 之前，以及组件卸载之后调用，会同步抛出 Error("PraxisAgent is not ready. Wait for onReady before calling control methods.")，调用不会排队。

usePraxisAgent() 返回稳定的 { ref, control }：把 ref 传给组件，在组件外用 control 调用方法。

前端工具与页面上下文

usePraxisTool、usePraxisReadable、PraxisProvider 和 onClientTool、onToolChange、onLog 见前端工具与页面上下文。

iframe 加载器

加载器负责令牌请求和跨窗口通信。属性与接入示例见嵌入方式。加载后可用 window.PraxisKit.get("ABC123") 取得句柄（换成智能体短号），调用 open()、close()、toggle()；远程组件方法返回 Promise。前端工具通过句柄的 onClientTool(handler) 注册。

本页列出嵌入时会碰到的上限和错误码。标注「策略」的值由你为智能体配置的嵌入策略决定，其余是平台固定值。

上限

签发令牌

策略

月度花费按 UTC 自然月统计。

会话与消息

错误

错误从两处到达页面：接口返回的错误体，以及 Kit 自身产生的错误。传输错误通过 praxis.error 事件的 detail 交给你，字段为 code、status、retryable 和 message；会话加载或发送失败可能只有 message，按错误码分支前先检查 code 是否存在。

EMBED_* 错误码

相关的通用错误码

Kit 自身产生的错误码

这些错误没有对应的接口响应，status 为 0 或接口状态码。

getToken 失败时，Kit 按 1、2、4 秒的间隔最多重试 3 次，之后令牌状态变为过期并发出 praxis.error。

暂不支持

以下能力在嵌入里尚未提供：

• 按消息切换模型
• 工具模式
• 语音输入
• entities、commands、widgets
• 按终端用户的记忆

（待补充）

（待补充）

（待补充）

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

选择入口

一次计算、批量处理或组合 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。

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

运行生命周期

脚本没有 waiting 和 suspended。取消请求尚未结束时，运行可能仍为 running，并带 cancel_requested_at。超时是 faulted，错误类型为 timeout，不是另一个状态。终态不会恢复；重跑创建新的根运行，rerun_of 指向原运行。

HTTP 成功表示请求被处理，不代表脚本成功。分别检查 status、output 和 error。脚本可查看调用与日志，工作流可查看步骤与等待点。

子运行与来源

脚本可以通过 praxis.automation.runs.create 启动子运行。子运行的 initiator 始终保留最初发起者（人、API Key 或触发器）；父子关系由 parent_run_id 表达。按来源筛选子运行用 channel=run，按指定父运行查找用 parent_run_id 过滤；公开详情中的 parent 提供父运行摘要，root_run_id 指向根运行。

父运行被取消时向下级联；父正常结束时子运行可以继续。子运行 deadline 不会超出父运行剩余时间。同一目标在调用链上再次出现会被循环检测拒绝；深度和扇出上限见限制。

幂等与重试

创建运行接受 Idempotency-Key。作用域为同一 owner、HTTP 方法、路径和 key，保留 24 小时；请求指纹不包含 wait。网络重试应复用原 key 和请求内容；重放返回当前运行，并带 Idempotent-Replayed: true。有意再跑一次时使用新 key。

同 key 不同请求返回 IDEMPOTENCY_KEY_MISMATCH；尚在处理时返回 IDEMPOTENCY_IN_FLIGHT，详见创建运行的错误表。幂等不提供事务回滚，失败前已经完成的调用可能产生了效果。

费用归因

运行本身不单独收费。运行中调用模型、搜索等能力产生费用，按这些能力的原价计费，并归因到运行与触发器上显示。没有能力调用的纯计算脚本不会产生模型或搜索费用。

API 参考 → · Cookbook →

脚本默认导出一个接收输入的函数；返回值成为运行的 output。

执行本页前，先在同一个 Bash 会话完成快速开始第 1–3 步：设置 PRAXIS_API_URL 与 PRAXIS_API_KEY、定义 SOURCE 并临时运行、定义并调用 read_result 辅助动作。该动作检查结果是否为 42，与本页的加一示例对应。

入口与 schema

把下面的内容保存为 script.ts：

export default async (input: { n: number }): Promise<{ answer: number }> => {
  console.log("Adding one", input.n);
  return { answer: input.n + 1 };
};

输入 schema 从参数类型推导；输出 schema 从显式返回类型推导，Promise 会展开。支持基本类型、对象、数组、联合类型及可解析的本地类型别名。不能推导的类型会得到空 schema 和警告；不要把空 schema 当成已经验证了字段。省略返回类型时，不应依赖返回表达式自动推导出输出约束。

通过校验定义检查实际生成的 schema，再发布：

curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/validate" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --rawfile source script.ts '{kind:"script",source:$source}')" \
  | jq -e '.valid == true and .input_schema.properties.n.type == "number" and .output_schema.properties.answer.type == "number"'

期望：输出 true，退出码 0。读取完整校验响应中的 errors 与 warnings 可以定位不能推导的类型。

运行与日志

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 --rawfile source script.ts \
    '{source:$source,language:"ts",input:{n:41},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
read_result "$RUN_ID"
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs/$RUN_ID/logs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

期望：结果断言为 true；日志响应包含 Adding one 41。console.log/info/debug 记录为 info，console.warn 和 console.error 保留各自级别。日志不是返回值；需要交给调用方的数据必须 return。可通过日志接口读取，或使用 Accept: text/event-stream 订阅。

全局 praxis

运行时已经提供 praxis，无需 import、API Key 或安装包。它提供以下 SDK 入口；方法参数采用参考页中的 path、query、body 形状，例如 praxis.automation.runs.create({body:{target,input}})。能否调用仍取决于发起者权限。

脚本不能直接访问外部网络。用平台提供的能力完成操作，并 await 调用以取得结果及处理异常。

调用平台内置动作

call("命名空间/名字", 输入) 接收 Action 引用和输入对象，返回 Action 的输出。它是当前运行里的一个步骤：有自己的输入、输出，并在调用记录里占一条，不会产生子运行。praxis 是平台命名空间；省略命名空间的裸名也只解析到平台 Action。调用总使用 Action 的当前修订，暂不支持 @版本；不再接受 命名空间::名字 写法。

调用失败时抛出错误，带 code、message、hint、调用记录序号 seq 和 request_id。多个 call 可以用 Promise.all 并发。praxis.* 只表示平台 SDK，call(...) 和 praxis.ocr(...) 这类写法已删除，运行时会报错并提示改用 call。

把下面内容保存为 chat.ts；它调用 praxis/chat。模型由动作内置并由维护者选择，调用时不选模型；praxis/ocr、praxis/image、praxis/embed 也一样。旧 model 字段已废弃，传入的值会被忽略。此调用会产生模型费用：

export default async (input: { prompt: string }) => {
  return await call("praxis/chat", {
    messages: [{ role: "user", content: input.prompt }],
    stream: false,
  });
};

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 --rawfile source chat.ts \
    '{source:$source,language:"ts",input:{prompt:"Say hello in one sentence."},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" | jq '{id,status,output,error}'

期望：终态为 completed，output 为模型结果，error 为 null。若仍是 pending 或 running，重复最后一条 GET，直到终态；faulted 时读取错误，不能把 HTTP 成功当成模型成功。动作输入输出的完整约定可用读取动作查看 praxis/chat。

调用自建动作

以下示例创建动作，再用它的完整名字调用。生成的脚本源码中引用是字符串字面量，便于发布前校验。

ACTION_NAME="add-one-$(date +%s)-$RANDOM"
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/actions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg name "$ACTION_NAME" '{
    namespace:"docs-samples",name:$name,
    input_schema:{type:"object",properties:{n:{type:"number"}},required:["n"],additionalProperties:false},
    output_schema:{type:"object",properties:{answer:{type:"number"}},required:["answer"],additionalProperties:false},
    implementation:{kind:"code",language:"ts",source:"export default async (input: { n: number }) => ({ answer: input.n + 1 });"}
  }')" | jq -e '.id | startswith("act_")'
SOURCE="export default async (input: { n: number }) => await call(\"docs-samples/$ACTION_NAME\", input);"
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")
read_result "$RUN_ID"

期望：动作创建与运行结果均输出 true，结果为 42。用完后可归档动作。动作可复用，但不能在动作内部再编排其他动作、脚本或工作流。

调用另一个脚本或工作流

invoke("命名空间/名字@版本", 输入) 把另一个已发布的脚本或工作流作为子运行启动，等它结束后返回子运行的输出；省略 @版本 用最新版。和 call 的区别：call 是当前运行里的一个步骤，不产生子运行；invoke 产生一个有自己 ID、状态和日志的子运行，并在调用记录里用 child_run_id 指向它。

export default async (input: { urls: string[] }) => {
  // 多个 invoke 用 Promise.all 并发；子运行经队列启动，不受单次请求链长度限制。
  const pages = await Promise.all(input.urls.map(url => invoke("team/fetch-page", { url })));
  return { pages };
};

• 等待有上限：invoke 同步等待子运行结束，等待时间受父运行 deadline 限制。到期时抛出 INVOKE_TIMEOUT，消息里带子运行 ID；子运行不会因此被取消，可以用该 ID 另行读取结果。需要等很久的子运行，请在工作流里用 run: 步骤——工作流在等待期间不占用计算。
• 失败：子运行失败、被取消或无法创建时抛出错误，code 是子运行的错误码，message 带子运行 ID。目标不存在或已归档时立即失败，不会排队。
• 取消与超时：父运行被取消或失败时，仍在等待中的子运行会一起被取消。
• 查看子运行：列出运行时用 parent_run_id 筛选，得到每个子运行的 ID、目标、状态和耗时。
• 限制：每个运行最多 100 个子运行，同时执行的最多 20 个，多出的排队等待；嵌套最多 10 层，不允许自己调用自己。

脚本不能自行指定独立运行（detach）的子运行；需要“启动后不等结果”时，调用 创建运行。

返回值和时间预算

返回 JSON 可序列化的值；不要返回 undefined、BigInt 或循环引用。序列化后的 UTF-8 返回值最多 1 MiB，超过会使运行失败。大结果应保存到文件等存储中，返回引用。

脚本墙钟时间默认最多 5 分钟；CPU 时间最多 30 秒，并受剩余 deadline 进一步约束。等待平台调用与纯计算的耗时不同，增加等待时长不能解决死循环。全部数值见限制与错误。

有依据的错误与修法

运行失败看 Run.error；创建请求被拒绝看 HTTP problem 响应。两者不能混用。

API 参考 → · Cookbook →

触发器把“何时执行”与脚本、工作流的内容分开。

执行本页前，先在同一个 Bash 会话完成快速开始第 1–3 步：设置 PRAXIS_API_URL 与 PRAXIS_API_KEY、定义 SOURCE 并临时运行、定义并调用 read_result 辅助函数。该函数检查结果是否为 42，与本页的加一示例对应。再完成第 4–5 步：保存并发布脚本、设置 TARGET。TARGET 必须指向这个接收 n、返回 answer 的已发布脚本。

定时执行

每个 schedule 只能选择一种规则：

timezone 使用 IANA 名称，API 默认 UTC。当地时间 cron 在夏令时春季跳过不存在的时刻，秋季重复的时刻只运行一次。every 按时长、at 按绝对时间执行，不使用这条 cron 夏令时规则。

先预览下次时间：

curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/triggers/preview" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"schedule":{"cron":"0 9 * * *"},"timezone":"Asia/Shanghai"}' \
  | jq -e '{next_fire_times} | select(.next_fire_times | length == 5)'

期望：输出五个未来时间，例如：

{
  "next_fire_times": [
    "2026-10-13T01:00:00.000Z",
    "2026-10-14T01:00:00.000Z",
    "2026-10-15T01:00:00.000Z",
    "2026-10-16T01:00:00.000Z",
    "2026-10-17T01:00:00.000Z"
  ]
}

日期随预览时间变化。末尾的 Z 表示 UTC。例如 2026-10-13T01:00:00.000Z 换算为上海时间（UTC+8）10 月 13 日 09:00。timezone 决定 cron 按哪个当地时区计算，返回的时间统一用 UTC 表达。

再创建触发器，并立即触发一次检查目标：

TRIGGER=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/triggers" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg target "$TARGET" '{
    name:"daily-hello",target:$target,kind:"schedule",input:{n:41},
    schedule:{cron:"0 9 * * *"},timezone:"Asia/Shanghai",
    overlap:"skip",catchup_window_seconds:300
  }')")
SCHEDULE_ID=$(jq -er '.id' <<< "$TRIGGER")
jq -e '.state == "enabled" and (.next_fire_times | length == 5)' <<< "$TRIGGER"
FIRING=$(curl --fail-with-body -sS -X POST \
  "$PRAXIS_API_URL/automation/v1/triggers/$SCHEDULE_ID/fire" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' --data '{}')
jq -e '.outcome == "started"' <<< "$FIRING"
read_result "$(jq -er '.run_id' <<< "$FIRING")"

期望：三次断言输出 true。started 只表示启动成功；read_result 用返回的 run_id 读取运行，确认终态成功且结果为 42。

target 写 @1.0.0 固定版本，写 @latest 跟随标签；每条触发记录保存实际版本。创建和修改时检查静态输入，触发时再次检查，避免新版本不再接受原输入。

重叠、延迟与有效时间

默认 overlap: "skip"：上一次运行未结束时，本次记录为 skipped_overlap；allow 允许重叠启动，仍受运行并发限制。没有排队补齐、取消旧运行或历史 backfill 策略。

catchup_window_seconds 默认 300。调度延迟超过窗口记为 missed，不会启动；这不是恢复后重放所有错过任务的承诺。暂停期间不执行，恢复后继续未来调度。

用 start_at 与 end_at 设置有效时间范围（RFC 3339）。一次性 at 执行后、或达到结束时间后变为 expired。连续 5 次触发失败会自动暂停。通过暂停和恢复控制后续触发。

暂停上面创建的触发器，再恢复：

curl --fail-with-body -sS -X POST \
  "$PRAXIS_API_URL/automation/v1/triggers/$SCHEDULE_ID/pause" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' --data '{}' \
  | jq -e '.state == "paused" and (.next_fire_times | length == 0)'
curl --fail-with-body -sS -X POST \
  "$PRAXIS_API_URL/automation/v1/triggers/$SCHEDULE_ID/resume" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' --data '{}' \
  | jq -e '.state == "enabled" and (.next_fire_times | length == 5)'

期望：两次请求都输出 true；恢复后返回这个每日计划的下五次执行时间。

工作流 YAML 中的 cron/every schedule 在发布为 latest 时管理一个 source=definition 触发器；修改要重新发布定义，不能直接 PATCH 这个触发器。可以暂停或恢复它。schedule.after 与 schedule.on 暂不支持。

Webhook

创建时选 input_mode: "body"，收到的 JSON 就是运行输入；非 JSON 请求体作为字符串。以下示例把 n:41 传给快速开始的脚本：

HOOK=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/triggers" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg target "$TARGET" '{
    name:"webhook-hello",target:$target,kind:"webhook",webhook:{input_mode:"body"}
  }')")
WEBHOOK_ID=$(jq -er '.id' <<< "$HOOK")
WEBHOOK_URL=$(jq -er '.webhook_url' <<< "$HOOK")
curl --fail-with-body -sS "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -H "webhook-id: hello-$(date +%s)-$RANDOM" \
  --data '{"n":41}' | jq -e '.id | startswith("frg_")'

期望：HTTP 202，断言输出 true，响应含触发记录 ID。异步启动结果需要再查触发历史。

完整 URL 只在创建或轮换时返回；其中的 token 是凭据，无需 API Key，不要公开。旧 URL 在轮换后失效。错误 token、暂停或不存在的触发器都返回 404。请求体最多 1 MiB；相同 webhook-id 在 24 小时内去重。

签名头与 envelope

当前 webhook 入口验证 secret URL，不自动验证 Standard Webhooks、GitHub 或 Stripe 的 HMAC 签名。传入 webhook-signature 不代表它已经通过验签。

若目标需要读取头部，创建时使用 webhook: {input_mode:"envelope"}，并让目标的输入 schema 接受下列形状（这不是快速开始的 n 输入）：

{
  "body": { "n": 41 },
  "headers": { "content-type": "application/json", "webhook-id": "delivery-1" },
  "webhook_id": "delivery-1",
  "received_at": "2026-10-11T12:00:00.000Z"
}

webhook_id 未提供时为 null。只保留以下头：content-type、user-agent、webhook-id、webhook-timestamp、webhook-signature、x-github-event、x-github-delivery、x-hub-signature-256、stripe-signature；Authorization、Cookie 不会转交。

JSON body 会先被解析，envelope 不包含独立的原始请求字节。对于必须签署原始字节的协议，不能用 JSON.stringify(body) 代替原文验签。需要这种验证时，在你接收原始请求的服务中按发送方协议先验证，再转发到 secret URL。当前没有可直接套用到此 JSON envelope 的通用验签示例。

查看触发记录与清理

curl --fail-with-body -sS \
  "$PRAXIS_API_URL/automation/v1/triggers/$WEBHOOK_ID/firings" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  | jq -e '.data | length > 0'
curl --fail-with-body -sS \
  "$PRAXIS_API_URL/automation/v1/triggers/$WEBHOOK_ID/firings" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  | jq '.data[] | {outcome,run_id,resolved_version,error}'

期望：第一个请求输出 true，第二个列出记录。若异步处理尚未完成，稍后重新读取。started 表示已启动，failed 看 error，missed 表示超过窗口，skipped_overlap 表示前次未结束，deduped 表示命中去重。按 run_id 继续查看运行终态，记录保留 30 天。

测试完成后删除本页创建的两个触发器，避免继续定时执行：

for id in "$SCHEDULE_ID" "$WEBHOOK_ID"; do
  curl --fail-with-body -sS -X DELETE \
    "$PRAXIS_API_URL/automation/v1/triggers/$id" \
    -H "Authorization: Bearer $PRAXIS_API_KEY"
done

期望：curl 均退出 0。删除不影响已经启动的运行。

API 参考 → · Cookbook →

以下默认值约束单次运行及其子运行；调用方设置的更短 deadline 也约束后续执行。并发超限时排队，不会增加执行容量。

执行与数据

载荷软阈值不是拒绝边界；硬上限为 1 MiB，按 JSON 编码后的 UTF-8 字节计算。内联阈值决定数据的存储方式，不代表脚本可以返回超过硬上限的结果。

脚本运行时

脚本输出必须可序列化为 JSON，编码失败会使运行失败。脚本没有检查点或事务回滚；具体报错原文与修法见编写脚本。

触发器

找到对应错误

HTTP 错误表示请求被拒绝；运行状态 faulted 表示执行失败，即使读取它的 HTTP 响应为 200。排查时保存运行 ID 与响应头 X-Request-Id。

• 创建运行错误表：输入、目标解析、幂等与配额。
• 发布错误表：草稿已变、版本冲突与定义校验。
• 触发器错误表与调度错误表。
• Webhook 错误表：请求体大小、输入与不可用 URL。
• 鉴权与通用错误。

例如 INTERVAL_TOO_SHORT 的报错原文为 every must be at least one minute，把间隔改为 PT1M 或更长；不要原样重试无效调度。

API 参考 → · Cookbook →

统一接口访问 LLM、图像、语音、Embedding 模型；兼容 OpenAI 与 Anthropic 协议，现有 SDK 零改动接入。

出口

API 参考 → · Cookbook →

用一个云 API Key 调用 deepseek-flash，读取实付费用，再找到同一次调用的记录。示例会产生少量费用。

1. 准备 Key 与终端

在控制台 → API Keys点击「创建 Key」，填写名称并创建，将 Key 安全注入当前终端的 PRAXIS_API_KEY 环境变量。不要写入代码或日志。已有 Key 可直接使用。

准备 Python 3.10+ 和 uv，在 macOS / Linux 终端执行：

test -n "${PRAXIS_API_KEY:-}"

期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。示例默认使用 https://api.deepraxis.com；切换环境时，将 PRAXIS_API_BASE 设为对应 API 域名，不带末尾斜杠或 API 路径。

2. 发出请求并读取费用

保存为 quickstart.py，在该文件所在目录执行 uv run -q --no-project --with openai --with anthropic --with google-genai python quickstart.py。

import json
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PRAXIS_API_KEY"],
    base_url=os.environ.get("PRAXIS_API_BASE", "https://api.deepraxis.com") + "/openai/v1",
    timeout=90.0,
    max_retries=0,
)
raw = client.chat.completions.with_raw_response.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Reply with exactly: Hello Praxis."}],
    max_tokens=256,
)
reply = raw.parse()
usage = reply.usage.model_dump()
request_id = raw.headers.get("x-request-id")
generation_id = raw.headers.get("x-praxis-generation-id")
assert raw.status_code == 200 and reply.choices[0].message.content
assert request_id and generation_id
assert isinstance(usage.get("cost"), (int, float)) and usage["cost"] >= 0
print(reply.choices[0].message.content)
print("usage:", usage)
print("X-Request-Id:", request_id)
print("X-Praxis-Generation-Id:", generation_id)
Path("quickstart-result.json").write_text(json.dumps({
    "request_id": request_id, "generation_id": generation_id, "cost": usage["cost"],
}))

期望：退出码 0，输出非空回答（通常为 Hello Praxis.）、usage 和两个 ID，并生成 quickstart-result.json。该文件只保存本次调用的 ID 与费用，不含 Key。

usage 包含输入和输出 token 数；usage.cost 是本次实付美元金额，不是每百万 token 的单价。不要把缺失费用当成零。字段定义见 Chat Completions API。

3. 找到这次调用

打开控制台 → 模型 → 调用日志。在「按 X-Request-Id / Generation ID 查找」输入框粘贴上一步的 X-Request-Id，按 Enter。此路径与控件名核对于 2026-10-13 的 Console。

期望：出现模型为 deepseek-flash 的本次调用，可查看状态、用量与费用。记录可能延迟几秒；使用与 Key 相同的账号及环境，并确保时间范围包含刚才的调用。

不使用浏览器时，可用下面的等价硬验证。保存为 verify-generation.py，在同一目录执行 uv run -q --no-project --with openai --with anthropic --with google-genai python verify-generation.py。

import json
import os
import time
from decimal import Decimal
from pathlib import Path
import httpx

saved = json.loads(Path("quickstart-result.json").read_text())
base = os.environ.get("PRAXIS_API_BASE", "https://api.deepraxis.com")
with httpx.Client(timeout=60.0) as client:
    for attempt in range(10):
        response = client.get(
            base + "/model/v1/generation",
            params={"id": saved["generation_id"]},
            headers={"Authorization": "Bearer " + os.environ["PRAXIS_API_KEY"]},
        )
        if response.status_code != 404:
            break
        time.sleep(3)
    response.raise_for_status()
    record = response.json()
    assert record["id"] == saved["generation_id"]
    assert record["model"] == "deepseek-flash"
    assert abs(Decimal(str(record["cost"])) - Decimal(str(saved["cost"]))) <= Decimal("0.0000005")
    print("Verified generation:", record["id"])
    print("cost:", record["cost"])
    print("X-Request-Id:", response.headers.get("x-request-id"))

期望：退出码 0，输出 Verified generation 和按美元六位小数记录的费用；脚本允许相应舍入差异。查询使用 X-Praxis-Generation-Id，不是 X-Request-Id 或响应正文的 id；详见生成记录 API。

失败分支

• 404 查询记录：记录尚未可查时，脚本每 3 秒重试，最多 10 次；仍失败则保留两个 ID，检查 Key、环境及生成 ID 是否来自同一次调用，再查询。
• Model "gpt-4o" does not exist.：模型 ID 不自动映射；使用本页的 deepseek-flash 或目录中的 ID。

接下来可使用流式响应或工具调用。

API 参考 → · Cookbook →

模型与价格会变化，请从控制台 → 模型目录或实时 API 读取，不依赖静态清单。

1. 准备查询

准备 Python 3.10+ 与 uv。原生目录 GET /model/v1/models 无需 Key；下面同时查询 OpenAI 兼容目录，需要按快速开始设置 PRAXIS_API_KEY。

期望：已有 Key 环境变量。示例默认使用 https://api.deepraxis.com；切换环境时，设置 PRAXIS_API_BASE 为 API 域名，不带末尾斜杠或 API 路径。

2. 核对模型与协议

保存为 catalog.py，执行 uv run -q --no-project --with openai --with anthropic --with google-genai python catalog.py。

import os
import httpx

base = os.environ.get("PRAXIS_API_BASE", "https://api.deepraxis.com")
with httpx.Client(timeout=60.0) as client:
    response = client.get(base + "/model/v1/models")
    response.raise_for_status()
    models = response.json()["data"]
    model = next(item for item in models if item["id"] == "deepseek-flash")
    assert "openai.chat.completions" in model["supported_apis"]
    for field in ("id", "type", "supported_apis", "context_window", "pricing"):
        print(field + ":", model[field])
    print("X-Request-Id:", response.headers.get("x-request-id"))

    filtered = client.get(
        base + "/openai/v1/models",
        params={"api": "responses"},
        headers={"Authorization": "Bearer " + os.environ["PRAXIS_API_KEY"]},
    )
    filtered.raise_for_status()
    ids = [item["id"] for item in filtered.json()["data"]]
    assert "deepseek-flash" in ids
    print("Responses models:", ids)
    print("X-Request-Id:", filtered.headers.get("x-request-id"))

期望：退出码 0，打印 deepseek-flash 的类别、协议、上下文和价格，以及包含该 ID 的 Responses 列表。示例核对于 2026-10-13；以查询时的结果为准。若断言失败，不要向所选协议发送请求，先从最新列表选择支持它的模型。

3. 根据结果选择

先按 type 找任务类别，再用 supported_apis 确认要调用的协议；不能从模型名称推断协议。原生列表还可用 supported_api=openai.responses 筛选；OpenAI 兼容列表的 api=chat,embeddings 表示匹配任一协议。

再核对上下文和输出限制，以及输入、输出、缓存或非 token 计量的单价。模型与目录概念解释计费单位及可用率；列出模型 API提供字段定义。

期望：所选 ID 支持应用需要的协议，限制能容纳请求，价格单位与任务一致。最后按快速开始发起真实调用并核对实付费用。

API 参考 → · Cookbook →

一次模型调用由模型 ID 指定要用的模型，由协议决定请求和响应的格式；平台在符合要求的线路中完成调用。

• 模型与目录：区分模型类别、协议支持与计费单位。
• 协议兼容：理解同一个地址下不同协议的适用范围。
• 路由：理解线路选择、失败换线与参数要求。
• 会话亲和：理解重复使用同一线路与缓存的关系。
• BYOK：查看自带凭证的开放状态。

第一次调用从快速开始进入；选择模型从模型目录进入。

API 参考 → · Cookbook →

模型目录描述可以选择什么；一次调用的记录描述实际用了多少、付了多少。两者用途不同。

模型 ID 与能力

请求中的 model 使用目录返回的完整 id，例如 deepseek-flash。显示名称不是 ID；相同 ID 也不表示底层版本永远不变，滚动版本应以模型说明为准。

type 区分语言、图像、语音、视频、向量等模型类别，不能据此推断它支持所有相关接口。supported_apis 才是已开放协议的列表；选择 Chat、Responses 或 Messages 前分别核对它。输入和输出模态说明能处理什么内容，不等于所有文件格式都能原生读取。

上下文窗口限制一次输入与生成可容纳的内容，不是每次必然能输出的长度。原生目录的字段为 context_window；OpenAI 兼容目录使用 context_length。输出上限需另看模型说明与 API 参考。

标价与实付

目录 pricing 的金额为美元，单位由价格项决定。token 单价以每个 token 表达，展示为每百万 token 时乘以一百万；输入与输出分别定价。input_cache_read 是缓存命中时的输入读价，不保证每次都会命中。

并非所有模型按 token 计费：视频可按秒、图像可按张、OCR 可按页、转写可按音频分钟。价格项缺失不表示免费，不要把所有数值都乘以一百万。具体价格项与字段定义见列出模型 API。

Chat 响应的 usage.cost 是本次实付美元金额；用目录单价乘以 token 数只是估算，可能忽略缓存或其他计量。需要核对实际调用时，使用快速开始中的生成记录查询。

可用率

可用率衡量平台与上游能否完成有效请求：平台或上游原因的失败计入，调用方参数等原因造成的拒绝不计入。它不表示任意参数都能成功，也不保证下一次请求必然成功。

模型目录说明如何获取当前目录；本页不维护静态模型与价格清单。

API 参考 → · Cookbook →

你选择模型，平台从支持该模型及所用协议的线路中选择一次调用的去向。同一个模型可以有多条线路；线路数量与状态会变化。

从请求到线路

平台先检查模型、协议和参数要求，再结合健康状态与优先级选择可用线路。备选线路必须支持同一种协议；Chat、Responses、Messages 之间不会为了换线而偷偷转换。

同优先级的可用线路还可能受会话亲和影响。优先级不是对某个供应商的永久绑定，也不是每次都选择最低价格的保证。

失败换线

当一次尝试因可重试的上游故障、限流或线路不可用而失败时，平台可自动尝试其他合适的线路。没有可用备选或尝试仍失败时，请求返回错误；不是无限重试，也不保证已开始的流式回答可以无缝续接。

调用方参数错误不靠换线修复。应用仍需检查完成状态，并按错误与限制处理失败。

参数要求与供应商选择

provider.require_parameters 要求线路声明支持请求中的相关工具与采样参数，避免把要求交给不支持它的线路。它限制候选线路，不会为模型增加能力，也不保证模型一定调用工具或生成某种回答；没有符合要求的线路时可拒绝请求。具体参数支持以 Chat API 参考为准。

provider 中指定供应商的 order、only、ignore 是 BYOK 专属选项；require_parameters 这种能力约束不属于供应商选择限制。平台模型由平台选线。BYOK 当前即将推出，不要依赖它指定平台供应商。

API 参考 → · Cookbook →

协议兼容让你沿用客户端的请求格式；不表示每个模型支持所有协议或官方的全部功能。以模型的 supported_apis 和各端点支持说明为准。

只有一个地址 https://api.deepraxis.com，按协议分入口：

OpenAI Chat Completions

POST /openai/v1/chat/completions。常用的对话协议；流式（SSE）、工具调用与多模态输入是否可用取决于模型。 模型能力与字段差异见 Chat API；会话标识的作用见会话亲和。

OpenAI Responses

POST /openai/v1/responses 及 retrieve / delete / cancel / input_items。OpenAI 新一代有状态协议；Codex 等 Agent 走这里。支持范围见 Responses API。压缩响应与输入 token 计数端点当前未实现，调用返回 501。

OpenAI Files

/openai/v1/files：上传 user_data 文件供后续请求引用；可列出、读元数据、下载、删除。

OpenAI Images

POST /openai/v1/images/generations：使用目录声明支持图像生成的模型。

Anthropic Messages

POST /anthropic/v1/messages。Claude Code、Anthropic SDK 走这里。 具体支持范围见 Messages API。

Anthropic Files

/anthropic/v1/files：上传、列出、读元数据、删除；上传后不可下载（与官方一致）。

Google Gemini API（generateContent）

POST /google/v1beta/models/{model}:generateContent。目前用于 Gemini 原生协议的图像生成与编辑。

模型目录

用 GET /openai/v1/models?api=responses 查找支持 Responses 的模型，api=chat,embeddings 匹配任一协议。原生目录 GET /model/v1/models 及模型详情会返回每个模型的 supported_apis；原生列表可用 ?supported_api=openai.responses 筛选。

GET /openai/v1/models：列出当前 Key 可调用的模型，OpenAI 风格返回；Kilo Code 等客户端靠它自动发现模型。

Anthropic 客户端使用 GET /anthropic/v1/models，Google 客户端使用 GET /google/v1beta/models；分别返回对应协议的模型列表。

标准化地址

以上每个入口还有一个标准化长路径 /v1/router/<vendor>/...，语义完全相同，见 API 参考。

→ 深入：OpenAI 兼容接口 · Anthropic 兼容接口

API 参考 → · Cookbook →

会话亲和让同一会话后续请求，在条件允许时优先复用之前成功的线路。它是一种选路偏好，不是锁定供应商，也不是替应用保存对话历史。

为什么有用

多轮对话常重复系统提示、工具定义和早期消息。重复前缀留在同一条支持缓存的线路上，更有机会命中上游缓存，降低重复输入的费用与延迟。相同会话 ID 不保证命中缓存；内容变化、缓存失效或换线都可能让它失效。

如何识别同一会话

客户端可用请求体的 session_id 或请求头 x-session-id 标识会话；两者同时存在时，请求体优先。没有显式会话 ID 时，还可能使用 prompt_cache_key 或从对话前缀推导标识。自动推导受内容变化影响，因此长期多轮对话应保持显式标识一致，不同对话使用不同标识。

何时生效

缓存亲和要求该线路支持本次模型与协议、输入得到保留，并且缓存读取价格低于普通输入价格。成功完成的调用才更新亲和记录；后续请求仍须通过当前的健康与能力检查。

亲和只在同优先级范围内调整顺序，不绕过冷却或参数要求。距上次成功已空闲 10 分钟、原线路不再合适，或亲和记录不可用时，按正常路由继续；因此应用不能依赖它保证状态永远留在同一上游。

Chat 请求仍应携带需要的消息历史。有状态 Responses 的续写属于独立的协议能力，不能用会话 ID 代替 previous_response_id。参数说明见 Chat API 与 Responses API。

API 参考 → · Cookbook →

BYOK（自带模型供应商凭证）即将推出，Console 尚未开放配置入口。目前请使用 Praxis 云 API Key 调用模型目录中的平台模型，由平台管理线路与计费；首次调用见快速开始。

API 参考 → · Cookbook →

OpenAI SDK 使用 https://api.deepraxis.com/openai/v1。请求按同协议转发；兼容不表示所有官方端点、字段和模型都可用。

选对地址

各兼容目录只列声明提供该协议的模型。出现在 OpenAI 目录里不等于同时支持 Chat Completions 和 Responses；未声明的操作返回 404 model_protocol_not_offered。

字段差异去哪里核对

未知顶层字段可能原样转发给同协议上游；请求被接受不证明字段已生效。已声明字段仍会校验。依赖一个选项前，请查看对应端点的字段支持说明。

1. 准备

需要 Python 3.10+、uv 和一个 Praxis Key。在控制台 → API Keys创建 Key，将它安全注入当前终端的 PRAXIS_API_KEY 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

test -n "${PRAXIS_API_KEY:-}"

期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。

2. 验证 Responses

示例使用 deepseek-flash。截至 2026-10-12，glm-5.3-flash 也提供 Responses；gpt-5.6-sol 提供 Chat Completions，但不提供 Responses。使用前在模型目录确认所需操作。

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
uv run -q --no-project --with openai --with anthropic python - <<'PY'
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepraxis.com/openai/v1",
    api_key=os.environ["PRAXIS_API_KEY"],
    timeout=90.0,
    max_retries=0,
)
models = client.models.list()
assert "deepseek-flash" in {m.id for m in models.data}
raw = client.responses.with_raw_response.create(
    model="deepseek-flash",
    input="Reply OK.",
    max_output_tokens=1024,
)
reply = raw.parse()
text = reply.output_text
print("HTTP", raw.status_code)
print("X-Request-Id:", raw.headers.get("x-request-id"))
print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id"))
print(text)
assert raw.status_code == 200 and text and text.strip()
assert raw.headers.get("x-request-id")
PY

期望：退出码 0，输出 HTTP 200、非空正文（通常为 OK.）和 X-Request-Id。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。

期望：output_text 是最终正文，不把思考输出当作正文。若返回 model_protocol_not_offered，换支持 Responses 的模型；若提示 does not exist，从目录复制准确 ID。已有应用回滚时同时恢复原地址、Key 与模型，再运行原冒烟请求。

API 参考 → · Cookbook：从 OpenAI 迁移 →

Anthropic SDK 使用 https://api.deepraxis.com/anthropic。SDK 会追加 /v1/messages，基础地址不要再加 /v1。请求按同协议转发，可用能力取决于模型的声明。

兼容覆盖什么

/anthropic/v1/models 只列 Anthropic 兼容模型。不要假设其他协议目录里的 ID 在这里也可用。未声明的操作返回 404（anthropic.messages is not offered for …）；换地址不会把不支持的模型能力转换出来。

字段差异去哪里核对