Building AI agents, atomically
feat(agent): add max_context_tokens auto-trim to prevent context window overruns
U (OpenClaw)2e82248fdbb4
diff --git a/atomic-agents/atomic_agents/agents/atomic_agent.py b/atomic-agents/atomic_agents/agents/atomic_agent.pyindex b8b459f..48ed6db 100644--- a/atomic-agents/atomic_agents/agents/atomic_agent.py+++ b/atomic-agents/atomic_agents/agents/atomic_agent.py@@ -87,6 +87,14 @@ class AgentConfig(BaseModel):model_config = {"arbitrary_types_allowed": True}mode: Mode = Field(default=Mode.TOOLS, description="The Instructor mode used for structured outputs (TOOLS, JSON, etc.).")model_api_parameters: Optional[dict] = Field(None, description="Additional parameters passed to the API provider.")+ max_context_tokens: Optional[int] = Field(+ None,+ description=(+ "Maximum tokens for the full context (system prompt + history + tools). "+ "When exceeded, oldest conversation turns are automatically trimmed to stay within limit. "+ "Uses LiteLLM's provider-agnostic token counter — works with any supported model."+ ),+ )class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:@@ -112,6 +120,8 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:current_user_input (Optional[InputSchema]): The current user input being processed.model_api_parameters (dict): Additional parameters passed to the API provider.- Use this for parameters like 'temperature', 'max_tokens', etc.+ max_context_tokens (Optional[int]): Maximum tokens for the full context. When exceeded,+ oldest conversation turns are automatically trimmed. Uses LiteLLM's token counter.Hook System:The AtomicAgent integrates with Instructor's hook system to provide comprehensive monitoring@@ -188,6 +198,7 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:self.current_user_input = Noneself.mode = config.modeself.model_api_parameters = config.model_api_parameters or {}+ self.max_context_tokens = config.max_context_tokens# Hook management attributesself._hook_handlers: Dict[str, List[Callable]] = {}@@ -274,6 +285,62 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:}]+ def _trim_context(self) -> None:+ """+ Trim oldest conversation turns to stay within max_context_tokens limit.++ Called before building the messages list. Uses the full context token count+ (system prompt + history + tools) via get_context_token_count().+ Removes oldest turns one at a time until the context fits within the limit.++ Turn-preserving: always removes complete turns, never individual messages.++ Raises:+ ValueError: If a single turn itself exceeds max_context_tokens.+ """+ if self.max_context_tokens is None:+ return++ result = self.get_context_token_count()+ total_tokens = result.total++ if total_tokens <= self.max_context_tokens:+ return++ logger = logging.getLogger(__name__)++ # Collect unique turn_ids in order (oldest first)+ turn_ids_ordered = []+ seen = set()+ for msg in self.history.history:+ if msg.turn_id and msg.turn_id not in seen:+ turn_ids_ordered.append(msg.turn_id)+ seen.add(msg.turn_id)++ # Remove oldest turns until within limit+ for turn_id in turn_ids_ordered:+ if total_tokens <= self.max_context_tokens:+ break++ self.history.delete_turn_id(turn_id)+ new_result = self.get_context_token_count()+ removed = total_tokens - new_result.total+ total_tokens = new_result.total+ logger.warning(+ "Context exceeded max_context_tokens (%d). " "Trimmed turn '%s' (%d tokens). New total: %d.",+ self.max_context_tokens,+ turn_id,+ removed,+ total_tokens,+ )++ if total_tokens > self.max_context_tokens:+ raise ValueError(+ f"max_context_tokens ({self.max_context_tokens}) is smaller than the "+ f"minimum required for a single turn ({total_tokens} tokens). "+ "Increase max_context_tokens or reduce system prompt size."+ )+def _prepare_messages(self):self.messages = self._build_system_messages()history = self.history.get_history()@@ -489,6 +556,10 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:assert not isinstance(self.client, instructor.core.client.AsyncInstructor), "The run method is not supported for async clients. Use run_async instead."++ # Trim history BEFORE adding new user message to protect the new input+ self._trim_context()+if user_input:self.history.initialize_turn()self.current_user_input = user_input@@ -522,6 +593,9 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:assert not isinstance(self.client, instructor.core.client.AsyncInstructor), "The run_stream method is not supported for async clients. Use run_async instead."++ self._trim_context()+if user_input:self.history.initialize_turn()self.current_user_input = user_input@@ -563,6 +637,9 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:Use run_async_stream() method instead for streaming responses."""assert isinstance(self.client, instructor.core.client.AsyncInstructor), "The run_async method is for async clients."++ self._trim_context()+if user_input:self.history.initialize_turn()self.current_user_input = user_input@@ -589,6 +666,7 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:OutputSchema: Partial responses from the chat agent."""assert isinstance(self.client, instructor.core.client.AsyncInstructor), "The run_async method is for async clients."+ self._trim_context()if user_input:self.history.initialize_turn()self.current_user_input = user_inputdiff --git a/atomic-agents/tests/agents/test_atomic_agent.py b/atomic-agents/tests/agents/test_atomic_agent.pyindex e3b36ca..45881c4 100644--- a/atomic-agents/tests/agents/test_atomic_agent.py+++ b/atomic-agents/tests/agents/test_atomic_agent.py@@ -1199,3 +1199,164 @@ def test_prepare_messages_keeps_system_for_openai(mock_instructor, mock_system_phistory_messages = [m for m in agent.messages if m.get("content") != mock_system_prompt_generator.generate_prompt()]assert len(history_messages) == 1assert history_messages[0]["role"] == "system"+++# --- max_context_tokens and _trim_context tests ---+++def test_trim_context_no_op_when_max_context_tokens_unset(mock_instructor, mock_system_prompt_generator):+ """When max_context_tokens is None, _trim_context returns without any action."""+ history = ChatHistory()+ history.add_message("user", BasicChatInputSchema(chat_message="Hello"))+ config = AgentConfig(+ client=mock_instructor,+ model="gpt-5-mini",+ history=history,+ system_prompt_generator=mock_system_prompt_generator,+ # max_context_tokens not set — default None+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)++ # Should not raise, should not modify history+ agent._trim_context()+ assert history.get_message_count() == 1+++@patch("atomic_agents.agents.atomic_agent.get_token_counter")+def test_trim_context_no_op_when_within_limit(mock_get_token_counter, mock_instructor, mock_system_prompt_generator):+ """When context is within max_context_tokens, history is not modified."""+ history = ChatHistory()+ history.add_message("user", BasicChatInputSchema(chat_message="Hello"))++ mock_counter_instance = Mock()+ mock_get_token_counter.return_value = mock_counter_instance+ mock_counter_instance.count_context.return_value = TokenCountResult(+ total=100, system_prompt=30, history=70, tools=0, model="gpt-5-mini", max_tokens=8192, utilization=0.01+ )++ config = AgentConfig(+ client=mock_instructor,+ model="gpt-5-mini",+ history=history,+ system_prompt_generator=mock_system_prompt_generator,+ max_context_tokens=200, # well above current 100+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)+ agent._trim_context()++ # History untouched+ assert history.get_message_count() == 1+ # delete_turn_id never called+ mock_counter_instance.count_context.assert_called_once()+++@patch("atomic_agents.agents.atomic_agent.get_token_counter")+def test_trim_context_trims_oldest_turn_when_over_limit(mock_get_token_counter, mock_instructor, mock_system_prompt_generator):+ """When context exceeds max_context_tokens, oldest turn is removed."""+ history = ChatHistory()++ # Turn 1 (user message)+ history.initialize_turn()+ history.add_message("user", BasicChatInputSchema(chat_message="First request"))++ # Turn 2 (user message)+ history.initialize_turn()+ history.add_message("user", BasicChatInputSchema(chat_message="Second request"))++ turn1_id = history.history[0].turn_id++ mock_counter_instance = Mock()+ mock_get_token_counter.return_value = mock_counter_instance+ # First call: over limit; Second call: within limit after one turn removed+ mock_counter_instance.count_context.side_effect = [+ TokenCountResult(+ total=500, system_prompt=100, history=400, tools=0, model="gpt-5-mini", max_tokens=8192, utilization=0.06+ ),+ TokenCountResult(+ total=150, system_prompt=100, history=50, tools=0, model="gpt-5-mini", max_tokens=8192, utilization=0.018+ ),+ ]++ config = AgentConfig(+ client=mock_instructor,+ model="gpt-5-mini",+ history=history,+ system_prompt_generator=mock_system_prompt_generator,+ max_context_tokens=200,+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)+ agent._trim_context()++ # Turn 1 should be gone; Turn 2 remains+ assert history.get_message_count() == 1+ remaining = history.history[0]+ assert remaining.content.chat_message == "Second request"+ assert remaining.turn_id != turn1_id+++@patch("atomic_agents.agents.atomic_agent.get_token_counter")+def test_trim_context_raises_when_single_turn_exceeds_limit(+ mock_get_token_counter, mock_instructor, mock_system_prompt_generator+):+ """When even one turn exceeds max_context_tokens, ValueError is raised."""+ history = ChatHistory()+ history.initialize_turn()+ history.add_message("user", BasicChatInputSchema(chat_message="Very long message that exceeds the limit"))++ mock_counter_instance = Mock()+ mock_get_token_counter.return_value = mock_counter_instance+ # Even after trimming all turns, still over limit+ mock_counter_instance.count_context.return_value = TokenCountResult(+ total=500, system_prompt=400, history=100, tools=0, model="gpt-5-mini", max_tokens=8192, utilization=0.06+ )++ config = AgentConfig(+ client=mock_instructor,+ model="gpt-5-mini",+ history=history,+ system_prompt_generator=mock_system_prompt_generator,+ max_context_tokens=100, # artificially low+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)++ with pytest.raises(ValueError, match="max_context_tokens.*smaller than the minimum"):+ agent._trim_context()+++@patch("atomic_agents.agents.atomic_agent.get_token_counter")+def test_trim_context_called_before_user_message_in_run(mock_get_token_counter, mock_instructor, mock_system_prompt_generator):+ """_trim_context runs before the new user message is added to history."""+ history = ChatHistory()++ # Existing turn in history+ history.initialize_turn()+ history.add_message("user", BasicChatInputSchema(chat_message="Old message"))++ mock_counter_instance = Mock()+ mock_get_token_counter.return_value = mock_counter_instance+ mock_counter_instance.count_context.side_effect = [+ TokenCountResult(+ total=500, system_prompt=100, history=400, tools=0, model="gpt-5-mini", max_tokens=8192, utilization=0.06+ ),+ TokenCountResult(+ total=50, system_prompt=100, history=0, tools=0, model="gpt-5-mini", max_tokens=8192, utilization=0.006+ ),+ ]++ config = AgentConfig(+ client=mock_instructor,+ model="gpt-5-mini",+ history=history,+ system_prompt_generator=mock_system_prompt_generator,+ max_context_tokens=200,+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)++ # Mock chat completion+ mock_instructor.chat.completions.create.return_value = BasicChatOutputSchema(chat_message="Response")++ agent.run(BasicChatInputSchema(chat_message="New message"))++ # Old turn was trimmed BEFORE new message was added+ assert history.get_message_count() == 2 # assistant response + new user message+ assert history.history[0].content.chat_message == "New message" # new message is first