# 传入上下文 (/docs/cloud/services/agent/embed/context)



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

<Callout title="先读这两条">
  指令与 `system.message` **不是秘密**，模型可能被用户要求复述，不要在里面放密钥、内部规则或不想让用户看到的内容。

  工具调用前的询问确认只是帮终端用户确认自己的意图，**不是安全手段**。权限要由工具一侧按终端用户鉴权。
</Callout>

| 渠道                  | 谁写         | 何时生效         | 可信度        |
| ------------------- | ---------- | ------------ | ---------- |
| 1. 智能体指令            | 你，在控制台     | 每个会话         | 最高，属于智能体本身 |
| 2. 覆盖指令             | 你的后端，签发令牌时 | 该令牌的会话       | 高，仅策略允许时可用 |
| 3. `system.message` | 你的后端       | 令牌签发时，或会话进行中 | 可信的宿主上下文   |
| 4. 页面上下文            | 页面         | 每条用户消息       | 不可信        |
| 5. 工具（MCP）          | 你的系统       | 调用时          | 取决于你的鉴权    |

## 1. 智能体指令 [#1-智能体指令]

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

## 2. 覆盖指令 [#2-覆盖指令]

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

## 3. `system.message` [#3-systemmessage]

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

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

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

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

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

## 4. 页面上下文 [#4-页面上下文]

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

## 5. 工具 [#5-工具]

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

| 请求头                         | 含义                              |
| --------------------------- | ------------------------------- |
| `X-Praxis-External-User-Id` | 令牌里的 `external_user_id`，即你的终端用户 |
| `X-Praxis-Agent-Id`         | 智能体 id                          |
| `X-Praxis-Session-Id`       | 会话 id                           |

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

## 选哪个 [#选哪个]

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