​
Overview

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

​
Basic Settings

from openoperator import Agent, LLM

# Define LLM
llm=LLM(model="openai/gpt-4o")

# Create Agent
agent = Agent(llm=llm)

# Add a task
agent.add_task(Search for latest news about AI")

​
Agent Behavior

Control how the agent operates: 
# Define LLM
llm=LLM(model="openai/gpt-4o")

agent = Agent(
    llm=llm,
    controller=custom_controller,  # For custom tool calling
    use_vision=True,              # Enable vision capabilities
    save_conversation_path="logs/conversation.json"  # 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.
Vision capabilities are recommended for better web interaction understanding, but can be disabled to reduce costs or when using models without vision support.

​
(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 OpenOperator Browser instance. When provided, the agent will reuse this browser instance and automatically create new contexts for each run(). 
from openoperator import Agent, Browser
from browser_use.browser.context import BrowserContext

# Define LLM
llm=LLM(model="openai/gpt-4o")

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

# Add a task
agent.add_task("What's the mass of pluto?")

# Run agent
await agent.run()

# Manually close the browser
await browser.close()
Remember: in this scenario the Browser will not be closed automatically.

​
Reuse Existing Browser Context

browser_context: A Playwright browser context. Useful for maintaining persistent sessions. See Persistent Browser for more details. 
from openoperator import Agent, Browser
from playwright.async_api import BrowserContext

# Define LLM
llm=LLM(model="openai/gpt-4o")

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

    # Add a task
    agent.add_task("Summarize today's top 3 news articles.")

    # 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.
You can reuse the same context for multiple agents. If you do nothing, the browser will be automatically created and closed on run() completion.

​
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
For a complete list of helper methods and detailed history analysis capabilities, refer to the AgentHistoryList source code.

​
Run initial actions

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}},
	{'extract_content': {'include_links': False}},
]
agent = Agent(
	initial_actions=initial_actions,
	llm=llm
)