压缩上下文

当上下文窗口被填满时，AgentScope 通过 ContextConfig 控制的两套自动机制保持其形态：上下文压缩（汇总较早消息）与工具结果截断（截断过大的工具输出）。两者均透明运行，智能体不会因此中断。

配置压缩

ContextConfig 在创建智能体时传入：

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

自动压缩

压缩在每次推理步骤前自动执行，流程如下：

计算 token 数

智能体累计系统提示、摘要、上下文与工具 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）来引导摘要行为：

# 使用智能体默认配置进行检查
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。超出限额时，结果被切分为保留部分（留在上下文中）与卸载部分（如挂载了卸载器，则交由其持久化，见卸载上下文）。保留部分会追加一段截断标记，让智能体知道输出已被截断：

<<<TRUNCATED>>>
<system-reminder>The remaining content has been omitted for limited context.</system-reminder>

挂载了卸载器时，标记还会指向已持久化的完整输出：

<<<TRUNCATED>>>
<system-reminder>The remaining content has been omitted for limited context. You can refer to the file in '/path/to/tool_result-<id>.txt' for the truncated content if needed.</system-reminder>

tool_result_limit 设置过低会让智能体错过关键的工具输出；过高则可能让一次结果填满整个上下文。

快速开始

核心模块

智能体即服务

其他

配置压缩

自动压缩

手动压缩

截断工具结果

​配置压缩

​自动压缩

​手动压缩

​截断工具结果

配置压缩

自动压缩

手动压缩

截断工具结果