Skip to content

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

Dropdown for agent

Magnus Müller4150f0239694
diff --git a/docs/customize/agent-basic.mdx b/docs/customize/agent-basic.mdx
new file mode 100644
index 000000000..7d897800a
--- /dev/null
+++ b/docs/customize/agent-basic.mdx
@@ -0,0 +1,27 @@
+---
+title: "Basic Setup"
+description: ""
+icon: "play"
+mode: "wide"
+---
+
+
+```python
+from browser_use import Agent, ChatOpenAI
+
+agent = Agent(
+ task="Search for latest news about AI",
+ llm=ChatOpenAI(model="gpt-4.1-mini"),
+)
+
+async def main():
+ history = await agent.run(max_steps=100)
+```
+
+- `task`: The task you want to automate.
+- `llm`: Your favorite LLM. See <a href="/customize/supported-models">Supported Models</a>.
+
+
+The agent is executed using the async `run()` method:
+
+- `max_steps` (default: `100`): Maximum number of steps the agent can take
diff --git a/docs/customize/agent-output-format.mdx b/docs/customize/agent-output-format.mdx
new file mode 100644
index 000000000..8cbf663cf
--- /dev/null
+++ b/docs/customize/agent-output-format.mdx
@@ -0,0 +1,79 @@
+---
+title: "Output Format"
+description: "Understanding agent execution results and structured output"
+icon: "arrow-right-to-bracket"
+mode: "wide"
+---
+
+## Output Format
+
+The `run()` method returns an `AgentHistoryList` object with the complete execution history:
+
+```python
+history = await agent.run()
+
+# Access useful information
+history.urls() # List of visited URLs
+history.screenshot_paths() # List of screenshot paths
+history.screenshots() # List of screenshots as base64 strings
+history.action_names() # Names of executed actions
+history.extracted_content() # List of extracted content from all actions
+history.errors() # List of errors (with None for steps without errors)
+history.model_actions() # All actions with their parameters
+history.model_outputs() # All model outputs from history
+history.last_action() # Last action in history
+
+# Analysis methods
+history.final_result() # Get the final extracted content (last step)
+history.is_done() # Check if agent completed successfully
+history.is_successful() # Check if agent completed successfully (returns None if not done)
+history.has_errors() # Check if any errors occurred
+history.model_thoughts() # Get the agent's reasoning process (AgentBrain objects)
+history.action_results() # Get all ActionResult objects from history
+history.action_history() # Get truncated action history with essential fields
+history.number_of_steps() # Get the number of steps in the history
+history.total_duration_seconds() # Get total duration of all steps in seconds
+
+# Structured output (when using output_model_schema)
+history.structured_output # Property that returns parsed structured output
+```
+
+See all helper methods in the [AgentHistoryList source code](https://github.com/browser-use/browser-use/blob/main/browser_use/agent/views.py#L301).
+
+## Structured Output
+
+For structured data extraction, use the `output_model_schema` parameter with a Pydantic model:
+
+```python
+from pydantic import BaseModel
+from browser_use import Agent, ChatOpenAI
+
+class Post(BaseModel):
+ post_title: str
+ post_url: str
+ num_comments: int
+ hours_since_post: int
+
+class Posts(BaseModel):
+ posts: list[Post]
+
+# Create agent with structured output
+agent = Agent(
+ task="Go to hackernews show hn and give me the first 5 posts",
+ llm=ChatOpenAI(model="gpt-4.1-mini"),
+ output_model_schema=Posts
+)
+
+# Run and parse structured result
+history = await agent.run()
+result = history.final_result()
+
+if result:
+ parsed: Posts = Posts.model_validate_json(result)
+ for post in parsed.posts:
+ print(f"Title: {post.post_title}")
+ print(f"URL: {post.post_url}")
+ print(f"Comments: {post.num_comments}")
+```
+
+For a complete structured output example, see the [custom_output.py example](https://github.com/browser-use/browser-use/blob/main/examples/features/custom_output.py).
diff --git a/docs/customize/agent-parameters.mdx b/docs/customize/agent-parameters.mdx
new file mode 100644
index 000000000..1eaed7c77
--- /dev/null
+++ b/docs/customize/agent-parameters.mdx
@@ -0,0 +1,49 @@
+---
+title: "All Parameters"
+description: "Complete reference for all agent configuration options"
+icon: "sliders"
+mode: "wide"
+---
+
+## Available Parameters
+
+### Core Settings
+- `controller`: Registry of tools the agent can call. Defaults to base Controller. [Example for custom tools](https://github.com/browser-use/browser-use/tree/main/examples/custom-functions)
+- `browser_session`: BrowserSession object where you can specify the browser settings.
+- `output_model_schema`: Pydantic model class for structured output validation. [Full example](https://github.com/browser-use/browser-use/blob/main/examples/features/custom_output.py)
+
+### Vision & Processing
+- `use_vision` (default: `True`): Enable/disable vision capabilities for processing screenshots
+- `vision_detail_level` (default: `'auto'`): Screenshot detail level - `'low'`, `'high'`, or `'auto'`
+- `page_extraction_llm`: Separate LLM model for page content extraction. You can choose a small & fast model because it only needs to extract text from the page (default: same as `llm`)
+
+### Actions & Behavior
+- `initial_actions`: List of actions to run before the main task without LLM. [Full example](https://github.com/browser-use/browser-use/blob/main/examples/features/initial_actions.py)
+- `max_actions_per_step` (default: `10`): Maximum actions per step, e.g. for form filling the agent can output 10 fields at once. We execute the actions until the page changes.
+- `max_failures` (default: `3`): Maximum retries for steps with errors
+- `use_thinking` (default: `True`): Controls whether the agent uses its internal "thinking" field for explicit reasoning steps.
+- `flash_mode` (default: `False`): Fast mode that skips evaluation, next goal and thinking and only uses memory. If `flash_mode` is enabled, it overrides `use_thinking` and disables the thinking process entirely. [Full example](https://github.com/browser-use/browser-use/blob/main/examples/getting_started/05_fast_agent.py)
+
+### System Messages
+- `override_system_message`: Completely replace the default system prompt.
+- `extend_system_message`: Add additional instructions to the default system prompt. [Full example](https://github.com/browser-use/browser-use/blob/main/examples/features/custom_system_prompt.py)
+
+### File & Data Management
+- `save_conversation_path`: Path to save complete conversation history
+- `save_conversation_path_encoding` (default: `'utf-8'`): Encoding for saved conversations
+- `available_file_paths`: List of file paths the agent can access
+- `sensitive_data`: Dictionary of sensitive data to handle carefully. [Full example](https://github.com/browser-use/browser-use/blob/main/examples/features/sensitive_data.py)
+
+### Visual Output
+- `generate_gif` (default: `False`): Generate GIF of agent actions. Set to `True` or string path
+- `include_attributes`: List of HTML attributes to include in page analysis
+
+### Performance & Limits
+- `max_history_items`: Maximum number of last steps to keep in the LLM memory. If `None`, we keep all steps.
+- `llm_timeout` (default: `90`): Timeout in seconds for LLM calls
+- `step_timeout` (default: `120`): Timeout in seconds for each step
+- `preload` (default: `True`): If we detect a url in the task, we directly open it.
+
+### Advanced Options
+- `calculate_cost` (default: `False`): Calculate and track API costs
+- `display_files_in_done_text` (default: `True`): Show file information in completion messages
diff --git a/docs/customize/agent-settings.mdx b/docs/customize/agent-settings.mdx
deleted file mode 100644
index a1c417631..000000000
--- a/docs/customize/agent-settings.mdx
+++ /dev/null
@@ -1,197 +0,0 @@
----
-title: "Agent Settings"
-description: "Learn how to configure the agent"
-icon: "gear"
-mode: "wide"
----
-
-## 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
-
-```python
-from browser_use import Agent, ChatOpenAI
-
-agent = Agent(
- task="Search for latest news about AI",
- llm=ChatOpenAI(model="gpt-4.1-mini"),
-)
-```
-
-### Required Parameters
-
-- `task`: The instruction for the agent to execute
-- `llm`: A chat model instance. See <a href="/customize/supported-models">Supported Models</a> for supported models.
-
-## Agent Behavior
-
-Control how the agent operates:
-
-```python
-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 <a href="/customize/custom-functions">Custom Functions</a> 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)
-- `vision_detail_level`: Controls the detail level of screenshots sent to the vision model. Can be `'low'`, `'high'`, or `'auto'` (default). Using `'low'` can significantly reduce token consumption and cost for simpler visual tasks, while `'high'` provides more detail for complex visual analysis.
-- `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.
-
-<Note>
- Vision capabilities are recommended for better web interaction understanding,
- but can be disabled to reduce costs or when using models without vision
- support.
-</Note>
-
-### Reuse Existing Browser Context
-
-By default browser-use launches its own builtin browser using Playwright-installed chromium.
-You can also connect to a remote browser or pass `browser_session` or `browser_profile` objects to the Agent.
-
-
-These all get passed down to create a `BrowserSession` for the `Agent`:
-
-```python
-agent = Agent(
- task='book a flight to fiji',
- llm=llm,
- browser_profile=browser_profile, # use this profile to create a BrowserSession
- browser_session=BrowserSession( # use an existing BrowserSession
- cdp_url=..., # remote CDP browser to connect to
- # or
- wss_url=..., # remote wss playwright server provider
- # or
- browser_pid=... # pid of a locally running browser process to attach to
- # or
- executable_path=... # provide a custom chrome binary path
- # or
- channel=... # specify chrome, chromium, ms-edge, etc.
-
- ),
-)
-```
-
-For example, to connect to an existing browser over CDP you could do:
-
-```python
-agent = Agent(
- ...
- browser_session=BrowserSession(cdp_url='http://localhost:9222'),
-)
-```
-
-For example, to connect to a local running chrome instance you can do:
-
-```python
-agent = Agent(
- ...
- browser_session=BrowserSession(browser_pid=1234),
-)
-```
-
-See <a href="/customize/real-browser">Connect to your Browser</a> for more info.
-
-<Note>
- You can reuse the same `BrowserSession` after an agent has completed running.
- If you do nothing, the browser will be automatically closed on `run()`
- completion only if it was launched by us.
-</Note>
-
-## 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.
-
-```python
-# Example of accessing history
-history = await agent.run()
-
-# Access (some) useful information
-history.urls() # List of visited URLs
-history.screenshot_paths() # 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
-
-<Note>
- For a complete list of helper methods and detailed history analysis
- capabilities, refer to the [AgentHistoryList source
- code](https://github.com/browser-use/browser-use/blob/main/browser_use/agent/views.py#L111).
-</Note>
-
-## Run initial actions without LLM
-
-With [this example](https://github.com/browser-use/browser-use/blob/main/examples/features/initial_actions.py) 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](https://github.com/browser-use/browser-use/blob/main/browser_use/controller/service.py) source code.
-
-```python
-
-initial_actions = [
- {'go_to_url': {'url': 'https://www.google.com', 'new_tab': True}},
- {'go_to_url': {'url': 'https://en.wikipedia.org/wiki/Randomness', 'new_tab': True}},
- {'scroll_down': {'amount': 1000}},
-]
-agent = Agent(
- task='What theories are displayed on the page?',
- initial_actions=initial_actions,
- llm=llm,
-)
-```
-
-
-
-
-
-### Optional Parameters
-
-- `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
-
-Memory management in browser-use has been significantly improved since version 0.3.2. The agent's context handling and state management are now robust enough that the previous memory system (`mem0`) is no longer needed or supported.
-
-The agent maintains its context and task progress through:
-
-- Detailed history tracking of actions and results
-- Structured state management
-- Clear goal setting and evaluation at each step
-
-The `enable_memory` parameter has been removed as the new system provides better context management by default.
-
-<Note>
- If you're upgrading from an older version that used `enable_memory`, simply remove this parameter. The agent will automatically use the improved context management system.
-</Note>
diff --git a/docs/customize/output-format.mdx b/docs/customize/output-format.mdx
deleted file mode 100644
index 434dcf06f..000000000
--- a/docs/customize/output-format.mdx
+++ /dev/null
@@ -1,51 +0,0 @@
----
-title: "Output Format"
-description: "The default is text. But you can define a structured output format to make post-processing easier."
-icon: "code"
-mode: "wide"
----
-
-## Custom output format
-With [this example](https://github.com/browser-use/browser-use/blob/main/examples/features/custom_output.py) you can define what output format the agent should return to you.
-
-```python
-from pydantic import BaseModel
-# Define the output format as a Pydantic model
-class Post(BaseModel):
- post_title: str
- post_url: str
- num_comments: int
- hours_since_post: int
-
-
-class Posts(BaseModel):
- posts: List[Post]
-
-
-controller = Controller(output_model=Posts)
-
-
-async def main():
- task = 'Go to hackernews show hn and give me the first 5 posts'
- model = ChatOpenAI(model='gpt-4.1-mini')
- agent = Agent(task=task, llm=model, controller=controller)
-
- history = await agent.run()
-
- result = history.final_result()
- if result:
- parsed: Posts = Posts.model_validate_json(result)
-
- for post in parsed.posts:
- print('\n--------------------------------')
- print(f'Title: {post.post_title}')
- print(f'URL: {post.post_url}')
- print(f'Comments: {post.num_comments}')
- print(f'Hours since post: {post.hours_since_post}')
- else:
- print('No result')
-
-
-if __name__ == '__main__':
- asyncio.run(main())
-```
diff --git a/docs/customize/supported-models.mdx b/docs/customize/supported-models.mdx
index b1755e9b9..0c13dd48d 100644
--- a/docs/customize/supported-models.mdx
+++ b/docs/customize/supported-models.mdx
@@ -11,7 +11,6 @@ mode: "wide"
- Fastest: `llama4` on groq
- Balanced: fast + cheap + clever: `gemini-2.5-flash` or `gpt-4.1-mini`
-Find full examples built for you in github [examples/models](https://github.com/browser-use/browser-use/tree/main/examples/models).
### OpenAI
@@ -105,7 +104,7 @@ from dotenv import load_dotenv
load_dotenv()
# Initialize the model
-llm = ChatGoogle(model='gemini-2.0-flash-exp')
+llm = ChatGoogle(model='gemini-2.5-flash')
# Create agent with the model
agent = Agent(
@@ -212,3 +211,4 @@ llm = ChatOllama(model="llama3.1:8b")
## Other models (DeepSeek, Novita, X, Qwen...)
We support all other models that can be called via OpenAI compatible API. We are open to PRs for more providers.
+
diff --git a/docs/docs.json b/docs/docs.json
index 1cb2191e0..8cbb6efd8 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -31,24 +31,26 @@
"group": "Get Started",
"pages": [
"introduction",
- {
- "group": "Quickstart",
- "icon": "rocket",
- "pages": [
- "quickstart",
- "quickstart_llm"
- ]
- }
+ "quickstart",
+ "quickstart_llm"
]
},
{
"group": "Customize",
"pages": [
- "customize/supported-models",
- "customize/agent-settings",
+ {
+ "group": "Agent",
+ "icon": "robot",
+ "isDefaultOpen": true,
+ "pages": [
+ "customize/agent-basic",
+ "customize/supported-models",
+ "customize/agent-parameters",
+ "customize/agent-output-format"
+ ]
+ },
"customize/browser-settings",
"customize/real-browser",
- "customize/output-format",
"customize/sensitive-data",
"customize/custom-functions"
]
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index 3c5f4b2f8..0953b29ef 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -1,5 +1,5 @@
---
-title: "Quickstart for humans"
+title: "Human Quickstart"
description: ""
icon: "person"
---
diff --git a/docs/quickstart_llm.mdx b/docs/quickstart_llm.mdx
index 99d9e2315..2baee2136 100644
--- a/docs/quickstart_llm.mdx
+++ b/docs/quickstart_llm.mdx
@@ -1,5 +1,5 @@
---
-title: "Quickstart for LLMs"
+title: "LLM Quickstart"
description: ""
icon: "robot"
---
diff --git a/examples/features/custom_output.py b/examples/features/custom_output.py
index aa1a500d4..69a7a1f81 100644
--- a/examples/features/custom_output.py
+++ b/examples/features/custom_output.py
@@ -16,7 +16,7 @@ load_dotenv()
from pydantic import BaseModel
-from browser_use import Agent, ChatOpenAI, Controller
+from browser_use import Agent, ChatOpenAI
class Post(BaseModel):
@@ -30,13 +30,10 @@ class Posts(BaseModel):
posts: list[Post]
-controller = Controller(output_model=Posts)
-
-
async def main():
task = 'Go to hackernews show hn and give me the first 5 posts'
model = ChatOpenAI(model='gpt-4.1-mini')
- agent = Agent(task=task, llm=model, controller=controller)
+ agent = Agent(task=task, llm=model, output_model_schema=Posts)
history = await agent.run()