服务型智能体 · 接入与配置
在 Console 里试用、配置、发布版本、管理密钥，把服务型智能体接到你的产品里。
服务型智能体是放进你自己的网站或应用、替你的用户回答问题和办事的智能体。每个智能体有两个工作台：接入与配置用来把它做好、接上线；运营与管理用来看它跑得怎么样，见运营与管理。本页讲前者。
打开 Console，进入「服务型智能体」，点「新建服务型智能体」，或点列表里已有的智能体。页面顶部显示名称、版本徽标（如 v3）、状态标记和短号，短号旁边的按钮可以复制。两个工作台在页签栏左侧切换：「接入与配置」「运营与管理」。接入与配置有五个页签：
| 页签 | 做什么 | 状态 |
|---|---|---|
| 试用调试 | 在 Console 里直接和智能体对话，模拟终端用户 | 可用 |
| 配置 | 指令、模型、工具、MCP、安全等 | 可用 |
| 版本 | 查看历史版本，决定嵌入使用哪一版 | 可用 |
| 接入方式与外观 | 配置 iframe、Hosted，获取 Kit 和 API 示例 | 可用 |
| 密钥 | 签发令牌用的 API key，以及可公开 key | 可用 |
页面右上角的「发布新版本」会带你到「版本」页签。
试用调试
先在「配置 · 安全」里保存嵌入策略，才能试用；没有策略时页面会提示「先在『配置 → 安全』里设置嵌入策略，才能试用」，点「去配置」直达。
- 形态：顶部的
inline、popup、sidebar、modal切换智能体在页面里的样子，与网站嵌入时的布局一一对应。 - 版本：下拉选择试用哪一版，默认是嵌入策略固定的版本，没有固定则是最新版。切换版本会重新签发令牌并开始新对话。
- 调试面板有三个页签：
- 「上下文」：当前版本的指令（只读）和宿主传入的上下文（host_context）。「页面上下文」可添加、删除名称和值，每条用户消息会带上这些内容。
- 「事件」：嵌入组件触发的事件列表（ready、error、thread.change、response.start、response.end、open、close 等），点一条展开详情。
- 「模拟」：填写 external_user_id 和 system_message，点「重新签发」，用这个身份开始新对话。用来检查「不同用户看到不同内容」。
期望：点「重新签发」后对话区重置，「上下文」页签里 host_context 显示你填的 system_message，「事件」页签出现 ready 事件。这与你的后端签发令牌是同一件事，见嵌入令牌与终端用户。
配置
左侧是配置分组，右侧是内容。
| 分组 | 内容 |
|---|---|
| 基本 | 名称、描述、注册号、智能体 ID，以及配置版本列表 |
| 指令 | 角色、口吻、回答范围 |
| 模型 | 使用的模型 |
| 工具与授权 | 启用哪些工具，以及每个工具的授权方式：「自动执行」或「每次询问」 |
| MCP 与凭据 | 智能体连接的 MCP 服务器，以及可用的凭据库 |
| 开场与外观 | 此配置入口仍为占位；请到「接入方式与外观 → iframe」保存外观 |
| 安全 | 运行环境、来源白名单、令牌与预算、限流、封禁名单入口 |
| 暂不支持 | 服务型智能体暂不支持的能力：按消息切换模型、工具模式、语音输入、按终端用户的记忆 |
保存与版本
「基本」「指令」「模型」「工具与授权」「MCP 与凭据」里的修改是一份草稿，页面底部的保存栏会列出改动过的分组。点保存会生成新版本；已固定版本的嵌入不会自动升级，见下文「版本」。离开页面前有未保存的改动会提示。
「安全」和「凭据库」是另外保存的：各有自己的保存按钮，保存后显示「已保存，不产生新版本」。
工具与授权
「授权方式」列出已启用的工具，每个选「自动执行」或「每次询问」。每次询问会在对话里弹出确认卡。询问确认只是帮终端用户确认意图，不是安全手段，工具应按终端用户在服务端鉴权，见工具授权。MCP 服务器可以设置默认授权，也可以逐个工具设置。
MCP 与凭据
在这里添加智能体要调用的 MCP 服务器。页面上的说明提醒：平台调用 MCP 时会附带 X-Praxis-External-User-Id、X-Praxis-Agent-Id、X-Praxis-Session-Id 三个请求头，工具应据此按终端用户鉴权。
下方「凭据库」勾选后保存：会话按凭据的「允许的主机」或 MCP 地址自动匹配凭据来调用 MCP 服务器。还没有创建嵌入策略时，这里会提示先到「安全」创建。
安全
这是嵌入策略，决定谁能签发令牌、令牌能做什么。
| 字段 | 含义 |
|---|---|
| 运行环境（必填） | 智能体会话运行所在的环境。下拉里没有选项时显示「暂无可用运行环境」 |
| 来源白名单 | 允许嵌入的网站来源，点「添加来源」逐个填写，需为 https，如 https://example.com，也可用 https://*.example.com；最多 50 个 |
| 允许 localhost | 仅开发调试用 |
| 令牌有效期默认值 / 上限（分钟） | 签发时不指定则用默认值，不能超过上限 |
| 每会话预算默认值 / 上限（元） | 单个会话最多花多少 |
| 允许宿主覆盖指令 | 打开后，宿主后端签发令牌时可以替换该令牌的指令 |
| 月度上限（元） | 留空表示不限 |
| 触顶动作 | 「停止新会话」或「只告警」 |
| 单个终端用户的活跃会话上限 | 同一终端用户正在运行的会话数；空闲的历史会话不计入 |
| 每分钟请求上限 | 每个终端用户 |
| 封禁名单 | 显示被封禁的人数，在「运营与管理 · 终端用户」里管理 |
第一次保存会创建嵌入策略；没有策略时不能签发令牌。每一项的详细含义见嵌入令牌与终端用户和安全。
版本
「版本」页签左侧是版本列表：版本号、创建时间、相对上一版的改动摘要，当前被嵌入使用的那一版带「嵌入中」标记。点版本号 vN，右侧显示它与上一版的对比。
嵌入使用哪一版由嵌入策略决定：
- 未固定：列表顶部显示「未固定，跟随最新」，之后新签发的令牌用最新版本。
- 固定：点某一版右侧的「设为嵌入版本」（最新版）或「回滚到此版本」（更早的版本），确认后新签发的令牌使用这一版。已固定时，列表顶部出现「取消固定」，确认后恢复跟随最新。
已经签发的令牌不变：确认框里会写明「已签发的令牌不变」，旧令牌到期前仍使用签发时的版本。没有嵌入策略时这些按钮不可用，页面会提示先到「配置 · 安全」设置。「近 7 天会话数」一列目前显示「—」。
接入方式与外观
进入「接入方式与外观 → iframe」，在实时预览旁调整外观，点「保存」。期望：显示「已保存，嵌入页刷新后生效」，刷新宿主页面验证。未配置来源白名单时，iframe 会被所有网站拒绝，请先到「配置 → 安全」设置。
保存的外观作用于 iframe 与 Hosted。Kit 组件的外观写在宿主代码里。Hosted 页签提供「打开预览」和后端跳转示例；接入代码见嵌入方式。
可保存的外观
| 设置 | 字段 |
|---|---|
| 智能体与顶栏 | agent.name、agent.avatar；header.title、header.subtitle、header.icon |
| 布局与启动按钮 | layout：inline/sidebar/popup/modal；launcher.type：none/bubble/mascot，以及 image、position、label |
| 主题 | theme.colorScheme、accent、surface、grayscale、radius、density、fontFamily、fontSize |
| 语言 | locale：zh 或 en；未设置时 iframe 与 Hosted 跟随浏览器语言 |
| 开场与输入框 | startScreen.greeting、startScreen.prompts（label/prompt 对）、composer.placeholder |
| 其他 | disclaimer、footer、history.enabled |
图片（agent.avatar、header.icon、launcher.image）必须使用 HTTPS。保存对象最多 8 KB；名称最多 40 字符，问候语 200 字符；推荐问题最多 4 个，每个标签最多 40 字符、问题最多 200 字符；输入框占位文字最多 80 字符，免责声明 200 字符，页脚 120 字符。保存外观不能包含凭据或可执行回调。
GET /agent/v1/embed/appearance 通过嵌入令牌或可公开 key 确定智能体并读取外观，不接受智能体 ID、短号或其他寻址参数；嵌入令牌放在 Authorization: Bearer <token>，可公开 key 放在 Praxis-Publishable-Key: PRAXIS_API_KEY（占位符）；组织 API Key 不能通过此端点读取。未保存外观时返回 {}。iframe 与 Hosted 页会自动加载。
密钥
签发令牌用的 API key：你的后端用 API key 为自己的登录用户签发嵌入令牌，key 只放在服务器上。页面给出一个签发示例命令和「复制」按钮，旁边「去 API Keys 创建」带你去创建 key。下方「最近用于签发本智能体令牌的 key」基于最近 50 条签发记录，显示每个 key 最近一次用于签发的时间和次数；还没有时显示「还没有用 API key 签发过」。
可公开 key：这一栏可以新建、编辑、停用、启用和删除可公开 key，并设置名称、匿名每分钟上限、单会话预算、每日会话数上限和每日花费上限（金额单位为元，留空表示不限）。新建后完整的 key 值只显示一次，请立即复制。可公开 key 可以出现在网页源码里，保护依赖「配置 · 安全」的来源白名单和这里的各项上限。匿名访客可通过 POST /agent/v1/embed_tokens/anonymous 换取令牌，见嵌入令牌。可公开 key 与服务器上的 API Key 是两种凭据。
期望：新建可公开 key 后弹出「只显示这一次」对话框，列表里出现这把 key 的前缀、状态「启用」和各项上限。