{"record":{"id":"8b036e5591d6bc6c","repo":"agentscope-ai/agentscope","slug":"the-context-buffer-ratio-of-the-injection-config","errorCode":null,"errorMessage":"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}.","messagePattern":"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 (.+?) and (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/agent/_agent.py","lineNumber":244,"sourceCode":"                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            )\n\n    # =======================================================================\n    # Agent public methods\n    # =======================================================================\n\n    async def reply_stream(\n        self,\n        inputs: Msg\n        | list[Msg]\n        | UserConfirmResultEvent\n        | UserInterruptEvent\n        | ExternalExecutionResultEvent","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/agent/_agent.py#L226-L262","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make context_buffer_ratio strictly smaller than trigger_ratio, e.g. context_buffer_ratio=0.3, trigger_ratio=0.5","Alternatively disable injection: inject_runtime_state=False, which skips the check","Centralize both ratios in one config object so they are always tuned together"],"exampleFix":"# before\nagent = ReActAgent(\n    context_config=ContextConfig(trigger_ratio=0.5),\n    injection_config=InjectionConfig(inject_runtime_state=True, context_buffer_ratio=0.7),\n)\n\n# after\nagent = ReActAgent(\n    context_config=ContextConfig(trigger_ratio=0.5),\n    injection_config=InjectionConfig(inject_runtime_state=True, context_buffer_ratio=0.3),\n)","handlingStrategy":"validation","validationCode":"def validate_agent_ratios(trigger: float, buffer_ratio: float, inject: bool) -> None:\n    if inject and buffer_ratio >= trigger:\n        raise ValueError(\n            f\"context_buffer_ratio ({buffer_ratio}) must be < trigger_ratio ({trigger}) \"\n            \"when inject_runtime_state=True\"\n        )\n\nvalidate_agent_ratios(cfg.trigger_ratio, inj.context_buffer_ratio, inj.inject_runtime_state)\nagent = ReActAgent(context_config=cfg, injection_config=inj)","typeGuard":"from typing import TypeGuard\n\ndef ratios_compatible(trigger: float, buffer_ratio: float) -> TypeGuard[float]:\n    return buffer_ratio < trigger","tryCatchPattern":"try:\n    agent = ReActAgent(context_config=ctx, injection_config=inj)\nexcept ValueError as e:\n    if \"context_buffer_ratio\" in str(e):\n        inj.context_buffer_ratio = ctx.trigger_ratio * 0.6\n        agent = ReActAgent(context_config=ctx, injection_config=inj)\n    else:\n        raise","preventionTips":["Tune trigger_ratio and context_buffer_ratio together, never in isolation","Remember the check only applies when inject_runtime_state=True — disabling it is a valid escape hatch","Keep context_buffer_ratio meaningfully below trigger_ratio (e.g. 60% of it) so state injection has headroom"],"tags":["configuration","validation","context-injection","agent","ratio"],"backgroundTag":"config-validation-failed","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}