agentscope-ai/agentscope · error · ValueError

The 'context_buffer_ratio' of the injection config must be s

Error message

The 'context_buffer_ratio' of the injection config must be smaller than the 'trigger_ratio' of the context config, so that the context length is injected before the compression, got {self.injection_config.context_buffer_ratio} and {self.context_config.trigger_ratio}.

What it means

Agent __init__ validation: when inject_runtime_state is enabled in the injection config, its context_buffer_ratio (the context fill level at which runtime state like context length is injected into the prompt) must be strictly below the context config's trigger_ratio (where compression starts). This guarantees the agent sees the context-length state before compression kicks in; otherwise the injection would be useless.

Source

Thrown at src/agentscope/agent/_agent.py:244

                context compression threshold.
        """
        if (
            self.context_config.reserve_ratio
            >= self.context_config.trigger_ratio
        ):
            raise ValueError(
                "The 'reserve_ratio' of the context config must be smaller "
                "than its 'trigger_ratio', got "
                f"{self.context_config.reserve_ratio} and "
                f"{self.context_config.trigger_ratio}.",
            )

        if (
            self.injection_config.inject_runtime_state
            and self.injection_config.context_buffer_ratio
            >= self.context_config.trigger_ratio
        ):
            raise ValueError(
                "The 'context_buffer_ratio' of the injection config must be "
                "smaller than the 'trigger_ratio' of the context config, so "
                "that the context length is injected before the compression, "
                f"got {self.injection_config.context_buffer_ratio} and "
                f"{self.context_config.trigger_ratio}.",
            )

    # =======================================================================
    # Agent public methods
    # =======================================================================

    async def reply_stream(
        self,
        inputs: Msg
        | list[Msg]
        | UserConfirmResultEvent
        | UserInterruptEvent
        | ExternalExecutionResultEvent

View on GitHub (pinned to e90f1c7592)

Solutions

1. Make context_buffer_ratio strictly smaller than trigger_ratio, e.g. context_buffer_ratio=0.3, trigger_ratio=0.5
2. Alternatively disable injection: inject_runtime_state=False, which skips the check
3. Centralize both ratios in one config object so they are always tuned together

Example fix

# before
agent = ReActAgent(
    context_config=ContextConfig(trigger_ratio=0.5),
    injection_config=InjectionConfig(inject_runtime_state=True, context_buffer_ratio=0.7),
)

# after
agent = ReActAgent(
    context_config=ContextConfig(trigger_ratio=0.5),
    injection_config=InjectionConfig(inject_runtime_state=True, context_buffer_ratio=0.3),
)

def validate_agent_ratios(trigger: float, buffer_ratio: float, inject: bool) -> None:
    if inject and buffer_ratio >= trigger:
        raise ValueError(
            f"context_buffer_ratio ({buffer_ratio}) must be < trigger_ratio ({trigger}) "
            "when inject_runtime_state=True"
        )

validate_agent_ratios(cfg.trigger_ratio, inj.context_buffer_ratio, inj.inject_runtime_state)
agent = ReActAgent(context_config=cfg, injection_config=inj)

from typing import TypeGuard

def ratios_compatible(trigger: float, buffer_ratio: float) -> TypeGuard[float]:
    return buffer_ratio < trigger

try:
    agent = ReActAgent(context_config=ctx, injection_config=inj)
except ValueError as e:
    if "context_buffer_ratio" in str(e):
        inj.context_buffer_ratio = ctx.trigger_ratio * 0.6
        agent = ReActAgent(context_config=ctx, injection_config=inj)
    else:
        raise

When it happens

Trigger: Constructing an Agent with InjectionConfig(inject_runtime_state=True, context_buffer_ratio=0.6) together with ContextConfig(trigger_ratio=0.5), or any combination where context_buffer_ratio >= trigger_ratio. Only enforced when inject_runtime_state is True.

Common situations: Enabling runtime state injection while tuning compression thresholds independently; defaults drifting after a version upgrade; setting a high trigger_ratio but leaving context_buffer_ratio at a larger default.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• The 'reserve_ratio' of the context config must be smaller th
• Invalid logging level: {level}. Must be one of 'INFO', 'DEBU
• factory must be a callable, got {type(factory).__name__}
• Agent did not produce a final message.
• The system prompt {suffix}exceed(s) the compression threshol

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/8b036e5591d6bc6c. Report an issue: GitHub.