# 服务型智能体 · 接入与配置 (/docs/cloud/services/agent/embed/console-integrate) 服务型智能体是放进你自己的网站或应用、替你的用户回答问题和办事的智能体。每个智能体有两个工作台：**接入与配置**用来把它做好、接上线；**运营与管理**用来看它跑得怎么样，见[运营与管理](/docs/cloud/services/agent/embed/console-operate)。本页讲前者。 打开 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 事件。这与你的后端签发令牌是同一件事，见[嵌入令牌与终端用户](/docs/cloud/services/agent/embed/tokens)。 ## 配置 [#配置] 左侧是配置分组，右侧是内容。 | 分组 | 内容 | | ------- | ---------------------------------------- | | 基本 | 名称、描述、注册号、智能体 ID，以及配置版本列表 | | 指令 | 角色、口吻、回答范围 | | 模型 | 使用的模型 | | 工具与授权 | 启用哪些工具，以及每个工具的授权方式：「自动执行」或「每次询问」 | | MCP 与凭据 | 智能体连接的 MCP 服务器，以及可用的凭据库 | | 开场与外观 | 此配置入口仍为占位；请到「接入方式与外观 → iframe」保存外观 | | 安全 | 运行环境、来源白名单、令牌与预算、限流、封禁名单入口 | | 暂不支持 | 服务型智能体暂不支持的能力：按消息切换模型、工具模式、语音输入、按终端用户的记忆 | ### 保存与版本 [#保存与版本] 「基本」「指令」「模型」「工具与授权」「MCP 与凭据」里的修改是一份草稿，页面底部的保存栏会列出改动过的分组。点保存会生成**新版本**；已固定版本的嵌入不会自动升级，见下文「版本」。离开页面前有未保存的改动会提示。 「安全」和「凭据库」是另外保存的：各有自己的保存按钮，保存后显示「已保存，不产生新版本」。 ### 工具与授权 [#工具与授权] 「授权方式」列出已启用的工具，每个选「自动执行」或「每次询问」。每次询问会在对话里弹出确认卡。**询问确认只是帮终端用户确认意图，不是安全手段**，工具应按终端用户在服务端鉴权，见[工具授权](/docs/cloud/services/agent/embed/tool-authorization)。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 | 仅开发调试用 | | 令牌有效期默认值 / 上限（分钟） | 签发时不指定则用默认值，不能超过上限 | | 每会话预算默认值 / 上限（元） | 单个会话最多花多少 | | 允许宿主覆盖指令 | 打开后，宿主后端签发令牌时可以替换该令牌的指令 | | 月度上限（元） | 留空表示不限 | | 触顶动作 | 「停止新会话」或「只告警」 | | 单个终端用户的活跃会话上限 | 同一终端用户正在运行的会话数；空闲的历史会话不计入 | | 每分钟请求上限 | 每个终端用户 | | 封禁名单 | 显示被封禁的人数，在「运营与管理 · 终端用户」里管理 | 第一次保存会创建嵌入策略；没有策略时不能签发令牌。每一项的详细含义见[嵌入令牌与终端用户](/docs/cloud/services/agent/embed/tokens)和[安全](/docs/cloud/services/agent/embed/security)。 ## 版本 [#版本] 「版本」页签左侧是版本列表：版本号、创建时间、相对上一版的改动摘要，当前被嵌入使用的那一版带「嵌入中」标记。点版本号 vN，右侧显示它与上一版的对比。 嵌入使用哪一版由嵌入策略决定： * **未固定**：列表顶部显示「未固定，跟随最新」，之后新签发的令牌用最新版本。 * **固定**：点某一版右侧的「设为嵌入版本」（最新版）或「回滚到此版本」（更早的版本），确认后新签发的令牌使用这一版。已固定时，列表顶部出现「取消固定」，确认后恢复跟随最新。 **已经签发的令牌不变**：确认框里会写明「已签发的令牌不变」，旧令牌到期前仍使用签发时的版本。没有嵌入策略时这些按钮不可用，页面会提示先到「配置 · 安全」设置。「近 7 天会话数」一列目前显示「—」。 ## 接入方式与外观 [#接入方式与外观] 进入「接入方式与外观 → iframe」，在实时预览旁调整外观，点「保存」。期望：显示「已保存，嵌入页刷新后生效」，刷新宿主页面验证。未配置来源白名单时，iframe 会被所有网站拒绝，请先到「配置 → 安全」设置。 保存的外观作用于 iframe 与 Hosted。Kit 组件的外观写在宿主代码里。Hosted 页签提供「打开预览」和后端跳转示例；接入代码见[嵌入方式](/docs/cloud/services/agent/embed/methods)。 ### 可保存的外观 [#可保存的外观] | 设置 | 字段 | | ------- | ---------------------------------------------------------------------------------------------------- | | 智能体与顶栏 | `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 `，可公开 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` 换取令牌，见[嵌入令牌](/docs/cloud/services/agent/embed/tokens)。可公开 key 与服务器上的 API Key 是两种凭据。 期望：新建可公开 key 后弹出「只显示这一次」对话框，列表里出现这把 key 的前缀、状态「启用」和各项上限。 下一步：[运营与管理](/docs/cloud/services/agent/embed/console-operate) · [嵌入到网页](/docs/cloud/services/agent/embed/quickstart)