{"record":{"id":"84291c122f731607","repo":"agentscope-ai/agentscope","slug":"the-reserve-ratio-of-the-context-config-must-be","errorCode":null,"errorMessage":"The 'reserve_ratio' of the context config must be smaller than its 'trigger_ratio', got {self.context_config.reserve_ratio} and {self.context_config.trigger_ratio}.","messagePattern":"The 'reserve_ratio' of the context config must be smaller than its 'trigger_ratio', got (.+?) and (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/agent/_agent.py","lineNumber":232,"sourceCode":"\n        # Set when a `ReplyEndEvent` escapes the reply middleware chain; the\n        # reply loop only exits after the event is delivered (not swallowed)\n        self._receive_reply_end: bool = False\n\n    def _validate_configs(self) -> None:\n        \"\"\"Validate the config combinations that a single config class cannot\n        check by itself.\n\n        Raises:\n            `ValueError`:\n                If the reserved/buffer ratios don't leave room ahead of the\n                context compression threshold.\n        \"\"\"\n        if (\n            self.context_config.reserve_ratio\n            >= self.context_config.trigger_ratio\n        ):\n            raise ValueError(\n                \"The 'reserve_ratio' of the context config must be smaller \"\n                \"than its 'trigger_ratio', got \"\n                f\"{self.context_config.reserve_ratio} and \"\n                f\"{self.context_config.trigger_ratio}.\",\n            )\n\n        if (\n            self.injection_config.inject_runtime_state\n            and self.injection_config.context_buffer_ratio\n            >= self.context_config.trigger_ratio\n        ):\n            raise ValueError(\n                \"The 'context_buffer_ratio' of the injection config must be \"\n                \"smaller than the 'trigger_ratio' of the context config, so \"\n                \"that the context length is injected before the compression, \"\n                f\"got {self.injection_config.context_buffer_ratio} and \"\n                f\"{self.context_config.trigger_ratio}.\",\n            )","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/agent/_agent.py#L214-L250","documentation":"During Agent __init__ validation: the context compression config requires reserve_ratio to be strictly smaller than trigger_ratio. reserve_ratio is the fraction of the context preserved after compression; if it is >= the ratio that triggers compression, compression could never free enough space, so the agent refuses to start.","triggerScenarios":"Constructing an Agent (or calling _validate_configs via __init__) with ContextConfig(reserve_ratio=0.5, trigger_ratio=0.4) or equal values (0.5, 0.5). The check is >=, so equality is also rejected.","commonSituations":"Tuning context-compression ratios without realizing the ordering constraint; defaults changed across versions; copying config examples where ratios were swapped; setting trigger_ratio low (e.g. 0.1) while leaving reserve_ratio at a default above it.","solutions":["Set reserve_ratio strictly below trigger_ratio, e.g. reserve_ratio=0.2, trigger_ratio=0.5","If you lowered trigger_ratio, lower reserve_ratio to match (rule of thumb: reserve ≈ half of trigger)","Add an assertion/normalization step in your config loader so misordered ratios fail fast with a clear message"],"exampleFix":"# before\nagent = ReActAgent(\n    context_config=ContextConfig(trigger_ratio=0.4, reserve_ratio=0.5),\n)\n\n# after\nagent = ReActAgent(\n    context_config=ContextConfig(trigger_ratio=0.5, reserve_ratio=0.2),\n)","handlingStrategy":"validation","validationCode":"def make_context_config(trigger: float, reserve: float) -> ContextConfig:\n    if not 0 < reserve < trigger <= 1:\n        raise ValueError(\n            f\"Need 0 < reserve_ratio < trigger_ratio <= 1, got reserve={reserve}, trigger={trigger}\"\n        )\n    return ContextConfig(trigger_ratio=trigger, reserve_ratio=reserve)\n\nagent = ReActAgent(context_config=make_context_config(0.5, 0.2))","typeGuard":"from typing import TypeGuard\n\ndef valid_context_ratios(trigger: float, reserve: float) -> TypeGuard[float]:\n    return 0 < reserve < trigger <= 1","tryCatchPattern":"try:\n    agent = ReActAgent(context_config=cfg)\nexcept ValueError as e:\n    if \"reserve_ratio\" in str(e):\n        cfg.reserve_ratio = cfg.trigger_ratio / 2\n        agent = ReActAgent(context_config=cfg)\n    else:\n        raise","preventionTips":["Treat ratio ordering as an invariant: reserve < trigger, always strict","Define ratios in one place (config file) with a validation hook","Rule of thumb: reserve_ratio ≈ half of trigger_ratio","Add unit tests for config boundaries, including equality (which is rejected)"],"tags":["configuration","validation","context-compression","agent","ratio"],"backgroundTag":"config-validation-failed","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}