组件参考

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

选项

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

launcher

header

theme

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

startScreen

更新选项

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

方法

在元素上直接调用。

事件

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

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

React

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

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

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

属性

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

控制句柄

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

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

前端工具与页面上下文

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

iframe 加载器

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