Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

added message compaction for agent

Saurav Panda79501fe2cd55
diff --git a/browser_use/agent/message_manager/service.py b/browser_use/agent/message_manager/service.py
index 3eff1bcfb..7f4726e21 100644
--- a/browser_use/agent/message_manager/service.py
+++ b/browser_use/agent/message_manager/service.py
@@ -11,15 +11,18 @@ from browser_use.agent.views import (
ActionResult,
AgentOutput,
AgentStepInfo,
+ MessageCompactionSettings,
MessageManagerState,
)
from browser_use.browser.views import BrowserStateSummary
from browser_use.filesystem.file_system import FileSystem
+from browser_use.llm.base import BaseChatModel
from browser_use.llm.messages import (
BaseMessage,
ContentPartImageParam,
ContentPartTextParam,
SystemMessage,
+ UserMessage,
)
from browser_use.observability import observe_debug
from browser_use.utils import match_url_with_domain_pattern, time_execution_sync
@@ -139,15 +142,19 @@ class MessageManager:
@property
def agent_history_description(self) -> str:
"""Build agent history description from list of items, respecting max_history_items limit"""
+ compacted_prefix = ''
+ if self.state.compacted_memory:
+ compacted_prefix = f'<compacted_memory>\n{self.state.compacted_memory}\n</compacted_memory>\n'
+
if self.max_history_items is None:
# Include all items
- return '\n'.join(item.to_string() for item in self.state.agent_history_items)
+ return compacted_prefix + '\n'.join(item.to_string() for item in self.state.agent_history_items)
total_items = len(self.state.agent_history_items)
# If we have fewer items than the limit, just return all items
if total_items <= self.max_history_items:
- return '\n'.join(item.to_string() for item in self.state.agent_history_items)
+ return compacted_prefix + '\n'.join(item.to_string() for item in self.state.agent_history_items)
# We have more items than the limit, so we need to omit some
omitted_count = total_items - self.max_history_items
@@ -163,7 +170,7 @@ class MessageManager:
# Add most recent items
items_to_include.extend([item.to_string() for item in self.state.agent_history_items[-recent_items_count:]])
- return '\n'.join(items_to_include)
+ return compacted_prefix + '\n'.join(items_to_include)
def add_new_task(self, new_task: str) -> None:
new_task = '<follow_up_user_request> ' + new_task.strip() + ' </follow_up_user_request>'
@@ -173,6 +180,135 @@ class MessageManager:
task_update_item = HistoryItem(system_message=new_task)
self.state.agent_history_items.append(task_update_item)
+ def prepare_step_state(
+ self,
+ browser_state_summary: BrowserStateSummary,
+ model_output: AgentOutput | None = None,
+ result: list[ActionResult] | None = None,
+ step_info: AgentStepInfo | None = None,
+ sensitive_data=None,
+ ) -> None:
+ """Prepare state for the next LLM call without building the final state message."""
+ # Clear contextual messages from previous steps to prevent accumulation
+ self.state.history.context_messages.clear()
+
+ # Update the agent history items with the latest step results
+ self._update_agent_history_description(model_output, result, step_info)
+
+ # Update sensitive data description for this page
+ effective_sensitive_data = sensitive_data if sensitive_data is not None else self.sensitive_data
+ if effective_sensitive_data is not None:
+ # Update instance variable to keep it in sync
+ self.sensitive_data = effective_sensitive_data
+ self.sensitive_data_description = self._get_sensitive_data_description(browser_state_summary.url)
+
+ async def maybe_compact_messages(
+ self,
+ llm: BaseChatModel | None,
+ settings: MessageCompactionSettings | None,
+ step_info: AgentStepInfo | None = None,
+ ) -> bool:
+ """Compact message history into a short memory block when thresholds are exceeded."""
+ if not settings or not settings.enabled:
+ return False
+ if llm is None:
+ logger.debug('Message compaction enabled but no LLM provided; skipping.')
+ return False
+
+ # Respect cooldown to avoid repeated compaction loops
+ if (
+ step_info is not None
+ and self.state.last_compaction_step is not None
+ and step_info.step_number - self.state.last_compaction_step < settings.cooldown_steps
+ ):
+ return False
+
+ history_items = self.state.agent_history_items
+ if settings.min_history_items and len(history_items) < settings.min_history_items:
+ return False
+
+ full_history_text = '\n'.join(item.to_string() for item in history_items).strip()
+ current_char_count = len(full_history_text)
+ # trigger_char_count is always resolved to an int by the model validator
+ trigger_char_count = settings.trigger_char_count or 250000
+ if current_char_count < trigger_char_count:
+ return False
+
+ # After the first compaction, only re-trigger when history has grown by at least
+ # trigger_char_count beyond the post-compaction baseline. This prevents a cycle
+ # where verbose retained items immediately re-trigger compaction after cooldown.
+ if self.state.post_compaction_char_count > 0:
+ growth = current_char_count - self.state.post_compaction_char_count
+ if growth < trigger_char_count:
+ return False
+
+ logger.debug(
+ f'Compacting message history (items={len(history_items)}, chars={len(full_history_text)})'
+ )
+
+ # Build compaction input, optionally including prior compacted memory
+ compaction_sections = []
+ if self.state.compacted_memory:
+ compaction_sections.append(
+ f'<previous_compacted_memory>\n{self.state.compacted_memory}\n</previous_compacted_memory>'
+ )
+ compaction_sections.append(f'<agent_history>\n{full_history_text}\n</agent_history>')
+ if settings.include_read_state and self.state.read_state_description:
+ compaction_sections.append(f'<read_state>\n{self.state.read_state_description}\n</read_state>')
+ compaction_input = '\n\n'.join(compaction_sections)
+
+ # Filter sensitive data before sending to LLM
+ if self.sensitive_data:
+ filtered = self._filter_sensitive_data(UserMessage(content=compaction_input))
+ compaction_input = filtered.text
+
+ system_prompt = (
+ 'You are summarizing an agent run for prompt compaction.\n'
+ 'Capture task requirements, key facts, decisions, partial progress, errors, and next steps.\n'
+ 'Preserve important entities, values, URLs, and file paths.\n'
+ 'Return plain text only. Do not include tool calls or JSON.'
+ )
+ if settings.summary_max_chars:
+ system_prompt += f' Keep under {settings.summary_max_chars} characters if possible.'
+
+ messages = [SystemMessage(content=system_prompt), UserMessage(content=compaction_input)]
+ try:
+ response = await llm.ainvoke(messages)
+ summary = (response.completion or '').strip()
+ except Exception as e:
+ logger.warning(f'Failed to compact messages: {e}')
+ return False
+
+ if not summary:
+ logger.debug('Message compaction produced empty summary; skipping.')
+ return False
+
+ if settings.summary_max_chars and len(summary) > settings.summary_max_chars:
+ summary = summary[: settings.summary_max_chars].rstrip() + '…'
+
+ self.state.compacted_memory = summary
+ self.state.compaction_count += 1
+ if step_info is not None:
+ self.state.last_compaction_step = step_info.step_number
+
+ # Trim history to keep only the first item and the most recent items
+ keep_last = max(0, settings.keep_last_items)
+ if len(history_items) > keep_last + 1:
+ if keep_last == 0:
+ self.state.agent_history_items = [history_items[0]]
+ else:
+ self.state.agent_history_items = [history_items[0]] + history_items[-keep_last:]
+
+ # Record post-compaction char count so we only re-trigger after meaningful growth
+ post_text = '\n'.join(item.to_string() for item in self.state.agent_history_items).strip()
+ self.state.post_compaction_char_count = len(post_text)
+
+ logger.debug(
+ f'Compaction complete (summary_chars={len(summary)}, history_items={len(self.state.agent_history_items)})'
+ )
+
+ return True
+
def _update_agent_history_description(
self,
model_output: AgentOutput | None = None,
@@ -300,21 +436,18 @@ class MessageManager:
available_file_paths: list[str] | None = None, # Always pass current available_file_paths
unavailable_skills_info: str | None = None, # Information about skills that cannot be used yet
plan_description: str | None = None, # Rendered plan for injection into agent state
+ skip_state_update: bool = False,
) -> None:
"""Create single state message with all content"""
- # Clear contextual messages from previous steps to prevent accumulation
- self.state.history.context_messages.clear()
-
- # First, update the agent history items with the latest step results
- self._update_agent_history_description(model_output, result, step_info)
-
- # Use the passed sensitive_data parameter, falling back to instance variable
- effective_sensitive_data = sensitive_data if sensitive_data is not None else self.sensitive_data
- if effective_sensitive_data is not None:
- # Update instance variable to keep it in sync
- self.sensitive_data = effective_sensitive_data
- self.sensitive_data_description = self._get_sensitive_data_description(browser_state_summary.url)
+ if not skip_state_update:
+ self.prepare_step_state(
+ browser_state_summary=browser_state_summary,
+ model_output=model_output,
+ result=result,
+ step_info=step_info,
+ sensitive_data=sensitive_data,
+ )
# Use only the current screenshot, but check if action results request screenshot inclusion
screenshots = []
diff --git a/browser_use/agent/message_manager/views.py b/browser_use/agent/message_manager/views.py
index 88076ba52..9bab41777 100644
--- a/browser_use/agent/message_manager/views.py
+++ b/browser_use/agent/message_manager/views.py
@@ -94,5 +94,9 @@ class MessageManagerState(BaseModel):
read_state_description: str = ''
# Images to include in the next state message (cleared after each step)
read_state_images: list[dict[str, Any]] = Field(default_factory=list)
+ compacted_memory: str | None = None
+ compaction_count: int = 0
+ last_compaction_step: int | None = None
+ post_compaction_char_count: int = 0 # History char count right after last compaction; used to gate re-triggers
model_config = ConfigDict(arbitrary_types_allowed=True)
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index adeade90a..12d3c4179 100644
--- a/browser_use/agent/service.py
+++ b/browser_use/agent/service.py
@@ -57,6 +57,7 @@ from browser_use.agent.views import (
BrowserStateHistory,
DetectedVariable,
JudgementResult,
+ MessageCompactionSettings,
PlanItem,
SimpleJudgeResult,
StepMetadata,
@@ -202,6 +203,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
loop_detection_window: int = 20,
loop_detection_enabled: bool = True,
llm_screenshot_size: tuple[int, int] | None = None,
+ message_compaction: MessageCompactionSettings | bool | None = True,
_url_shortening_limit: int = 25,
**kwargs,
):
@@ -376,6 +378,9 @@ class Agent(Generic[Context, AgentStructuredOutput]):
self.sample_images = sample_images
+ if isinstance(message_compaction, bool):
+ message_compaction = MessageCompactionSettings(enabled=message_compaction)
+
self.settings = AgentSettings(
use_vision=use_vision,
vision_detail_level=vision_detail_level,
@@ -403,6 +408,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
planning_exploration_limit=planning_exploration_limit,
loop_detection_window=loop_detection_window,
loop_detection_enabled=loop_detection_enabled,
+ message_compaction=message_compaction,
)
# Token cost service
@@ -410,6 +416,8 @@ class Agent(Generic[Context, AgentStructuredOutput]):
self.token_cost_service.register_llm(llm)
self.token_cost_service.register_llm(page_extraction_llm)
self.token_cost_service.register_llm(judge_llm)
+ if self.settings.message_compaction and self.settings.message_compaction.compaction_llm:
+ self.token_cost_service.register_llm(self.settings.message_compaction.compaction_llm)
# Initialize state
self.state = injected_agent_state or AgentState()
@@ -1073,6 +1081,16 @@ class Agent(Generic[Context, AgentStructuredOutput]):
# Render plan description for injection into agent context
plan_description = self._render_plan_description()
+ self._message_manager.prepare_step_state(
+ browser_state_summary=browser_state_summary,
+ model_output=self.state.last_model_output,
+ result=self.state.last_result,
+ step_info=step_info,
+ sensitive_data=self.sensitive_data,
+ )
+
+ await self._maybe_compact_messages(step_info)
+
self._message_manager.create_state_messages(
browser_state_summary=browser_state_summary,
model_output=self.state.last_model_output,
@@ -1084,6 +1102,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
available_file_paths=self.available_file_paths, # Always pass current available_file_paths
unavailable_skills_info=unavailable_skills_info,
plan_description=plan_description,
+ skip_state_update=True,
)
await self._inject_budget_warning(step_info)
@@ -1095,6 +1114,19 @@ class Agent(Generic[Context, AgentStructuredOutput]):
await self._force_done_after_failure()
return browser_state_summary
+ async def _maybe_compact_messages(self, step_info: AgentStepInfo | None = None) -> None:
+ """Optionally compact message history to keep prompts small."""
+ settings = self.settings.message_compaction
+ if not settings or not settings.enabled:
+ return
+
+ compaction_llm = settings.compaction_llm or self.settings.page_extraction_llm or self.llm
+ await self._message_manager.maybe_compact_messages(
+ llm=compaction_llm,
+ settings=settings,
+ step_info=step_info,
+ )
+
@observe_debug(ignore_input=True, name='get_next_action')
async def _get_next_action(self, browser_state_summary: BrowserStateSummary) -> None:
"""Execute LLM interaction with retry logic and handle callbacks"""
diff --git a/browser_use/agent/views.py b/browser_use/agent/views.py
index ece2ce6e9..8eaaf3f17 100644
--- a/browser_use/agent/views.py
+++ b/browser_use/agent/views.py
@@ -31,6 +31,40 @@ from browser_use.tools.registry.views import ActionModel
logger = logging.getLogger(__name__)
+class MessageCompactionSettings(BaseModel):
+ """Configuration options for message compaction.
+
+ Thresholds can be specified as either char count or token count (not both).
+ Token counts are converted to char counts using chars_per_token as a rough
+ approximation — we deliberately avoid provider-specific tokenizers to keep
+ dependencies light. The default of ~4 chars/token is a reasonable average
+ for English text; set lower (~3) for code-heavy workloads.
+ """
+
+ enabled: bool = True
+ trigger_char_count: int | None = None # Trigger when history exceeds this many chars; set via trigger_token_count if preferred
+ trigger_token_count: int | None = None # Trigger when history exceeds this many estimated tokens
+ chars_per_token: float = 4.0 # Rough chars-per-token ratio for token estimation
+ min_history_items: int = 12
+ keep_last_items: int = 6
+ summary_max_chars: int = 6000
+ cooldown_steps: int = 3
+ include_read_state: bool = False
+ compaction_llm: BaseChatModel | None = None
+
+ @model_validator(mode='after')
+ def _resolve_trigger_threshold(self) -> MessageCompactionSettings:
+ """Resolve trigger_char_count from trigger_token_count if needed."""
+ if self.trigger_char_count is not None and self.trigger_token_count is not None:
+ raise ValueError('Set trigger_char_count or trigger_token_count, not both.')
+ if self.trigger_token_count is not None:
+ self.trigger_char_count = int(self.trigger_token_count * self.chars_per_token)
+ elif self.trigger_char_count is None:
+ # Default: ~62k tokens worth of chars
+ self.trigger_char_count = 250000
+ return self
+
+
class AgentSettings(BaseModel):
"""Configuration options for the Agent"""
@@ -49,6 +83,7 @@ class AgentSettings(BaseModel):
use_judge: bool = True
ground_truth: str | None = None # Ground truth answer or criteria for judge validation
max_history_items: int | None = None
+ message_compaction: MessageCompactionSettings | None = None
enable_planning: bool = True
planning_replan_on_stall: int = 3 # consecutive failures before replan nudge; 0 = disabled
planning_exploration_limit: int = 5 # steps without a plan before nudge; 0 = disabled