Agent Settings

​

Overview

The Agent class is the core component of Browser Use that handles browser automation. Here are the main configuration options you can use when initializing an agent.

​

Basic Settings

from browser_use import Agent
from langchain_openai import ChatOpenAI

agent = Agent(
    task="Search for latest news about AI",
    llm=ChatOpenAI(model="gpt-4o"),
)

​

Required Parameters

• task: The instruction for the agent to execute
• llm: A LangChain chat model instance. See LangChain Models for supported models.

​

Agent Behavior

Control how the agent operates:

agent = Agent(
    task="your task",
    llm=llm,
    controller=custom_controller,  # For custom tool calling
    use_vision=True,              # Enable vision capabilities
    save_conversation_path="logs/conversation"  # Save chat logs
)

​

Behavior Parameters

• controller: Registry of functions the agent can call. Defaults to base Controller. See Custom Functions for details.
• use_vision: Enable/disable vision capabilities. Defaults to True.
  • When enabled, the model processes visual information from web pages
  • Disable to reduce costs or use models without vision support
  • For GPT-4o, image processing costs approximately 800-1000 tokens (~$0.002 USD) per image (but this depends on the defined screen size)
• save_conversation_path: Path to save the complete conversation history. Useful for debugging.
• override_system_message: Completely replace the default system prompt with a custom one.
• extend_system_message: Add additional instructions to the default system prompt.

​

(Reuse) Browser Configuration

You can configure how the agent interacts with the browser. To see more Browser options refer to the Browser Settings documentation.

​

Reuse Existing Browser

browser: A Browser Use Browser instance. When provided, the agent will reuse this browser instance and automatically create new contexts for each run().

from browser_use import Agent, Browser
from browser_use.browser.context import BrowserContext

# Reuse existing browser
browser = Browser()
agent = Agent(
    task=task1,
    llm=llm,
    browser=browser  # Browser instance will be reused
)

await agent.run()

# Manually close the browser
await browser.close()

​

Reuse Existing Browser Context

browser_context: A Playwright browser context. Useful for maintaining persistent sessions. See Persistent Browser for more details.

from browser_use import Agent, Browser
from playwright.async_api import BrowserContext

# Use specific browser context (preferred method)
async with await browser.new_context() as context:
    agent = Agent(
        task=task2,
        llm=llm,
        browser_context=context  # Use persistent context
    )

    # Run the agent
    await agent.run()

    # Pass the context to the next agent
    next_agent = Agent(
        task=task2,
        llm=llm,
        browser_context=context
    )

    ...

await browser.close()

For more information about how browser context works, refer to the Playwright documentation.

​

Running the Agent

The agent is executed using the async run() method:

• max_steps (default: 100) Maximum number of steps the agent can take during execution. This prevents infinite loops and helps control execution time.

​

Agent History

The method returns an AgentHistoryList object containing the complete execution history. This history is invaluable for debugging, analysis, and creating reproducible scripts.

# Example of accessing history
history = await agent.run()

# Access (some) useful information
history.urls()              # List of visited URLs
history.screenshots()       # List of screenshot paths
history.action_names()      # Names of executed actions
history.extracted_content() # Content extracted during execution
history.errors()           # Any errors that occurred
history.model_actions()     # All actions with their parameters

The AgentHistoryList provides many helper methods to analyze the execution:

• final_result(): Get the final extracted content
• is_done(): Check if the agent completed successfully
• has_errors(): Check if any errors occurred
• model_thoughts(): Get the agent’s reasoning process
• action_results(): Get results of all actions

​

Run initial actions without LLM

With this example you can run initial actions without the LLM. Specify the action as a dictionary where the key is the action name and the value is the action parameters. You can find all our actions in the Controller source code.

initial_actions = [
	{'open_tab': {'url': 'https://www.google.com'}},
	{'open_tab': {'url': 'https://en.wikipedia.org/wiki/Randomness'}},
	{'scroll_down': {'amount': 1000}},
]
agent = Agent(
	task='What theories are displayed on the page?',
	initial_actions=initial_actions,
	llm=llm,
)

​

Run with message context

You can configure the agent and provide a separate message to help the LLM understand the task better.

from langchain_openai import ChatOpenAI

agent = Agent(
    task="your task",
    message_context="Additional information about the task",
    llm = ChatOpenAI(model='gpt-4o')
)

​

Run with planner model

You can configure the agent to use a separate planner model for high-level task planning:

from langchain_openai import ChatOpenAI

# Initialize models
llm = ChatOpenAI(model='gpt-4o')
planner_llm = ChatOpenAI(model='o3-mini')

agent = Agent(
    task="your task",
    llm=llm,
    planner_llm=planner_llm,           # Separate model for planning
    use_vision_for_planner=False,      # Disable vision for planner
    planner_interval=4                 # Plan every 4 steps
)

​

Planner Parameters

• planner_llm: A LangChain chat model instance used for high-level task planning. Can be a smaller/cheaper model than the main LLM.
• use_vision_for_planner: Enable/disable vision capabilities for the planner model. Defaults to True.
• planner_interval: Number of steps between planning phases. Defaults to 1.

Using a separate planner model can help:

• Reduce costs by using a smaller model for high-level planning
• Improve task decomposition and strategic thinking
• Better handle complex, multi-step tasks

​

Optional Parameters

• message_context: Additional information about the task to help the LLM understand the task better.
• initial_actions: List of initial actions to run before the main task.
• max_actions_per_step: Maximum number of actions to run in a step. Defaults to 10.
• max_failures: Maximum number of failures before giving up. Defaults to 3.
• retry_delay: Time to wait between retries in seconds when rate limited. Defaults to 10.
• generate_gif: Enable/disable GIF generation. Defaults to False. Set to True or a string path to save the GIF.

​

Memory Management

Browser Use includes a procedural memory system using Mem0 that automatically summarizes the agent’s conversation history at regular intervals to optimize context window usage during long tasks.

agent = Agent(
    task="your task",
    llm=llm,
    enable_memory=True,
    memory_interval=10, # create procedural memory every 10 steps
)

​

Memory Parameters

• enable_memory: Enable/disable the procedural memory system. Defaults to True.
• memory_interval: Number of steps between memory summarization. Defaults to 10.
• memory_config: Optional configuration dictionary for the underlying memory system.

​

How Memory Works

When enabled, the agent periodically compresses its conversation history into concise summaries:

1. Every memory_interval steps, the agent reviews its recent interactions
2. It creates a procedural memory summary using the same LLM as the agent
3. The original messages are replaced with the summary, reducing token usage
4. This process helps maintain important context while freeing up the context window

​

Disabling Memory

If you want to disable the memory system (for debugging or for shorter tasks), set enable_memory to False:

agent = Agent(
    task="your task",
    llm=llm,
    enable_memory=False
)