Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
added message compaction for agent
Saurav Panda79501fe2cd55
diff --git a/browser_use/agent/message_manager/service.py b/browser_use/agent/message_manager/service.pyindex 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 BrowserStateSummaryfrom browser_use.filesystem.file_system import FileSystem+from browser_use.llm.base import BaseChatModelfrom browser_use.llm.messages import (BaseMessage,ContentPartImageParam,ContentPartTextParam,SystemMessage,+ UserMessage,)from browser_use.observability import observe_debugfrom browser_use.utils import match_url_with_domain_pattern, time_execution_sync@@ -139,15 +142,19 @@ class MessageManager:@propertydef 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 itemsif 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 someomitted_count = total_items - self.max_history_items@@ -163,7 +170,7 @@ class MessageManager:# Add most recent itemsitems_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_pathsunavailable_skills_info: str | None = None, # Information about skills that cannot be used yetplan_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 inclusionscreenshots = []diff --git a/browser_use/agent/message_manager/views.py b/browser_use/agent/message_manager/views.pyindex 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-triggersmodel_config = ConfigDict(arbitrary_types_allowed=True)diff --git a/browser_use/agent/service.py b/browser_use/agent/service.pyindex 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 stateself.state = injected_agent_state or AgentState()@@ -1073,6 +1081,16 @@ class Agent(Generic[Context, AgentStructuredOutput]):# Render plan description for injection into agent contextplan_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_pathsunavailable_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.pyindex 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 ActionModellogger = 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 = Trueground_truth: str | None = None # Ground truth answer or criteria for judge validationmax_history_items: int | None = None+ message_compaction: MessageCompactionSettings | None = Noneenable_planning: bool = Trueplanning_replan_on_stall: int = 3 # consecutive failures before replan nudge; 0 = disabledplanning_exploration_limit: int = 5 # steps without a plan before nudge; 0 = disabled