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
Dropdown for agent
Magnus Müller4150f0239694
diff --git a/docs/customize/agent-basic.mdx b/docs/customize/agent-basic.mdxnew file mode 100644index 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 takediff --git a/docs/customize/agent-output-format.mdx b/docs/customize/agent-output-format.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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 messagesdiff --git a/docs/customize/agent-settings.mdx b/docs/customize/agent-settings.mdxdeleted file mode 100644index 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.mdxdeleted file mode 100644index 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.mdxindex 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_dotenvload_dotenv()# Initialize the model-llm = ChatGoogle(model='gemini-2.0-flash-exp')+llm = ChatGoogle(model='gemini-2.5-flash')# Create agent with the modelagent = 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.jsonindex 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.mdxindex 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.mdxindex 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.pyindex 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, ChatOpenAIclass 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()