Message Manager
Relevant source files
The following files were used as context for generating this wiki page:
The Message Manager is a core architectural component responsible for orchestrating the flow of communication between the AI agent and the underlying Large Language Model (LLM). Within the web-ui project, the CustomMessageManager extends the base functionality of the browser-use library to provide specialized prompt handling, token management, and state tracking tailored for complex web automation tasks.
The system ensures that the LLM receives a structured history of events, including system instructions, historical actions, browser state snapshots (text and visual), and task progress updates. It plays a critical role in managing the "Memory" of the agent, ensuring that relevant information is retained while staying within the token constraints of specific models like DeepSeek-R1 or GPT-4.
Architecture and Components
The Message Manager operates as a bridge between the CustomAgent and the LLM providers. It maintains a MessageHistory object and uses specialized prompt classes to format raw browser data into a structured conversational format.
CustomMessageManager Class
The CustomMessageManager class manages the lifecycle of a conversation. It initializes with a task and system prompt, then progressively adds state updates as the agent interacts with the browser.
- Initialization: Upon creation, it sets up the
MessageHistoryand adds the initial system prompt and optional context messages. - Token Management: It tracks
total_tokensand provides logic to trim history (cut_messages) if the context length exceeds defined limits. - State Integration: The
add_state_messagefunction convertsBrowserStateandActionResultobjects intoHumanMessageobjects using a specific prompt class.
Sources: src/agent/custom_message_manager.py:27-65
Data Flow Diagram
The following diagram illustrates how the Message Manager processes browser states and historical actions to generate messages for the LLM.
The diagram shows the sequence where browser states and action results are aggregated by the agent and formatted by the message manager into a structured history for the LLM.
Sources: src/agent/custom_agent.py:255-275, src/agent/custom_message_manager.py:73-85
Prompt Management
The Message Manager relies on custom prompt classes to define the "personality" and operational rules for the agent.
CustomSystemPrompt
This class defines the foundational rules provided to the LLM. Key constraints include:
- Response Format: Mandates a strict JSON output containing
current_state(evaluation, contents, progress, plans, thought, summary) and anactionsequence. - Interaction Rules: Instructions on using element indexes, handling popups, and managing action sequences.
- Deep Research Logic: Instructions for the agent to use
extract_contentwhen performing information-gathering tasks.
Sources: src/agent/custom_prompts.py:12-90
CustomAgentMessagePrompt
This class dynamically constructs the user (human) message for each step. It assembles the following data points:
- Step Information: Current step number vs. max steps.
- Memory: Historical findings and extracted content.
- Browser State: Current URL, open tabs, and a formatted string of interactive elements.
- Action History: A log of the previous actions and their results (success/error).
- Visuals: If vision is enabled, it attaches a base64 encoded screenshot.
Sources: src/agent/custom_prompts.py:110-184
Token and Model Specific Logic
The Message Manager includes specific logic to handle the variations between LLM providers, particularly regarding token counting and context windows.
| Feature | Description | File Reference |
|---|---|---|
| Token Trimming | Automatically removes the oldest messages if total_tokens exceeds max_input_tokens. | custom_message_manager.py:67-71 |
| DeepSeek-R1 Support | Limits context to 64,000 tokens and disables function calling for deepseek-reasoner models. | custom_agent.py:94-100 |
| Vision Integration | Encodes images into image_url message blocks for multimodal models. | custom_prompts.py:175-184 |
| Token Estimation | Falls back to character-based estimation (length // 3) if a specific tokenizer is unavailable. | custom_message_manager.py:87-99 |
Token Counting Logic
The system uses model-specific tokenizers when possible (e.g., for OpenAI or Anthropic) and falls back to a character-to-token ratio for others.
def _count_text_tokens(self, text: str) -> int:
if isinstance(self.llm, (ChatOpenAI, ChatAnthropic, DeepSeekR1ChatOpenAI)):
try:
tokens = self.llm.get_num_tokens(text)
except Exception:
tokens = (len(text) // self.estimated_characters_per_token)
else:
tokens = (len(text) // self.estimated_characters_per_token)
return tokens
Sources: src/agent/custom_message_manager.py:87-99
Interaction Sequence
The following sequence diagram shows how the CustomAgent interacts with the CustomMessageManager during a single execution step.
This diagram demonstrates the flow where the agent triggers message creation, the manager uses the prompt class to format it, and the resulting history is passed to the LLM.
Sources: src/agent/custom_agent.py:255-275, src/agent/custom_message_manager.py:73-85
Summary
The Message Manager is essential for maintaining a coherent and efficient dialogue between the web agent and the LLM. By wrapping browser interactions into a structured JSON-based communication protocol and managing token usage, it allows the agent to execute complex, multi-step tasks across various browser states while preserving critical "memory" of past actions and findings. It specifically enables high-level features like Deep Research by providing the LLM with consistent feedback on task progress and future planning requirements.
Sources: src/agent/custom_message_manager.py, src/agent/custom_agent.py, src/agent/custom_prompts.py