Custom Prompts & User Agents

Relevant source files

The following files were used as context for generating this wiki page:

• examples/features/custom_system_prompt.py
• browser_use/agent/prompts.py
• browser_use/browser/context.py
• browser_use/agent/message_manager/service.py
• browser_use/agent/views.py
• examples/use-cases/post-twitter.py

The browser-use library provides a robust framework for customizing how AI agents perceive the web and how they identify themselves to web servers. This is achieved through a programmable prompt system and configurable browser contexts. Custom prompts allow developers to inject specific behavioral rules and response formats into the LLM, while custom User Agents (UA) enable the browser to mimic specific devices or bypass simple bot detection mechanisms.

System Prompt Architecture

The system prompt is the foundational set of instructions given to the LLM to define its role as a browser automation agent. The architecture relies on the SystemPrompt class, which generates a structured template for the LLM to follow.

Components of the System Prompt

The default system prompt is composed of several logical blocks that ensure the agent operates within expected parameters:

• Response Format: Enforces a strict JSON structure containing current_state (summary, evaluation, memory, next goal) and action sequences.
• Action Logic: Defines how to chain multiple actions like form filling or navigation.
• Interaction Rules: Instructions on using element indexes, handling popups, and visual context verification.
• Task Completion: Guidelines on when to use the done action and how to report final results.

Sources: browser_use/agent/prompts.py:17-105

Customizing System Prompts

Users can extend the default prompt logic by subclassing SystemPrompt. This allows for the injection of "Important Rules" that take precedence over or supplement existing instructions.

class MySystemPrompt(SystemPrompt):
    def important_rules(self) -> str:
        existing_rules = super().important_rules()
        new_rules = 'REMEMBER: ALWAYS open Wikipedia first!'
        return f'{existing_rules}\n{new_rules}'

Sources: examples/features/custom_system_prompt.py:16-21

The following diagram illustrates how the MessageManager assembles these prompts before sending them to the LLM:

The diagram shows the decision flow for selecting between default and user-defined prompt logic during agent startup. Sources: browser_use/agent/message_manager/service.py:45-70

User Agent Configuration

The User Agent (UA) string identifies the browser to the web server. Customizing this is critical for compatibility and avoiding "headless" browser detection.

BrowserContextConfig

The BrowserContextConfig class manages the User Agent setting. By default, it uses a standard Chrome UA on Windows.

Parameter	Type	Default Value	Description
user_agent	str	Mozilla/5.0 ... Chrome/85.0.4183.102 ...	The UA string sent in HTTP headers.
browser_window_size	Dict	{'width': 1280, 'height': 1100}	Viewport dimensions associated with the UA.
disable_security	bool	False	Whether to bypass CSP and HTTPS errors.

Sources: browser_use/browser/context.py:44-118

Implementation in Playwright

When a BrowserSession is initialized, the custom UA is passed directly to the Playwright new_context method. This ensures that every request made by the agent carries the specified identity.

This sequence shows the propagation of the User Agent string from configuration to the underlying browser driver. Sources: browser_use/browser/context.py:194-210

Message Management & History

The MessageManager handles the stateful conversation between the agent and the LLM. It manages the injection of system prompts, task instructions, and browser state results.

Token & Sensitivity Control

The manager includes logic to filter sensitive data from prompts and trim history to fit within model token limits.

• Filtering: Uses a sensitive_data dictionary to replace real values with <secret>key</secret> placeholders in the prompt history.
• Trimming: If the token count exceeds max_input_tokens, the manager removes the image or truncates the text of the oldest state messages.

Sources: browser_use/agent/message_manager/service.py:165-245

Message Flow Structure

1. System Message: The instructions generated by SystemPrompt.
2. Task Message: The user-defined task (e.g., "Post to Twitter").
3. Example Tool Call: A few-shot example helping the LLM understand the AgentOutput format.
4. History Memory: Previous actions and results marked for inclusion.
5. Current State: The live DOM tree, URL, and screenshot.

Sources: browser_use/agent/message_manager/service.py:65-115, browser_use/agent/prompts.py:133-167

Summary of Customization Options

Feature	Class/Method	Purpose
Custom Rules	SystemPrompt.important_rules()	Add domain-specific constraints to agent behavior.
Output Schema	Controller(output_model=...)	Define a custom Pydantic model for the final result.
Identity	BrowserContextConfig(user_agent=...)	Spoof specific browsers or devices.
Element Context	AgentMessagePrompt	Adjust which HTML attributes are included in the prompt.

Sources: browser_use/agent/views.py:53-65, browser_use/controller/service.py:45-55, browser_use/browser/context.py:112

Customizing prompts and user agents allows browser-use agents to be tailored for complex environments, ranging from secure corporate portals requiring specific identity headers to specialized research tasks requiring custom logic injected into the system instruction set.