Compress Context

When the context window fills up, AgentScope keeps it in shape with two automatic mechanisms governed by ContextConfig: context compression (summarize older messages) and tool result truncation (cap oversized tool outputs). Both run transparently; the agent continues working without interruption.

Configure Compression

ContextConfig is passed to the agent at construction time:

from agentscope.agent import Agent
from agentscope.agent import 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,
        max_image_num=5,
    ),
)

Available fields:

Parameter	Type	Description
`trigger_ratio`	`float`	Compression activates when token usage exceeds this ratio of the model’s context size (capped at `0.9`)
`reserve_ratio`	`float`	Proportion of context tokens kept as recent messages after compression
`tool_result_limit`	`int`	Maximum tokens per tool result; outputs exceeding this are truncated
`max_image_num`	`int`	Maximum number of images kept in the context, `5` by default
`compression_prompt`	`str`	The prompt that guides the model to generate the summary
`summary_template`	`str`	String template for formatting the summary into the context
`summary_schema`	`dict`	JSON Schema constraining the model’s structured summary output

Compress Automatically

Compression runs automatically before each reasoning step. The flow:

Count tokens

The agent totals the tokens of the system prompt, summary, context, and tool schemas.

Check threshold

If total tokens exceed trigger_ratio × context_size, compression activates. Otherwise the agent proceeds with the model call as usual.

Split messages

Older messages are marked for compression; recent messages within reserve_ratio × context_size are kept. Tool call / result pairs are kept intact across the split.

Generate summary

The model produces a structured summary from the older messages, with five fields: task_overview, current_state, important_discoveries, next_steps, context_to_preserve.

Update state

The summary replaces the compressed messages; the reserved messages become the new context. The agent then continues its reasoning step.

The remaining 10% between trigger_ratio (max 0.9) and the full context size is reserved for the compression model call itself: the model needs room to generate the summary.

Compress Manually

Compression can also be triggered manually by calling the agent’s compress_context() method. Without arguments, it uses the agent’s stored context_config; pass a one-off ContextConfig to override, or an instructions HintBlock to guide the summarization:

# Force-check using the agent's default config
await agent.compress_context()

# Or override the config for this single call (e.g. compress more aggressively)
from agentscope.agent import ContextConfig

await agent.compress_context(
    context_config=ContextConfig(trigger_ratio=0.5, reserve_ratio=0.1),
)

# Or inject instructions to guide the summarization
from agentscope.message import HintBlock

await agent.compress_context(
    instructions=HintBlock(
        hint="Keep every file path and API signature mentioned so far.",
    ),
)

The method is a no-op when token usage is below trigger_ratio × context_size, so it is safe to call between turns or at any custom checkpoint.

Limit Images

max_image_num prevents images from accumulating in the model context over a long conversation. Once the count exceeds the limit, AgentScope removes images starting from the oldest and leaves a hint in their place:

If the agent is configured with an offloader, the image is persisted first and the hint carries the path for re-reading it;
Without an offloader, the image is dropped and the hint only records that it was removed by the image limit.

Set max_image_num=0 to keep no images in the model context at all.

Truncate Tool Results

After each tool call, the agent compares the result’s token count against tool_result_limit. If the limit is exceeded, the result is split into a reserved portion (kept in context) and an offloaded portion (handed to the offloader if one is attached, see Offload Context). A truncation marker is appended to the reserved portion so the agent knows the output was clipped:

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

When an offloader is attached, the marker also points the agent to the persisted full output:

<<<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>

Setting tool_result_limit too low may starve the agent of critical tool output. Setting it too high risks one result filling the entire context.

Get Started

Building Blocks

Agent as Service

Others

Configure Compression

Compress Automatically

Compress Manually

Limit Images

Truncate Tool Results

​Configure Compression

​Compress Automatically

​Compress Manually

​Limit Images

​Truncate Tool Results

Configure Compression

Compress Automatically

Compress Manually

Limit Images

Truncate Tool Results