Agent Settings

Configuration options for customizing agent behavior and capabilities

The AgentSettings class controls how the agent thinks, plans, and executes tasks.

Vision & Processing

use_vision

use_vision · bool | 'auto' · default: "True"

Controls vision mode for screenshots:

• "auto" - Includes screenshot tool but only uses vision when explicitly requested
• True - Always includes screenshots in LLM context
• False - Never includes screenshots and excludes screenshot tool

vision_detail_level

vision_detail_level · 'auto' | 'low' | 'high' · default: "auto"

Screenshot detail level for LLM vision models:

• "auto" - Let the LLM provider choose optimal detail
• "low" - Faster, lower cost, reduced detail
• "high" - Slower, higher cost, maximum detail

page_extraction_llm

page_extraction_llm · BaseChatModel

Separate LLM model for page content extraction.

You can use a smaller, faster model since it only needs to extract text from pages.

Default: Same as main llm parameter

---

Actions & Behavior

max_actions_per_step

max_actions_per_step · int · default: "5"

Maximum actions the agent can execute in a single step.

For example, for form filling the agent can output 3 fields at once. Actions are executed until the page changes.

max_failures

max_failures · int · default: "5"

Maximum number of consecutive failures before the agent stops.

Each step error increments the failure counter. Successful steps reset it to 0.

final_response_after_failure

final_response_after_failure · bool · default: "True"

If True, attempts one final LLM call with intermediate output after max_failures is reached.

This allows the agent to provide a summary even if the task couldn’t be completed.

---

Reasoning & Planning

use_thinking

use_thinking · bool · default: "True"

Controls whether the agent uses its internal “thinking” field for explicit reasoning steps.

When enabled, the agent outputs its thought process before choosing actions.

flash_mode

flash_mode · bool · default: "False"

Fast mode that skips evaluation, next goal, and thinking - only uses memory.

Performance: ~2x faster execution

Trade-off: Reduced reasoning capability

See Fast Agent Example

If flash_mode is enabled, it overrides use_thinking and disables the thinking process entirely.

enable_planning

enable_planning · bool · default: "True"

Enable the agent to create and follow multi-step plans for complex tasks.

planning_replan_on_stall

planning_replan_on_stall · int · default: "3"

Number of consecutive failures before triggering a plan revision nudge.

Set to 0 to disable.

planning_exploration_limit

planning_exploration_limit · int · default: "5"

Number of steps without a plan before nudging the agent to create one.

Set to 0 to disable.

---

System Messages

override_system_message

override_system_message · string

Completely replace the default system prompt with a custom one.

Use with caution: This removes all default instructions.

extend_system_message

extend_system_message · string

Add additional instructions to the default system prompt.

See Custom System Prompt Example

---

History & Memory

max_history_items

max_history_items · int

Maximum number of last steps to keep in LLM memory.

Default: None (keeps all steps)

Useful for limiting context size on very long tasks.

message_compaction

message_compaction · MessageCompactionSettings

Settings for summarizing older history into a compact memory block.

Fields:

• enabled (bool): Enable compaction
• compact_every_n_steps (int): Compact every N steps
• trigger_char_count (int): Minimum characters before compaction
• keep_last_items (int): Recent items to keep uncompacted
• summary_max_chars (int): Maximum summary size

---

Loop Detection

loop_detection_enabled

loop_detection_enabled · bool · default: "True"

Enable detection of repetitive actions and nudges to the agent.

loop_detection_window

loop_detection_window · int · default: "20"

Rolling window size for tracking action similarity.

---

Validation & Judging

use_judge

use_judge · bool · default: "True"

Enable lightweight validation of agent success claims.

The judge validates that the agent’s response genuinely satisfies the task requirements.

ground_truth

ground_truth · string

Ground truth answer or criteria for judge validation.

When provided, the judge compares the agent’s output against this ground truth.

---

File & Data Management

save_conversation_path

save_conversation_path · string | Path

Path to save complete conversation history as JSON.

save_conversation_path_encoding

save_conversation_path_encoding · string · default: "utf-8"

Text encoding for saved conversation files.

generate_gif

generate_gif · bool | string · default: "False"

Generate an animated GIF of agent actions.

• True - Save to default location
• string - Save to specified path
• False - Disable

include_attributes

include_attributes · list[string]

List of HTML attributes to include in page analysis.

Default: Common attributes like id, class, href, type, etc.

---

Performance & Limits

llm_timeout

llm_timeout · int · default: "60"

Timeout in seconds for LLM API calls.

Auto-detected values:

• 30s for Gemini models
• 90s for o3 models
• 60s default

step_timeout

step_timeout · int · default: "180"

Timeout in seconds for each agent step (including actions and LLM calls).

calculate_cost

calculate_cost · bool · default: "False"

Track and calculate API costs for LLM calls.

max_clickable_elements_length

max_clickable_elements_length · int · default: "40000"

Maximum characters for clickable elements in the prompt.

---

Example

from browser_use import Agent, AgentSettings, ChatBrowserUse, Browser

agent = Agent(
    task="Research and summarize AI trends",
    llm=ChatBrowserUse(),
    browser=Browser(),
    # Pass custom settings
    flash_mode=True,
    max_actions_per_step=3,
    use_vision='auto',
    max_failures=10,
    extend_system_message="Focus on recent developments from 2024"
)

await agent.run()

Most settings can be passed directly to the Agent constructor as keyword arguments.

---

Related Configuration

• Browser Settings - Configure browser behavior
• Sandbox Settings - Configure cloud execution