Skip to content

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.py
index 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 = None
self.mode = config.mode
self.model_api_parameters = config.model_api_parameters or {}
+ self.max_context_tokens = config.max_context_tokens
# Hook management attributes
self._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_input
diff --git a/atomic-agents/tests/agents/test_atomic_agent.py b/atomic-agents/tests/agents/test_atomic_agent.py
index 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_p
history_messages = [m for m in agent.messages if m.get("content") != mock_system_prompt_generator.generate_prompt()]
assert len(history_messages) == 1
assert 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