Get started

Choose the service you need

Every service has its own quickstart, guides and API.

Agents

Define responsibilities, provide materials and run tasks. The agent service manages underlying capability calls.

Models

Call models through one unified interface to generate text and process multimodal input.

Sandbox

Execute code, operate files and use a browser in an isolated environment.

Search

Query for the information you need and get results with sources.

Manage your cloud services

API

Agents / Models / Sandbox / Search — request parameters, response structures, error codes and code examples. To verify a call, expand the debug panel on the page, configure and send the request.

Browse all APIs →

前提

一个 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 个核心术语

Use agents to answer product questions, retrieve business data, or carry out tool tasks. You configure the model, instructions, and tools. Praxis manages session execution and event history; your application decides who can use the agent and which business operations they may perform.

Who this is for

Add a ready-made conversation interface to an existing product and pass in the signed-in user and current page. For custom interfaces, background tasks, or non-web clients, create sessions and read events through the API. Agents retrieve business data through authorized tools; your business server still enforces order ownership.

If you need a single model call or want to write the model and tool loop yourself, start with Models. Agents suit applications that need reusable configurations, ongoing conversations, and a record of task execution.

How the objects relate

Service agents serve your customers with a separate environment per session. Personal agents bind to a persistent computer. The integration guides focus on service agents. See Agents and sessions for details. Public agent IDs have the form agent_…; use the value returned by creation or retrieval.

Choose a delivery format

React is one way to use Kit. Public documentation Q&A can use anonymous visitors. For account data, your backend must verify the signed-in user before issuing a token. See Choose an integration for the full comparison.

Continue by task

• Change instructions, models, or versions: Configure an agent.
• Supply page information and business capabilities: Pass context and Configure tool authorization.
• Investigate customer issues: Inspect sessions and usage and Manage end users.
• Prepare to launch: Test your integration and Go-live checklist.

Next: API reference · Documentation Q&A recipe · Limits and errors

Create a service-agent conversation through the API and verify its reply from the event history. This example runs on a server. It needs no web component or embed policy.

Prepare Bun or Node.js with native fetch, a Develop organization API Key, access to deepseek-flash, and available balance. Set PRAXIS_API_KEY in the server process; see API keys. If your Key belongs to another environment, align the API address, organization, and model before running. Do not mix environments.

1. Create an agent

Create first-agent.mjs with the code below. Append the next three JavaScript blocks to the same file, in order; do not run them separately. The assistant answers a simple arithmetic question so you can recognize a completed first call. Add business tools after connecting successfully.

POST /agent/v1/agents creates a configuration from its name, kind, model, and instructions. tools: [] declares no additional tools. The request helper checks each response and applies a timeout. Failures print only the status and request identifier, never the 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 });

Expected result: Creation returns HTTP 200 with a public id and a version. The script prints both and reuses them in later requests. Do not construct IDs yourself.

2. Open a session

Append this code. POST /agent/v1/sessions pins the version you just created. Omitting environment_id selects a light machine; you do not need to create a sandbox first. This example explicitly sets a budget of 100 US cents. That ceiling is not an estimate of the cost of this question.

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 });

Expected result: HTTP 201 with the session id. No user question has been sent yet, so an idle status cannot prove that a reply exists. The budget controls whether execution may continue; it does not guarantee a particular answer.

3. Send the first message

Append this code to call POST /agent/v1/sessions/{session_id}/events. The events array contains one user.message with exactly one nonempty text block.

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"));

Expected result: HTTP 200 with the accepted user event in data. This acknowledges the input; it is not the agent's answer. Do not resend the message just because the answer has not appeared yet.

4. Read and verify the reply

