配置上下文压缩

单个 Session 的对话历史会随着交互持续增长。配置生效后，运行时会按保存的策略判断是否需要压缩上下文，以控制后续模型调用使用的上下文长度。

压缩只调整后续模型调用看到的上下文，不删除 Session 的 Event 记录。需要查询完整交互历史时，调用 查询会话事件列表。需要查看事件字段含义时，参见 会话事件结构参考。

工作原理#

context_management 是一个最多包含一项策略的数组。当前策略类型固定为 compaction。

你可以按任务范围选择配置位置：

1. 只有当前 Session 需要不同策略时，才在创建 Session 的 agent 对象中设置 context_management，并将 agent.type 设为 agent_with_overrides。
2. 后续 Session 都需要同一策略时，将 context_management 保存到 Agent 版本。
3. 没有自定义上下文压缩策略时，不传 context_management，由运行时使用平台默认行为。

创建 Session 后，系统只将显式保存的策略冻结到 Agent 配置快照中。后续更新基础 Agent 不会改变已有 Session。查询 Agent 或 Session 时，响应可能展示平台当前默认策略或默认阈值，当前默认阈值为 192000 token。

为 Agent 配置上下文压缩#

需要让后续 Session 默认使用同一策略时，在创建 Agent 或更新 Agent 时配置 context_management：

1
2
3
4
5
6
7
8
9{
  "context_management": [
    {
      "type": "compaction",
      "compact_threshold": 100000,
      "instructions": "保留任务目标、已确认事实、关键标识、执行结果、未完成事项和下一步。"
    }
  ]
}

compact_threshold 控制自动压缩何时触发。只有需要固定触发阈值时才传入该字段；省略该字段或传 null 时，运行时使用平台默认阈值，查询响应会展示当前默认值。当前平台默认阈值为 192000 token。

instructions 用于指导系统生成压缩摘要。只有需要改变摘要关注点时才填写；没有自定义要求时，可以省略、传 null 或传空字符串。

完整请求字段、取值规则和响应结构，详情请参见 创建智能体 和 更新智能体。

更新或清除策略#

更新 Agent 时，context_management 会整体替换当前配置：

不要把高于模型上下文窗口的阈值当作关闭开关。服务端会保存该值，但模型调用可能在达到阈值前因输入超出模型窗口而失败。

为 Session 配置上下文压缩#

如果只有当前任务需要不同策略，创建 Session 时设置 agent.context_management，并将 agent.type 设为 agent_with_overrides。覆写只写入当前 Session 的 Agent 配置快照，不创建新的 Agent 版本，也不影响其他 Session。

1
2
3
4
5
6
7
8
9
10
11
12
13
14{
  "agent": {
    "type": "agent_with_overrides",
    "id": "<AGENT_ID>",
    "context_management": [
      {
        "type": "compaction",
        "compact_threshold": 80000,
        "instructions": "保留代码片段、变量名、技术决策、测试结果和下一步。"
      }
    ]
  },
  "environment_id": "<ENVIRONMENT_ID>"
}

Session 覆写支持以下三种传值方式：

• 省略或传 null：继承所选 Agent 版本的配置。
• 传 []：清除继承的自定义策略，改用平台默认压缩策略；查询响应可展示平台当前默认策略和默认阈值。
• 传入一项：整体替换所选 Agent 版本的策略。

完整请求结构，详情请参见 创建会话。

查询配置#

查询 Agent 或 Session 时，响应会显示上下文管理策略。当前平台默认阈值为 192000 token：

• 已显式保存 compact_threshold 时，响应返回保存的阈值。
• 已保存 compaction 策略但未保存 compact_threshold 时，响应保留已保存的 instructions，并显示平台当前默认阈值。
• 未保存自定义上下文压缩策略，或已通过 [] 清除自定义策略时，响应可显示一条 compaction 策略和平台当前默认阈值。
• 多智能体 Session 中，每个成员的 context_management 来自该成员创建时冻结的配置快照；响应展示默认值时，也不会改写成员快照。

查询响应中显示的默认值仅用于展示，不会写回 Agent 版本或 Session 快照。客户端如果把查询结果原样用于创建或更新请求，默认阈值 192000 会被保存为显式配置，之后不再跟随平台默认值变化。要继续使用平台默认阈值，创建或更新时省略 compact_threshold 或传 null。

压缩真正发生时，Session 事件流会返回 agent.thread_context_compacted 事件。该事件用于确认线程上下文已经完成摘要压缩，详情请参见 会话事件结构参考。

配置限制#

• context_management 最多包含一项，type 固定为 compaction。
• 显式配置的 compact_threshold 不能小于 50000；其他字段取值、长度限制和错误码以对应 API Reference 为准。
• Agent 更新只影响之后创建的 Session，不改写已有 Session 的配置快照。
• Session Upgrade 不支持修改 context_management。需要使用新策略时，更新 Agent 后创建新 Session。

相关文档#

• Agent
• 启动 Session
• 持久化记忆
• 上下文缓存