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

# Compress Context

> Keep the context length within the preset limit

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:

```python theme={null}
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,
    ),
)
```

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

<Steps>
  <Step title="Count tokens">
    The agent totals the tokens of the system prompt, summary, context, and tool schemas.
  </Step>

  <Step title="Check threshold">
    If total tokens exceed `trigger_ratio × context_size`, compression activates. Otherwise the agent proceeds with the model call as usual.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Update state">
    The summary replaces the compressed messages; the reserved messages become the new context. The agent then continues its reasoning step.
  </Step>
</Steps>

<Note>
  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.
</Note>

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

```python theme={null}
# 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.

## 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](/versions/2.0.5dev/en/building-blocks/context/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>
```

<Warning>
  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.
</Warning>