Append this code, then run node first-agent.mjs or bun first-agent.mjs. It reads every page from GET /agent/v1/sessions/{session_id}/events, finds an agent.message, and then finds a subsequent session.status_idle. It does not mistake the initial idle state for completion.

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}`);

Completion: The process exits successfully and prints a nonempty reply with completed: true. The answer should express 4. The 120-second deadline belongs to this example, not to the service. A nonempty-text assertion alone does not validate business correctness; prepare expected answers for your actual use case before launching.

Troubleshoot failures

Running the complete script again creates another agent and session. During troubleshooting, query the IDs already printed first. Once you no longer need the test records, manage them through the API reference. A running session cannot be treated as a record ready for deletion.

Next steps

Configure an agent, read Agents and sessions, or add PraxisKit to a web page.

Give this to your agent:

Follow /en/docs/developers/agent/quickstart on the server.
Ask me for a Develop organization API Key and confirm deepseek-flash access.
Complete when a nonempty agent.message is followed by session.status_idle.
Keep the Key out of browsers and logs. Record the agent ID, version, and session ID.

An agent is a reusable configuration. A session is a separate conversation running with that configuration. Keeping these objects distinct helps you determine who a configuration change affects, where to send a message, and how to recognize completion.

Configuration and execution objects

Service agents use a separate execution environment for each session. Personal agents bind to a persistent computer for tasks that retain a working directory. Choose the kind at creation. The API quickstart uses a service agent and needs no personal computer.

Versions and the session lifecycle

Saving agent configuration creates a new version. When creating a session, agent can be an ID string to select the latest version at that moment. Alternatively, pass { type: "agent", id, version } to choose explicitly. The session pins that configuration; later agent edits do not upgrade existing sessions.

A session can be idle, running, rescheduling, or terminated. An idle session has no task currently running and can accept another message. A terminated session cannot continue. Archiving is separate: you can still read the record, but cannot send more messages. Decide whether you need to retain history or stop accepting input before cleaning up records.

A successful user.message response only acknowledges input. Read agent.message for the reply and a subsequent session.status_idle to confirm that the turn became idle. If a tool needs approval, handle the pending confirmation event. Waiting for a decision does not mean the API has stopped responding.

Environment and identity boundaries

An API session uses a light machine when environment_id is omitted and no computer is selected. Choosing an environment selects its sandbox configuration. That configuration is fixed when the session is created. File and tool capabilities depend on configuration; the word “environment” does not imply support for arbitrary runtimes.

Keep organization API Keys on your server. Customer-facing pages use embed tokens. Your backend derives external_user_id from verified sign-in state and issues a token for the selected agent. The token scopes access to an agent, version, and end user. A user ID supplied by the browser is not verified identity.

Public documentation Q&A can use a publishable key to obtain anonymous visitor tokens. The same browser storage preserves the visitor identity. This is not a signed-in account and grants no access to private orders. When users change, destroy the old component and obtain fresh credentials; clearing the message list is insufficient.

Tool confirmation records whether the user agrees to an operation. Your business service must still validate the caller's credential and the user's access to each resource. Page context, model-generated arguments, and an approval button cannot replace that check. Instructions and context are also unsuitable for secrets.

Choose your next step

Use Run your first agent to verify the API. Read Configure an agent to change configuration or select an embed version. The API reference defines creation and update fields.

For customer products, choose a delivery format, then connect identity through Embed tokens and users. Investigate execution through Sessions and usage, then apply Limits and errors.

Choose where conversations appear, then decide who builds the interface. PraxisKit, iframe, and Hosted provide chat interfaces. Use the API when your application supplies its own interface.

Compare integrations

Choose for your task

Choose Kit to configure the component in code, control when it opens, or connect it to page interactions. Kit is a Web Component that you can also mount in a React application. Your host code supplies its interface options.

Choose iframe to insert a ready-made chat interface and maintain its appearance in the Dashboard. “One line” refers to the loader script. You still implement the backend token endpoint for signed-in users. A bare iframe address does not authenticate a user.

Choose Hosted when a button should open a separate chat page. Your backend creates a short-lived link for the current user, then redirects their browser immediately. You do not install a component on your page. Obtain a fresh link for each entry; never share a user's link as a public entry point.

Choose the API for an existing chat interface or a client outside the browser. The product quickstart runs a session from your backend. Before exposing it to end users, follow the token guide to isolate each user's access.

Prepare identity and configuration

Signed-in integrations require a service agent, a saved embed policy, and a backend that authenticates host users. Keep the API key on that backend. The browser receives only the current end user's embed token. Changing the interface should not change the stable identifier you assign to that user.

For public question-answering without login, Kit supports anonymous visitors through a publishable key. Kit obtains the anonymous token. Anonymous identity does not replace account authentication or authorize access to orders. See Embed tokens and users.

Embed policies and persistent appearance can currently only be configured in the Dashboard. Kit instance appearance is configured in host code. Complete a real conversation with one integration before adding context, tools, or themes.

Next steps

• Embed in a web page: issue tokens, mount the component, and verify two users.
• Embed tokens and users: choose identity and handle refresh and revocation.
• Agent API reference: look up session and event operations.
• Cookbook: explore complete application scenarios.

Add PraxisKit to your page so signed-in users can talk to a service agent. This local order-assistant example covers backend issuance, mounting, and user isolation. For other interfaces, see Choose an integration.

You need Bun, an available service agent and runtime environment, and an API key in the same organization. The example connects to Develop. Store PRAXIS_API_KEY only in the backend environment. The browser authenticates with your host; your host verifies identity, requests a token from Praxis, and passes that token to Kit.

1. Prepare your agent

In the Develop Dashboard, open 服务智能体 (Service agents) and select an existing agent. Save its instructions under 接入与配置 → 配置 → 指令. Under 配置 → 安全, select a runtime environment, enable 允许 localhost, and click 保存安全设置. The example runs at http://localhost:4242. Use a dedicated test agent with an empty origin allowlist and localhost enabled. Local requests are rejected when the token inherits a nonempty HTTPS origin list. Add your website's origin when moving to HTTPS hosting.

Embed policies can currently only be configured in the Dashboard. Copy the public agent ID (agent_…). After the saved confirmation appears, continue with actual issuance; saving settings alone does not prove that chat works.

2. Create a token endpoint

Create a directory and save this as server.ts. This loopback-only demo uses HTTP Basic authentication for two test accounts. Set your own test password in DEMO_PASSWORD; it is unrelated to your Praxis API key. The server derives the user ID from the authenticated account and ignores any client-supplied 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-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);

Set the three variables in the server process. Replace PRAXIS_AGENT_ID with the actual ID. Save index.html in the next step before starting.

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

Expected: the terminal prints the local URL. The host rejects unauthenticated requests. Only authenticated, same-origin requests reach Praxis. Praxis returns HTTP 201 on issuance; the host returns only token and expires_at, with caching disabled.

For an existing application, replace authenticate with its session validation. Mount the route behind login and CSRF protection, and recheck identity on every issuance. Do not use these test accounts as your production login system. See Embed tokens and users for expiration and refresh.

3. Mount the component

Choose one frontend implementation. The API address, CDN, and agent must use the same environment. These examples pin Kit 0.2.8 on Develop.

<!doctype html>
<html lang="en">
<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>

Expected: a chat area appears with a height of 600 pixels. api.url sets the API address, getToken returns a token string, and agent.name sets the display name. Wait for registration before calling setOptions. The praxis.ready event only confirms mounting. A real reply is required to verify the integration.

4. Verify the integration

1. Open http://localhost:4242. Sign in as customer_123 using your test password. Ask what order questions the assistant can help with and confirm a reply arrives.
2. In the network panel, check that the host token request succeeds without returning the API key. Session requests should use an embed token. Do not copy credentials into logs or screenshots.
3. In a separate browser profile or private window, sign in as customer_456. Expect no access to the first account's conversations. Two tabs sharing one login do not test isolation.
4. Request the local token endpoint without credentials. Expect HTTP 401 from the host. In your application, also verify that signing out prevents further issuance.

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

Troubleshoot failures

These are defined API failure cases. Check the actual response in your network panel:

• Issuance HTTP 400: confirm that the embed policy is saved and the runtime environment is available.
• Issuance HTTP 404: check the agent ID and confirm the API key and service agent belong to the same organization.
• Chat returns EMBED_ORIGIN_NOT_ALLOWED (HTTP 403): check the page origin. Enable localhost for local testing or save the HTTPS origin for your hosted site.

Next steps

• Pass context
• Customize appearance
• Agent API reference
• SaaS integration example

Add one loader script to display a Praxis-hosted iframe chat interface. Save its appearance in the Dashboard while users stay on your page. “One line” describes frontend installation; your backend still issues tokens for signed-in users.

Prepare an HTTPS host

You need an HTTPS website whose pages and backend you can change, Bun, an API key in the agent's organization, and a service agent with a short number. This example connects to Develop. Your demo HTTPS entry point must forward to 127.0.0.1:4242 and preserve the original Host header. Your host supplies its domain and TLS certificate.

In the Develop Dashboard, open 服务智能体 → your agent → 接入与配置 → 配置 → 安全. Select a runtime environment, add the actual HTTPS origin under 来源白名单, and click 保存安全设置. For example, use https://support.example.com, without a path. Embed policies can currently only be configured in the Dashboard.

Enabling 允许 localhost alone does not authorize iframe embedding. This guide requires a saved HTTPS origin. For HTTP-only local testing, start with the Kit quickstart.

Record two identifiers. Token issuance uses the public ID, agent_…. The script's data-agent uses the short number copied from the Dashboard header: 5–8 letters or digits. Do not put the full ID in the short-number attribute.

Provide a token endpoint

Save this as server.ts behind your HTTPS entry point. It uses two password-protected test accounts. For production, replace authenticate with your host's session validation and retain CSRF protection. Set HOST_ORIGIN to the actual HTTPS origin, without a trailing slash. Configure all environment variables only on the backend.

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);

Start the server after saving index.html in the next section. DEMO_PASSWORD is your chosen test-account password, not an API key. Sign in through the browser as customer_123 or 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

The loader sends a POST request to data-token-endpoint with browser credentials. That endpoint must derive the user ID from validated authentication on every issuance. After Praxis returns HTTP 201, the host returns token and expires_at to the loader. Keep the API key out of HTML and tokens out of page URLs.

Install the loader

Save this as index.html, replacing ABC123 with the actual short number. For an existing page, insert only the script tag where you want chat to appear.

<!doctype html>
<html lang="en">
<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>

The loader creates the iframe and transfers its token. Opening or pasting an iframe address alone does not supply the host user's identity.

When layout and launcher attributes are absent, the loader uses saved Dashboard appearance. Without a saved layout, it uses popup. Explicit attributes override the corresponding settings. With inline, the script's location determines insertion; reserve enough height in its containing element.

Save appearance

Open 接入与配置 → 接入方式与外观 → iframe. Adjust the name, greeting, and layout, then click 保存. Expect confirmation that changes apply after refreshing the embedded page. Refresh your host page to verify. Persistent appearance can currently only be configured in the Dashboard.

With data-launcher="none", a floating layout has no default opening button. Supply an existing button's CSS selector, or control opening in host code. In this example, the button exists before the loader executes:

<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>

This replaces the previous script. Keep only one loader script for the same agent on a page.

Verify and troubleshoot

Open your HTTPS page and sign in. Confirm that chat or its launcher appears, send a question, and receive a reply. Use a separate browser to sign in as the second test account. Confirm it cannot see the first account's conversations.

In the network panel, check that loader.js loads, the iframe comes from chat-develop.praxisusercontent.com, and the host token endpoint succeeds. The API key belongs only in server-to-server requests; it must not appear in browser network records.

• Browser blocks the frame: check that the saved origin matches the page. Your host CSP must allow https://chat-develop.praxisusercontent.com in frame-src and the script CDN in script-src. Do not disable the entire CSP to troubleshoot.
• Console reports Invalid Praxis loader configuration: check the short number format, script domain, and token endpoint attribute.
• Host endpoint returns HTTP 401 or 403: restore host authentication or correct the same-origin check. Retrying does not sign the user in.

Test origin rejection by loading the script from another HTTPS site outside the allowlist; expect the browser to block embedding. After signing out of your host, request its token endpoint again and expect rejection. A hidden button does not prove authorization.

Reload the host page after sign-out or account changes so the backend issues for the new identity and removes the old interface. Opening or closing the loader only changes visibility; it does not sign the user out of your host.

Next steps

• Customize appearance
• Protect your integration
• Agent API reference
• Cookbook

Add a button that takes signed-in users to a separate Praxis Hosted chat page. Your backend authenticates the user, issues a link, and redirects immediately. No chat component is installed on your host page.

Prepare your agent

You need Bun, an API key in the agent's organization, and a service agent with instructions, a runtime environment, and an embed policy. The agent must have a short number. Open it under 服务智能体 (Service agents) in the Develop Dashboard, check the short number in its header, and copy its public agent_… ID.

If the embed policy is not saved, open 接入与配置 → 配置 → 安全, select 运行环境, and click 保存安全设置. Embed policies can currently only be configured in the Dashboard. This example uses the Develop API and a local host at http://localhost:4242; chat opens on the hosted domain.

Hosted is a separate page and cannot be embedded in an iframe. To keep users inside the current page, choose iframe or the Kit component.

Issue a link and redirect

Save this complete server as server.ts. It binds only to loopback, authenticates two test accounts through HTTP Basic, and checks the form request's origin. PRAXIS_API_KEY stays on the backend. external_user_id comes from the authenticated account, never a form field.

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);

Setting hosted: true adds hosted_url to the issuance response. Successful issuance returns HTTP 201. The host responds with HTTP 302 and puts that URL in Location, taking the browser to chat. It does not return the API key or the issuance response's token to the form page.

Configure the actual agent ID, API key, and your chosen local test password in the server environment. Save the page in the next section, then start from the same directory:

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

Expected: the terminal shows the local address. Unauthenticated requests and requests from a different origin cannot issue links. In an existing application, replace test-account authentication with session validation and put the route behind login and CSRF protection. Do not use this test-account mechanism for production login.

Add an opening button

Save this as index.html in the same directory. A normal form submission follows the backend redirect. A background fetch request alone does not navigate the browser.

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

Open http://localhost:4242, sign in as customer_123 using your test password, and click the button. Expect navigation to a chat page on chat-develop.praxisusercontent.com. Each click requests a fresh link from your host; do not cache the previous result. After navigation, check that the chat input becomes available.

Understand link lifetime

The #c=… fragment in hosted_url contains a single-use exchange credential, not an embed token. It is valid for 60 seconds after issuance and can be redeemed successfully only once. Do not log, bookmark, or share credential-bearing links. Authenticate each user on your host before entry.

The hosted page reads the credential, removes the fragment, and automatically submits code to POST /agent/v1/embed/exchange. It receives token and expires_at. Your backend must not redeem the credential first, which would consume the browser's link.

The 60-second link lifetime is separate from the embed token's lifetime. After exchange, the page uses that token until expiration. Hosted does not refresh tokens automatically. Expiration or a revocation error replaces chat with a notice to return to the original website. Reloading the hosted page cannot reuse the removed credential; return to the host and click again.

Verify the integration

Use this server-side request to check issuance shape. It prints only the grant ID, expiration, and whether a link exists, without printing credentials. This independent API check does not navigate a browser. Its fixed user ID is for controlled testing; your application must use authenticated identity.

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")}'

Then exercise the complete button flow. The network panel should show a host POST returning 302, followed by successful exchange on the hosted page. Send an order question and confirm a real reply. A loading interface alone does not establish success.

Enter as customer_456 in a separate browser and confirm it cannot read the first account's conversations. Unauthenticated host requests should return HTTP 401. To test link expiration, create a separate test link and open it after 60 seconds. Expect instructions to return to the host, rather than successful access through repeated retries.

Handle failures and appearance

Exchange returns NOT_FOUND (HTTP 404) for expired, used, and unknown credentials. Restart from the host in all three cases. Missing short numbers or embed policies cause HTTP 400 during issuance; complete those prerequisites in the Dashboard before retrying. For HTTP 429, wait according to Retry-After, then have the host issue a new link.

Save appearance under 接入与配置 → 接入方式与外观 → iframe. Hosted shares settings such as name, theme, and greeting. Persistent appearance can currently only be configured in the Dashboard. Hosted always displays a full-page conversation without a floating launcher. The Dashboard's Hosted → 打开预览 button is a preview and does not replace host issuance for real signed-in users.

Next steps

• Embed tokens and users
• Customize appearance
• Agent API reference
• Cookbook

Update a service agent's instructions, model and tools, then choose the version offered to end users. Saving configuration and selecting an embed version are separate actions. A pinned embed does not automatically adopt new configuration.

Prepare your agent

You need an existing service agent and an organization account authorized to manage it. Open Service agents → Select agent → Integration and configuration → Configuration in the Dashboard. UI labels below describe the current Chinese Dashboard.

For API access, obtain the public agent_… ID from a create or retrieve response. Set PRAXIS_API_BASE to your environment's API origin and PRAXIS_API_KEY to its organization API Key on your server. Keep the Key out of browser code. The example requires Node.js with native fetch and PRAXIS_AGENT set to the real public ID.

Update and save configuration

Save embed settings separately

Embed security policies, vault selection and embed version pinning can currently only be configured in the Dashboard.

In Configuration → Security (安全), select an available environment, add your website origin, and set token lifetime and budgets. Click Save security settings (保存安全设置). Lifetime inputs use minutes and budget inputs use US dollars. Do not paste API seconds or cents into these fields. See Secure your embed for origin rules.

For vaults, select them in MCP and credentials and click Save vaults (保存凭据库). Expected: Both saves display “已保存，不产生新版本” (saved without creating a version). These settings are separate from the configuration draft in the bottom save bar.

Select the embed version

Open Integration and configuration → Versions (版本). Click a version to compare it with its predecessor. Choose Set as embed version (设为嵌入版本) or Roll back to this version (回滚到此版本) and confirm. Check the Embedded (嵌入中) badge. Choose Unpin (取消固定) to follow the latest version again. Save a security policy first if none exists.

An explicit version in token issuance takes precedence over the pinned version. When omitted, issuance uses the pinned version, or the latest when unpinned. Existing tokens retain their version, including after rollback. Issue a new token and start a new session to verify a change.

Verify and continue

In Playground (试用调试), select the saved version and ask a question that distinguishes the new instructions from the old ones. Check the actual reply. Then obtain a new token in your host application, start a session, and confirm its version under Operations → Sessions. A loaded interface alone does not prove the new configuration is in use.

Service agents do not currently support per-message model switching, tool modes, voice input or per-end-user memory. Configuration's appearance section is a placeholder; use Customize appearance.

Next: Test your embed · Agent API · Cookbook

Embed tokens let end users access a specific agent and their own sessions. For signed-in users, your backend issues the token and the browser consumes it. This guide covers identity, expiration, refresh, and single-token revocation.

You need a service agent in your organization, a saved embed policy, and a backend API key. Save the policy under 接入与配置 → 配置 → 安全 in the Dashboard; it can currently only be configured there. Examples use Develop. See Embed in a web page for a complete integration or Hosted for single-use redirects.

Identity and access

Your backend authenticates users through your login system, then supplies a stable external_user_id. The same organization, agent, and identifier refer to the same end user. This is neither an organization member ID nor a display name. Identifiers contain 1–128 characters: letters, digits, underscores, periods, colons, @, and hyphens.

Refreshing a token does not change identity. When accounts change, remove the old component and create one for the new identity. UI confirmation buttons do not replace server-side account authorization in your tools.

Issue a token

Production issuance calls POST /agent/v1/embed_tokens from your host backend. These standalone server checks use test user customer_123. Your actual host must derive the ID from a verified login session, never a browser assertion. The Dashboard's 试用调试 → 模拟 → 重新签发 is for identity debugging only.

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")}'

Expected: HTTP 201 with id, token, and expires_at. Use id to revoke this issuance, token as the browser credential, and expires_at as its ISO 8601 UTC expiration. Examples print only redacted check results. Every call creates a new grant; repeated issuance is not idempotent.

Omitted ttl_seconds uses the policy default. The range is 60 seconds through the smaller of the policy maximum and 3600 seconds. budget_cents cannot exceed the policy session-budget maximum. allowed_origins must be a subset of existing policy entries. Version selection uses explicit version, then the policy's pinned version, then latest. The selected version is fixed at issuance. See the API reference for all fields.

Refresh and end access

Kit calls getToken(current) with null initially and the current token on refresh. Use this callback for api.getToken in the quickstart. Your endpoint verifies that the user is still signed in before returning a fresh token.

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;
}

The callback does not need to send the current token to prove host identity. Kit schedules calls and keeps tokens in memory. Do not hard-code a fixed token. Expected: refreshing preserves access to the same user's sessions.

On sign-out, end the host session and remove the old Kit element. Removal closes its connections but does not revoke issued tokens on the server. Revoke separately when the old credential must stop working immediately. Hosted has no equivalent refresh path; users return to the host after expiration.

Anonymous visitors

For public questions without login, open 接入与配置 → 密钥 → 可公开 key → 新建可公开 key. Configure anonymous limits and budget, and copy the complete value shown only once. Manage allowed origins under 配置 → 安全. These settings can currently only be configured in the Dashboard. A publishable key cannot replace a backend API key.

Save this standalone page as index.html. Replace PRAXIS_PUBLISHABLE_KEY with your actual publishable key and serve it from an allowed origin. It does not need a signed-in host token endpoint. Do not also configure getToken.

<!doctype html>
<html lang="en">
<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 sends publishable_key to POST /agent/v1/embed_tokens/anonymous, adding an existing visitor_secret on later requests. No API key is required. Success returns HTTP 200 with token and expires_at; only new visitors also receive visitor_secret. Browsers cannot choose external_user_id, budget, instructions, or Hosted options.

Kit saves the visitor credential in local storage, falling back to page memory when storage is unavailable. Do not publish or share it. Expected: the same browser storage preserves visitor identity across refreshes; separate browser storage produces separate identities. Anonymous identity does not authorize access to account data such as orders.

Inspect and revoke

Revoke only the token whose access should end. These paths perform the same task.

Expected: revocation returns a record with revoked_at; repeated revocation returns the original record. Streams using that token receive session.error with EMBED_TOKEN_REVOKED, then close. Other tokens are unaffected. For user-wide revocation, blocking, and unblocking, see Manage end users.

Errors and next steps

Revalidate host login after expiration. Stop the original access after revocation. Correct configuration for disallowed origins; ask an administrator to handle blocked users. Do not repeatedly issue tokens to bypass denial. See Embed limits and errors for codes, HTTP statuses, and recovery conditions.

• Pass context
• Manage end users
• Open hosted chat
• Agent API reference

Give the agent the current lesson, selected order, or user preferences so it can answer in context. Use readables for page state and host context for information verified by your backend.

Prepare the integration

Start with a working Kit page, a service agent, and an embed policy. Serve the HTML below from your website. The same-origin POST /api/praxis-token route is your backend route, implemented as described in Embed tokens and users. It checks the login session and returns { token }; it is not a public Praxis endpoint. This example uses the Develop Kit and API. Your page origin must be allowed.

Send current page state

Save this HTML as a page on your website. Changing the selection updates the registered value; Kit takes a snapshot when the user sends a message.

<!doctype html>
<html lang="en">
<meta charset="utf-8" />
<title>Lesson assistant</title>
<label>Current lesson
  <select id="lesson">
    <option value="Lesson 3: Delivery rules">Lesson 3: Delivery rules</option>
    <option value="Lesson 4: Returns">Lesson 4: Returns</option>
  </select>
</label>
<button id="clear">Stop sharing the lesson</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: "Lesson assistant" },
  });
</script>
</html>

Expected result: ask which lesson is open. The agent receives lesson 3. Select lesson 4 and send another message: that message carries the new value. After clicking Stop sharing the lesson, later messages omit the item.

setReadable(name, value) accepts a string or JSON-serializable value. Names must match [A-Za-z0-9_.:-]{1,64}. Setting the same name replaces its value; removeReadable(name) removes it. Invalid names and non-serializable values throw without replacing the previous registration.

Each message can carry at most 32 items and 4096 UTF-8 bytes for the entire context JSON. Kit drops the earliest registered items from that snapshot until it fits. A praxis.log event has level warn, with dropped names in data.names. Registrations remain available; smaller values can be sent again.

Page context is attached to the current user message and marked untrusted. Each message gets a fresh snapshot, but removing a registration does not erase information in earlier messages. Page state cannot establish identity, account balances, or order ownership.

Send backend-verified information

Include system_message when your backend issues a token. Run this request on the server. Replace the public agent ID and derive the user ID from your authenticated login session. Never put PRAXIS_API_KEY or this command in a browser page.

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": "The customer prefers English replies."}]
  }'

Expected result: HTTP 201 with token, id, and expires_at. Return only the required short-lived credentials through your host route. Create a new session with that token to include the preference in model context. Keep tokens out of shared logs.

system_message is an array of { type: "text", text } blocks, limited to 8192 UTF-8 bytes of text. Use one block to avoid additional separators increasing the size. This information is visible to the model; it is not secret storage.

For an existing session, an API Key holder can append system.message through Send events. Replacing a token does not rewrite the context of an established session.

Choose another input

An override without policy permission returns HTTP 400 with EMBED_FIELD_NOT_ALLOWED. Change the policy or remove the field before issuing another token. Repeating the unchanged request cannot resolve it.

Verify the context

In browser Network tools, send a message and inspect praxis_context.items. It should contain name: "lesson" and the current lesson as a string value. Change the lesson, then remove it, sending a message after each action. Check the requests rather than relying only on the model's answer.

For host context, create a new session with the newly issued token. Ask about the preferred reply language and compare it with your issuance request. This checks the experience; identity and authorization still belong to your backend and tools.

Next: Client tools · Secure your integration · Agent API.

Let the agent read page state on demand or perform a page action. Declare a tool on the agent and implement a matching callback in your Kit page. Kit returns the result to the session so the agent can continue.

Prepare the integration

You need a working Kit page, a service agent's public ID (agent_…), and an API Key on your backend. This example reads a lesson selection without a video, database, or extra dependencies. Your website must provide an authenticated POST /api/praxis-token route returning { token }, as described in Embed tokens and users. This is your route, not a Praxis endpoint.

Use a client tool for on-demand reads. Use page context for small facts needed with every message.

Declare the tool

Save this as register-tool.ts, replace agent_example, and run bun register-tool.ts on a server with PRAXIS_API_KEY set. It reads the agent, then updates tools through the public API. Other tools are preserved, and the current version guards against concurrent changes.

// 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 });

Expected result: the terminal prints the agent ID and new version. Issue a token for that version and start a new session. Tokens pinned to an older version and existing sessions do not automatically adopt the new definition. If the embed policy pins a version, update it in the Dashboard or specify the new version during issuance.

Tool names must match ^[a-zA-Z0-9_-]{1,64}$ and must not duplicate custom or built-in tool names. input_schema.type must be object. Describe when the agent should call the tool. A browser function alone does not register a tool with the agent.

Handle the call in your page

Serve this HTML from your website. It uses the Develop Kit and API; the embed policy must allow the page origin.

<!doctype html>
<html lang="en">
<meta charset="utf-8" />
<title>Lesson assistant</title>
<label>Current lesson
  <select id="lesson">
    <option value="Lesson 3: Delivery rules">Lesson 3: Delivery rules</option>
    <option value="Lesson 4: Returns">Lesson 4: Returns</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: "Lesson assistant" },
  });
</script>
</html>

Assign onClientTool as a JavaScript property on the element. It is neither an HTML attribute nor a setOptions option. The callback receives { id, name, input }: call ID, tool name, and input. Validate the input in your handler and throw for unknown tool names.

Strings are returned unchanged. Other serializable values become JSON text; undefined becomes an empty string. Exceptions, rejected promises, and serialization failures become error results. Do not include credentials or another user's data.

Verify calls and recovery

Ask the agent to use the tool to identify the open lesson. Expected result: the page reports start, then end, and the agent answers using the returned lesson. Change the selection and ask again. An end event means the server accepted the result, not that the entire response finished.

The server waits at most 120 seconds, then records an error result and continues. Kit claims call IDs and checks historical results to avoid duplicate execution. This is not a transaction guarantee across browser tabs. Backend authorization and idempotency are required for tools that change business data.

Authorization and next steps

Client custom tools bypass the platform's tool confirmation cards. Implement any page-action confirmation in your own UI. Enforce data permissions on the backend, without trusting browser values or model-supplied identity.

Tool authorization · Component reference · Update agent API.

Choose whether enabled tools run immediately or ask the user to confirm. This guide uses an orders MCP server with query and return tools. Your tool server must still enforce business permissions.

Prepare the tools

Start with a working service agent. Connect an MCP server named orders under 配置 → MCP 与凭据 (Configuration → MCP and credentials). The example requires enabled list_orders and request_return tools. Replace these names with your actual server and tools; do not configure nonexistent example tools.

A confirmation card is not authentication. A public MCP service must authenticate the platform caller before applying end-user data restrictions. See Secure tool access.

Choose an execution policy

These are the two supported policies. Do not use auto: even where a type accepts it, the runtime rejects execution. Disable a tool to prevent its use entirely. Asking still lets the user approve a call.

Policies do not bypass mandatory tool interactions, security boundaries, or business checks. Client custom tools execute in your page and do not use these confirmation policies.

Configure tools and defaults

Resolution follows individual configs[].permission_policy, then default_config.permission_policy, then the tool default. Without an explicit MCP policy, only annotations.readOnlyHint === true defaults to allow. Otherwise, it defaults to ask. This server hint affects only the default; explicit settings take priority.

The built-in toolset defaults to always_allow when no default policy is specified, while mandatory tool interactions still apply. Explicitly require confirmation for refunds, deletion, and external messages instead of relying on server hints.

Verify confirmation

Issue an embed token for the new version and create a new session. If your policy pins a version, update that pin or specify the new version during issuance. Saving an agent does not upgrade existing sessions.

Request an order lookup, then a test return. Expected: the lookup runs immediately; the return shows a Kit confirmation card. Denying must prevent the server-side action. Request it again and allow it to proceed. Verify actual execution in your tool server's records rather than relying only on the model's answer.

Kit supplies the confirmation UI. An embedded user's approval applies to that call and does not save permanent tool permissions. For complete scenarios, see Test your integration.

Next steps

Protect tool access · Client tools · Update agent API.

Match chat colors, starter text, and the input area to your website. iframe and Hosted share appearance saved in the Dashboard. A Kit component uses options supplied by your page.

Prepare the integration

Start with a working service agent and embed policy. The Kit example requires your website to provide POST /api/praxis-token, check the login session, and return { token }. This is your same-origin route; see Embed tokens and users. The example uses Develop addresses, and your page origin must be allowed.

Save hosted appearance

Persistent iframe / Hosted appearance can currently only be configured in the Dashboard. Open 服务智能体 → your agent → 接入与配置 → 接入方式与外观 → iframe (Service agents → your agent → Integration and configuration → Integration methods and appearance → iframe).

1. Under 主题 (Theme), select the color scheme, accent, grayscale, radius, and density.
2. Under 开场 (Start screen), enter the greeting and prompts. Use 输入区 (Input area) for the placeholder and footer.
3. Click 保存 (Save). Expected: a message says the changes apply after the embed page refreshes. Refresh the iframe or reopen Hosted to check the same text and colors.

The 配置 → 开场与外观 entry is currently an information page. The public appearance API supports reading only; it has no public save operation.

Configure Kit appearance

Serve this HTML from your website. It sets the theme, start screen, and composer, with a button to verify updates during a conversation.

<!doctype html>
<html lang="en">
<meta charset="utf-8" />
<title>Order assistant</title>
<button id="dark">Switch to 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: "Order assistant" },
    theme: {
      colorScheme: "light", accent: "#2563eb", grayscale: "cool",
      radius: "lg", density: "normal", fontFamily: "system-ui, sans-serif",
      fontSize: 16,
    },
    header: { title: "Order support", subtitle: "Delivery and returns" },
    startScreen: {
      greeting: "What would you like to know?",
      prompts: [{ label: "Delivery rules", prompt: "Explain the delivery rules." }],
    },
    composer: { placeholder: "Ask about an order", attachments: { enabled: false } },
    history: { enabled: true },
    footer: "Confirm order details with the merchant.",
  });
  document.querySelector("#dark").addEventListener("click", () => {
    chat.setOptions({ theme: { colorScheme: "dark" } });
  });
</script>
</html>

Expected result: a blue accent, greeting, and Delivery rules button appear. The composer has no attachment button. Click Switch to dark to change the colors while keeping the current session and messages.

Subsequent setOptions calls merge nested groups and replace arrays. Updating theme.colorScheme does not require resending the token callback. To change starter prompts, supply the complete startScreen.prompts array.

Adjust colors and text

Saved appearance JSON is limited to 8192 UTF-8 bytes. Greetings allow 200 characters; at most 4 prompts each allow 40 characters for label and 200 for prompt. Input placeholders allow 80 characters. Avatar and header images require HTTPS URLs. See the component reference for component-specific boundaries.

Verify and continue

Check starter text in a new session. Click a prompt and confirm the sent text matches prompt. Switch an ongoing conversation to dark and check that messages remain. Open another page to verify saved Dashboard appearance instead of mistaking local Kit options for saved settings.

Appearance changes do not change agent instructions or tool authorization. If saving fails, follow the field error: shorten text, reduce prompt count, or correct image URLs before retrying.

Component reference · Secure your integration · Agent API.

Use your host login session to establish identity, an origin allowlist to restrict browser access, and server-side checks to protect tools. This page configures those boundaries. See Test your integration for scenarios and the go-live checklist for release verification.

Preparation and responsibilities

You need Dashboard access to manage the service agent, a host backend, and permission to change website response headers. Configure the embed policy and token issuance before reviewing these responsibilities.

Protect identity and credentials

Your backend uses PRAXIS_API_KEY to issue a short-lived embed token. Send only the required token to the browser. Revalidate the host login session for issuance and renewal. Never let a request body's external_user_id establish identity. Keep API Keys and embed tokens out of URLs, HTML, and logs.

Kit's transport holds its token in memory. Anonymous access also uses a visitor_secret, which Kit attempts to save in localStorage to retain visitor identity. It falls back to page memory when storage is unavailable. A publishableKey is public; a visitor_secret is private. Anonymous identity is not a logged-in account on your website.

On logout, stop issuance, remove the chat component, and revoke the relevant credentials from your backend. Clearing the page is not revocation. Blocking an end user prevents new issuance and revokes that user's existing tokens. Kit can obtain a token before expiry; Hosted does not automatically renew. See Embed tokens and users.

The model may repeat instructions, system_message, page context, or tool results. Include only information the current user may access. Never pass secrets or another user's data as context.

Restrict page origins

The origin allowlist can currently only be configured in the Dashboard. Open 服务智能体 → your agent → 接入与配置 → 配置 → 安全 (Service agents → your agent → Integration and configuration → Configuration → Security). Click 添加来源 (Add origin), enter an origin such as https://shop.example.com, then 保存安全设置 (Save security settings). Expected: the saved message confirms no new agent version was created.

allowed_origins permits at most 50 entries. Enter origins without paths, queries, or fragments. Regular origins require HTTPS. https://*.example.com matches one subdomain level, not the root or deeper subdomains, and does not support ports. 允许 localhost is for local HTTP development and defaults to off.

During issuance, use allowed_origins to select a nonempty subset of policy entries, matching them exactly. Do not use an empty array to mean “deny all”: token validation falls back to the policy allowlist. Changing a policy does not revoke issued tokens. Revoke credentials when access must be withdrawn immediately.

A disallowed origin returns HTTP 403 with EMBED_ORIGIN_NOT_ALLOWED. Correct the configuration before reconnecting. Origin checks constrain browsers; non-browser requests without Origin bypass this check. It does not replace token authentication.

Protect tool access

Your MCP server must authenticate the platform caller before treating X-Praxis-External-User-Id as the end-user identity. The platform also sends X-Praxis-Agent-Id and X-Praxis-Session-Id. Sessions without an end user do not carry these identity headers.

Reject requests missing required identity. Scope every query to that user, and verify ownership and business state before changing an order. Do not trust a model-supplied user ID or a public request merely because it contains identity headers. Authenticate the caller using MCP-configured headers before trusting platform-supplied identity.

Confirmation cards check intent; clicking allow does not grant data access. Client tools and page context come from the browser and cannot enforce authorization.

Protect the host page

This Develop response-header example assumes initialization scripts live in same-origin JavaScript files and Kit loads from its CDN. Narrow image and other sources to your site's needs. If initialization remains inline, add a CSP nonce or hash for that script.

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 themes use inline styles, which this policy allows. Connection sources must match api.url. frame-src permits loading the hosted iframe; frame-ancestors 'none' prevents other sites from embedding your host page.

Platform iframe ancestors come from the allowlist; an empty list prevents framing. Hosted cannot be framed. Kit's open Shadow DOM isolates styles, but scripts on the same page can read it. Avoid sharing the chat page with untrusted scripts.

For CDN integrity checks, copy the actual fixed-version URL and integrity generated by the Dashboard, retaining crossorigin="anonymous". Do not attach a fixed hash to the floating /v1/ URL or use an illustrative hash as a release value.

Verify and continue

Reload from an allowed website and send a message. Inspect the host response's CSP in browser Network tools. Console should show no CSP failures loading Kit or connecting to the API. Confirm the issuance route returns only short-lived credentials and that tool access is scoped to the logged-in user.

Test your integration · Go-live checklist · Embed limits and errors.

Find end users by their host application ID and stop or restore embedded access when needed. Each action applies to that user within the current organization and agent.

Prepare and choose an action

You need a service agent with an embed policy, organization management access, and the external_user_id used at issuance. Verify actions with an isolated test user first. Revocation and blocking interrupt that user's ongoing conversations.

To revoke just one token, use token management instead of user-wide revocation.

Find and manage a user

Verify the access boundary

After revocation, access with an old token must fail. The host can issue a new token after checking the user's login again. After blocking, issuance must return EMBED_USER_BLOCKED (HTTP 403). After unblocking, issue a new token and send a message. A revoked token must not become valid again.

Check that another user's access to this agent remains unaffected. Derive identity from the host's authenticated server session, not an arbitrary ID submitted by the browser.

Handle failures

If a user cannot be found, verify the organization, public agent ID and complete ID used at issuance. Dashboard Playground data is excluded from customer user listings. Similar ID prefixes do not establish identity.

If blocking fails, read the state again before retrying. The blocked state may already be saved while token revocation remains incomplete. Do not report the operation as complete in that case. Record the HTTP status and request ID, then use Limits and errors.

Next steps

Inspect sessions and usage · Test your embed · Agent API · Cookbook

Use sessions, users and spending to assess your embed, then inspect an individual conversation. This page is for service agents already receiving traffic from a host application.

Prepare the records

With an authorized organization account, open Service agents → Select agent → Operations in the Dashboard. Labels below describe the current Chinese Dashboard. Have the time, end-user ID and integration type ready.

Send a recognizable test message from your host website and receive a reply before checking operations data. Dashboard Playground records are excluded from customer operations statistics. They cannot prove customer traffic or spending was recorded.

Inspect the overview

Open Overview (概览) and choose 24 hours, 7 days or 30 days. Aggregate overview statistics are currently Dashboard-only; there is no corresponding public API.

Expected: Session trends and version distribution cover the selected period. A metric without samples displays “—”, not zero. The 24-hour trend uses hourly buckets; other periods use daily buckets. Run errors, origin blocks and tool counts aggregate the intersecting UTC calendar days, including whole boundary days.

Find and replay sessions

Inspect spending and budgets

Open Usage and budgets (用量与预算) to see monthly spending, the monthly cap and its action. Choose 7, 30 or 90 days for daily spending. Below are budget and rate settings, monthly source breakdown and the top 20 end users by spending. Monthly totals use the UTC calendar month; displayed amounts are US dollars.

These aggregate reports and budget settings are currently Dashboard-only. Change cap (修改上限) opens Configuration → Security. Save and return to verify. Stop new sessions rejects session creation when the cap is reached; Alert only does not block it. Cost composition (花费构成) is not available yet; its placeholder is not a breakdown.

Verify and act

Match the host message, replay and source using the same user, session and period. For an unexpected version, check the version used at token issuance. Pinning or rolling back does not alter existing tokens. For missing data, check the environment, organization and period before creating more test sessions.

For origin or budget failures, record the response's X-Request-Id, time, HTTP status and error code. Exclude API Keys and tokens. See Manage end users for user-level actions.

Next: Embed limits and errors · Agent API · Cookbook

Before going live, verify conversations and refusal paths in your actual host website. These are acceptance scenarios to execute. A visible component or praxis.ready proves mounting, not successful authentication or a model reply.

Prepare the test environment

Use an isolated service agent, available model and environment, saved embed policy, and an integrated host page. Allow that page's actual origin and set an affordable budget. Prepare host test accounts A and B with distinct external_user_id values derived from authenticated server sessions.

First select a version and send a question in Service agents → Select agent → Integration and configuration → Playground (试用调试). This checks configuration. Then test the host below. Dashboard simulation does not test host login, domains or token endpoints, and does not enter customer operations statistics.

Run acceptance scenarios

Use this standalone script to check the TTL minimum. On your server, set PRAXIS_API_BASE (API origin), PRAXIS_API_KEY (organization API Key), and PRAXIS_AGENT (real agent_… ID). Save it as test-token-limit.mjs and run node test-token-limit.mjs with Node.js supporting native fetch. Configure the policy first; otherwise missing configuration fails before TTL validation.

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') });

Expected: Exit successfully with status: 400. This checks refusal status only; separately inspect the error body for INVALID_PARAMS and the TTL field message. The script prints no credentials and does not replace successful issuance and reply tests.

Verify identity and lifecycle

1. After A starts a session, log out and destroy A's component. Log in as B with a new component. A's sessions must be absent from history, and reading A's session with B's token must fail. Clearing the interface alone does not switch identity.
2. Keep A logged in through token refresh. Confirm getToken(current) rechecks host identity and subsequent messages still belong to A. Separately, an expired-token request must return EMBED_TOKEN_EXPIRED (401).
3. Revoke A's current token under Operations → Issuance records (签发记录). Old access must fail without automatic refresh bypassing revocation. Test user-wide revocation, blocking and unblocking with Manage end users.
4. For anonymous access, use separate browser storage for two visitors. Reload one visitor's page to check continuity. Never share visitor_secret between visitors.
5. For Hosted, test exchange after 60 seconds, repeated exchange, and token expiry in an open page. The first two fail. The open page does not refresh its token automatically; obtain a new link from the host.

Diagnose and clean up

Record time, environment, component version, expected and actual results, plus failed responses' X-Request-Id, status and error code. An error event may contain only message; inspect browser network responses for details. Exclude Keys, tokens and visitor credentials.

Revoke test tokens, archive unused test sessions, and restore temporary limits and blocked states. Archiving retains records. Run one successful conversation with normal configuration afterward to confirm cleanup left no access problems.

Next: Go-live checklist · Limits and errors · Agent API

Use this checklist before first launch or after changing domains, identity integration or component versions. Complete Test your embed, save verifiable results for each item, then open access.

Confirm launch requirements

• Configuration and versions match. Dashboard Integration and configuration → Versions shows the intended embed version. A newly issued token creates a session with that version. Check that an explicit issuance version does not override your selection.
• Identity comes from host authentication. Logged-out requests cannot obtain tokens from your host. Test users A and B cannot see each other's sessions. The API Key stays on the server; browser source and responses contain no real PRAXIS_API_KEY value.
• Anonymous credentials are handled correctly. If enabled, expose only the publishable key and configure its limits. Visitors with separate browser storage remain isolated. Do not share visitor_secret.
• Target origins work. Complete a conversation on the actual HTTPS domain; an unlisted origin fails. The iframe renders in its intended page. Hosted opens independently and cannot be framed. Disable localhost access when no longer needed.
• Component delivery is reproducible. Record and verify the Kit version, script URL and applicable integrity value. Load from an empty cache and receive a real reply, not just praxis.ready.
• Refusal paths recover correctly. Test expiry, revocation, blocking and origin refusal. Destroy the old component on host logout. After Hosted expiry, obtain a new link rather than looping over an invalid one.
• Tools enforce permissions. Test valid input, invalid input and users without business permissions. Confirmation on every call does not replace server-side authorization.
• Budgets and monitoring work. Verify US-dollar budgets, lifetime, request limits and active-session limits. Confirm the monthly cap action. Find the host test session, source and spending under Operations.

Prepare rollback and support

Keep a verified host deployment and component version. For configuration issues, select an older version and click Roll back to this version (回滚到此版本). Verify after issuing a new token; existing tokens do not change. To stop a specific user's access immediately, block or revoke all tokens and confirm old-token access fails.

For support, retain the time, environment, public agent ID, session ID, HTTP status, error code and X-Request-Id. Exclude tokens and API Keys. Follow the recovery action in Limits and errors, then verify a conversation from the host.

Related: Configure your agent · Component reference · Agent API

<praxis-agent> renders an agent conversation on your website. Initialize it with element.setOptions(options). This reference covers properties, methods and events. For integration steps, see Embed in a web page.

Initialize

Initial options require api.url, agent.name, and either api.getToken or api.publishableKey. Missing values throw TypeError. Choose getToken for authenticated users or publishableKey for anonymous visitors. Supply one; when both are supplied, the publishable key takes precedence and getToken is not called.

This anonymous example targets Develop. Create a publishable key there, save an embed policy, and allow your host origin. Replace PRAXIS_PUBLISHABLE_KEY and serve this HTML from that origin. A publishable key is not a server API Key. The script URL, version and integrity value must belong to the same release.

<!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>

Expected: A chat interface appears and sending a question produces a real reply. Interface mounted only confirms mounting; also verify replies and user isolation.

Properties

api and agent

Layout and content

theme

Default accent colors are #167A43 in light mode and #30a46c in dark mode. Foreground colors are selected for contrast.

React props

React's PraxisAgent uses these props. The current React binding still requires a top-level getToken, even though options.api includes publishableKey in its type. For anonymous access, use the Web Component above directly.

Methods

The React control handle includes the methods from sendUserMessage through toggle above. Calls before onReady or after unmount throw a not-ready error rather than queueing. For React page context and tools, use usePraxisReadable and usePraxisTool, with PraxisProvider when sharing a registry scope. See the guides below.

Events

Events are bubbling, composed CustomEvent objects that cross Shadow DOM. React callbacks receive the same event object; read its event.detail.

Defaults and lifecycle

setOptions merges objects recursively and replaces arrays. Explicit undefined resets a field. Changing api.url or api.publishableKey after initialization throws TypeError. Destroy and recreate the element when changing backends or user identity. Removing an element releases connections and refresh timers, but does not revoke issued tokens.

Page context snapshots allow 32 items and 4096 UTF-8 bytes. Excess entries are omitted starting with the earliest registration, with a log event. These runtime options are separate from Dashboard-persisted iframe/Hosted appearance, which has its own fields and size limits.

Usage guides

Embed tokens and users · Pass context · Add client tools · Customize appearance

This page covers embed tokens, Kit, iframe and Hosted. The source column distinguishes fixed validation, Dashboard policy and component behavior. Policy values come from the configuration saved for your agent.

Limits

The monthly action stop_new_sessions rejects new sessions; alert_only does not block them. Dashboard monetary inputs use US dollars; API budget fields use cents. An exhausted session budget stops new work while retaining tool confirmation and interruption.

Server errors

These statuses apply to ordinary HTTP failures. Once a stream opens, errors arrive inside the stream and cannot change its HTTP status. Retryability refers to the original request, before changing configuration or credentials.

EMBED_TOKEN_EXPIRED

401 · Access · No direct retry. The token expired. Refreshable Kit access obtains another token and replays an expiry-failed request at most once. Hosted requires a new host-issued link.

EMBED_TOKEN_REVOKED

401 · Access/stream · Not retryable. Kit stops refreshing. End old access and have the host recheck eligibility. Do not automatically issue tokens to bypass revocation.

EMBED_ORIGIN_NOT_ALLOWED

403 · Origin check · Not retryable. Check scheme, host and port against the policy and any narrower issuance allowlist. After correction, issue again and verify.

EMBED_USER_BLOCKED

403 · Issuance/session creation · Not retryable. An administrator must review the user under Operations → End users. If access should resume, unblock and issue a new token.

EMBED_RATE_LIMITED

429 · Requests/session creation/anonymous issuance · Retry later. Request frequency, active sessions or daily anonymous sessions reached their limit. Wait for the rate window, running sessions or next UTC day respectively.

EMBED_BUDGET_EXHAUSTED

402 · Session work/anonymous issuance · Not retryable. Session budget or daily anonymous spending is exhausted. Review the budget; continue with a new token and session only when authorized, or wait for daily recovery. Do not loop issuance to bypass limits.

EMBED_MONTHLY_CAP_REACHED

402 · Session creation · Not retryable. The monthly cap requires stopping new sessions. An administrator decides whether to change the cap or action, or wait for the next UTC month.

EMBED_FIELD_NOT_ALLOWED

400 · Issuance/session creation · Not retryable. Remove unauthorized agent_override. Embedded session creation accepts only title, time_zone and initial_events. Initial events are plain-text user.message events with optional page context.

Other refusals

For session permissions, archiving and event-content errors, see Agent limits and errors.

Kit errors and retries

praxis.error detail can be a KitError with code, status, retryable and message, or only { message }. Status 0 means no HTTP response.

Non-Hosted token retrieval retries retryable failures up to 3 times at 1, 2 and 4 seconds. Revocation or budget refusal stops that retry loop. Transport-owned stream recovery reconnects at most 5 times; the interface may own recovery instead. Do not add an unlimited retry loop.

Diagnose failures

Retain time, environment, public agent_… ID, HTTP status, error code and X-Request-Id without credentials. Check token status under Operations → Issuance records, then replay the session. Repeat embed tests after recovery. See the Agent API for field definitions.

Use this page to investigate agent configuration and session API failures. See Embed limits and errors for tokens, origins, anonymous quotas, and components. Organization balance and quotas belong to Usage and billing.

Request and execution limits

A budget uses type: "limit", max_list_cost.currency: "USD", and a positive integer string in max_list_cost.amount, measured in US cents. null removes the ceiling. The budget controls subsequent model requests; it is not a cost forecast. String limits use JavaScript string length, so not every character occupies one unit. Tool schema size is measured in UTF-8 bytes.

Handle errors by code

Native API errors contain error.type, error.message, and request_id. Classified service failures can also include error.code and error.retryable; request parsing failures may have only a type and message. Use the actual response: equal HTTP statuses do not imply equal causes.

INVALID_PARAMS

HTTP 400. A request field, format, or unsupported option is invalid. Correct the request from the error message; unchanged retries will not help.

UNAUTHENTICATED

HTTP 401. Credentials are missing or invalid. Check the Key for this environment and organization, then authenticate again.

SESSION_FORBIDDEN

HTTP 403. The caller cannot access this session. Check its user and organization. Do not retry automatically or probe other users by changing IDs.

AGENT_NOT_FOUND

HTTP 404. The agent or version is missing or inaccessible. Use the ID from creation and verify its version.

SESSION_NOT_FOUND

HTTP 404. The session is missing or inaccessible. Check the returned ID and caller identity; repeating a creation request is not recovery.

MODEL_NOT_ALLOWED

HTTP 400. The model is not allowed by the pinned version. Select an allowed model or update the configuration and create a new session.

SESSION_CONFLICT

HTTP 409. The session state conflicts with the operation. Read the session or pending tool before submitting again; do not resubmit a completed tool result.

SESSION_ARCHIVED

HTTP 409. The session is archived and cannot accept messages. Retain its history for inspection and create a new session for another conversation.

INVALID_STATE

HTTP 409. The state does not permit this operation, such as deleting a running session. Interrupt it or wait for idle or termination, then check the state again.

INVALID_PAGE_TOKEN

HTTP 400. The cursor is invalid or mismatched to the query. Restart at the first page, then pass next_page unchanged with the same filters.

UPSTREAM_UNAVAILABLE

HTTP 502. An upstream is temporarily unavailable. Retry after backing off; check existing results first when creating resources or sending messages.

SANDBOX_UNAVAILABLE

HTTP 503. The execution environment is temporarily unavailable. Retry after backing off. Record the request identifier and contact support if failures persist.

When to retry

Resolve the cause first when error.retryable is false. For HTTP 429, read Retry-After and avoid tight retry loops. Temporary upstream or environment failures can be retried after backing off. A broken network connection does not prove the request was never executed. Check known sessions and events before repeating creation or message requests.

After an event stream starts, execution failures can arrive as events. A successful connection status does not establish task success. Inspect replies, pending tool confirmations, and session status; accepting a message is separate from completing its task.

Capture diagnostic information

Record the time, environment, agent and session IDs, HTTP status, error type and code, and X-Request-Id. If only request-id or request_id is available, record that value too. Keep Keys, embed tokens, and visitor credentials out of diagnostic records.

Inspect sessions and usage, then compare your request with the API reference. To narrow a reproduction, start from the minimal request in the quickstart.

Automation combines platform capabilities into scripts and workflows that you run on demand or start with a trigger.

Choose an entry point

Use a script for a calculation, batch job or sequence of API calls. Use a workflow when work must wait across time or resume from checkpoints. Package a shared capability as an action. Actions are called inside scripts or workflows; they have no standalone run endpoint.

Rerunning a failed script executes it from the beginning. Effects that already occurred are not rolled back. Add a trigger to a published target when it should run automatically.

Run once

Create a develop API Key in Console and set PRAXIS_API_KEY. In Bash with curl and jq installed, this sends a Bearer-authenticated request and adds one without calling a model:

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}'

Expected: status: "completed" and output: {"answer":42}. If still pending or running, save the returned id as RUN_ID and read the result. The quickstart also shows how to save and publish this script.

Next steps

• Quickstart: get a result with curl, then publish the script.
• Concepts: versions, run trees, idempotency and costs.
• Write a script: schemas, platform APIs, actions and logs.
• Triggers: schedules and webhooks.
• Limits and errors: capacity, timeouts and troubleshooting.

API reference → · Cookbook →

Use develop with Bash, curl and jq. Run the commands in order in one Bash session. No SDK installation is needed. This script adds two numbers without calling a billable capability.

1. Create an API Key

Open Develop Console → API Keys, create a key and store it in PRAXIS_API_KEY. See Account management for key management.

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"'

Expected: both commands are available. The request prints true and exits with code 0, confirming access to the automation run list.

2. Run an ad hoc script

Create a run accepts source code and input. wait is the maximum number of seconds this HTTP request waits for a terminal run: 0–60, default 0. wait: 60 returns sooner if the run finishes. Reaching this limit does not cancel the run. HTTP 200 means the run is terminal, which can include failure; HTTP 202 means it is still pending or executing. Check status in both cases.

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"

Expected: true, with the new run ID saved in RUN_ID. The script takes n: 41 and returns answer: 42.

An HTTP 202 response is still a Run object. A subset of its fields looks like this (use the actual id returned by your request):

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

Keep RUN_ID and use the next section to GET /automation/v1/runs/$RUN_ID until completed, faulted or cancelled. Do not create a duplicate run just because the wait expired.

3. Read the result

Retrieve the run until it reaches a terminal state. This helper polls for roughly three minutes. A failed run prints its actual error and returns a nonzero exit code.

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"

Expected: true and exit code 0. The assertion checks both completion and the value 42. If the run is still pending, keep its ID and retrieve it again instead of creating another run.

4. Save and publish

Save the same source as a script draft. Read its current draft.revision, then publish a version. Each tutorial execution uses a fresh name.

Choose your own namespace, such as your project name. docs-samples below is only an example; change NAMESPACE once and the following requests reuse it.

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"'

Expected: both checks print true; version 1.0.0 is published. If PRECONDITION_FAILED reports “草稿已修改”, read the draft again, review its content and publish with the current revision.

5. Run the published version

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"

Expected: true again, confirming the output is 42. Keep TARGET to add a trigger. When finished, archive the script; its name and history remain reserved.

API reference → · Cookbook →

Scripts and workflows define the work. A run records one execution, a trigger determines when it starts, and an action provides a reusable capability during execution.

Definitions, versions and tags

Scripts and workflows share namespace/name; a name belongs to only one kind. Drafts are editable. Published versions are immutable and version numbers cannot be reused. Publishing identical content under the same version returns that version. Deprecation preserves history rather than deleting it.

References follow npm version and dist-tag conventions: docs-samples/hello@1.0.0 pins a version; @^1.2.0, @~1.2 and @1.x select ranges; @latest follows a tag. Omitting @ means @latest. Each run records the version it actually resolved.

Stable releases update latest according to version selection rules; publishing an older release does not automatically move it backwards. A prerelease requires an explicit tag such as beta. Tags such as stable and beta can move. A tag cannot be a version or range, and latest cannot be deleted. Moving a tag affects subsequent resolution without modifying published content.

Publish a version to preserve content and set a tag to point to an existing version. Tag writes do not require If-Match. Draft updates require the current ETag; publishing a draft requires expected_draft_revision.

Actions have revisions rather than semantic versions. Compatible changes take effect immediately; call records identify the revision used. Use a new action name for an incompatible schema. Published workflows lock script and child-workflow dependencies to exact versions; actions are not locked.

Run lifecycle

Scripts do not enter waiting or suspended. During cancellation, a run may remain running with cancel_requested_at set. A timeout is faulted with error type timeout, not a separate status. Terminal runs cannot resume. Rerun creates a new root run whose rerun_of points to the original.

HTTP success means the request was handled, not that execution succeeded. Check status, output and error. Inspect script calls and logs, or workflow tasks and waits.

Child runs and origin

A script can start a child through praxis.automation.runs.create. The child's initiator remains the original human, API Key or trigger. parent_run_id expresses the parent relationship. Filter by channel=run for runs started by another run, or by parent_run_id for a particular parent's children. Public run details expose a parent summary and root_run_id.