> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 压缩上下文
> 将上下文长度维护在预设的长度内
当上下文窗口被填满时，AgentScope 通过 `ContextConfig` 控制的两套自动机制保持其形态：**上下文压缩**（汇总较早消息）与**工具结果截断**（截断过大的工具输出）。两者均透明运行，智能体不会因此中断。
## 配置压缩
`ContextConfig` 在创建智能体时传入：
```python theme={null}
from agentscope.agent import Agent, ContextConfig
agent = Agent(
name="my_agent",
system_prompt="...",
model=model,
toolkit=toolkit,
context_config=ContextConfig(
trigger_ratio=0.8,
reserve_ratio=0.1,
tool_result_limit=3000,
),
)
```
可用字段：
| 参数 | 类型 | 说明 |
| -------------------- | ------- | ---------------------------------------- |
| `trigger_ratio` | `float` | 当 token 用量超过该比例 × 模型上下文长度时触发压缩（上限 `0.9`） |
| `reserve_ratio` | `float` | 压缩后作为最近消息保留的上下文 token 比例 |
| `tool_result_limit` | `int` | 单条工具结果的最大 token 数，超出则截断 |
| `compression_prompt` | `str` | 引导模型生成摘要的提示词 |
| `summary_template` | `str` | 把摘要拼回上下文时使用的字符串模板 |
| `summary_schema` | `dict` | 约束模型结构化摘要输出的 JSON Schema |
## 自动压缩
压缩在每次推理步骤前自动执行，流程如下：
智能体累计系统提示、摘要、上下文与工具 schema 的全部 token。
若总数超过 `trigger_ratio × context_size`，触发压缩；否则跳过此步，正常发起模型调用。
较早消息标记为待压缩；落在 `reserve_ratio × context_size` 内的最近消息保留。工具调用 / 结果对在切分时保持成对，不会被拆开。
模型基于较早消息生成一份结构化摘要，包含五个字段：`task_overview`、`current_state`、`important_discoveries`、`next_steps`、`context_to_preserve`。
摘要替换被压缩的消息，保留下来的最近消息成为新的上下文。智能体随后继续完成本次推理步骤。
`trigger_ratio`（最高 `0.9`）与完整上下文之间的剩余 10% 是给压缩调用本身预留的：模型需要空间生成摘要。
## 手动压缩
也可以调用智能体的 `compress_context()` 方法手动触发压缩。不传参数时使用智能体自身的 `context_config`；可通过传入一份临时的 `ContextConfig` 进行覆盖，或传入 `instructions`（一个 `HintBlock`）来引导摘要行为：
```python theme={null}
# 使用智能体默认配置进行检查
await agent.compress_context()
# 或针对单次调用覆盖配置（例如更激进地压缩）
from agentscope.agent import ContextConfig
await agent.compress_context(
context_config=ContextConfig(trigger_ratio=0.5, reserve_ratio=0.1),
)
# 或注入指令来引导摘要行为
from agentscope.message import HintBlock
await agent.compress_context(
instructions=HintBlock(
hint="保留至今提到的所有文件路径与 API 签名。",
),
)
```
当 token 用量低于 `trigger_ratio × context_size` 时该方法为空操作，因此可以安全地在轮次之间或自定义检查点处随时调用。
## 截断工具结果
每次工具调用之后，智能体会比较结果的 token 数与 `tool_result_limit`。超出限额时，结果被切分为保留部分（留在上下文中）与卸载部分（如挂载了卸载器，则交由其持久化，见[卸载上下文](/versions/2.0.5dev/zh/building-blocks/context/offload-context)）。
保留部分会追加一段截断标记，让智能体知道输出已被截断：
```
<<>>
The remaining content has been omitted for limited context.
```
挂载了卸载器时，标记还会指向已持久化的完整输出：
```
<<>>
The remaining content has been omitted for limited context. You can refer to the file in '/path/to/tool_result-.txt' for the truncated content if needed.
```
`tool_result_limit` 设置过低会让智能体错过关键的工具输出；过高则可能让一次结果填满整个上下文。