Browser Use Tool Provider

The BrowserUseToolProvider provides browser automation capabilities using the browser-use library.

Installation

pip install 'stirrup[browser]'  # or: uv add 'stirrup[browser]'

Prerequisites

Local browser (default):

# Install Chromium browser
uvx browser-use install

Cloud browser (optional):

For cloud-hosted browser sessions, set the BROWSER_USE_API_KEY environment variable:

export BROWSER_USE_API_KEY=your-api-key-here

Get your API key from the Browser Use Cloud dashboard.

Quick Start

import asyncio

from stirrup import Agent
from stirrup.clients.chat_completions_client import ChatCompletionsClient
from stirrup.tools import DEFAULT_TOOLS
from stirrup.tools.browser_use import BrowserUseToolProvider


async def main() -> None:
    """Run browser automation example."""
    client = ChatCompletionsClient(
        base_url="https://openrouter.ai/api/v1",
        model="anthropic/claude-sonnet-4.5",
    )

    browser_provider = BrowserUseToolProvider(
        headless=False,  # Set to True for headless mode
    )

    agent = Agent(
        client=client,
        name="browser_agent",
        tools=[*DEFAULT_TOOLS, browser_provider],
        system_prompt=(
            "You are a web automation assistant. Use the browser tools to complete tasks. "
            "Always start by taking a snapshot to see the current page state and element indices. "
            "Use the indices from the snapshot when clicking or typing."
        ),
    )

    async with agent.session(output_dir="output/browser_use_example") as session:
        _finish_params, _history, _metadata = await session.run(
            "Go to artificial analysis and select GPT-5 (high) on the AA Index score"
        )


if __name__ == "__main__":
    asyncio.run(main())

Available Tools

When you add BrowserUseToolProvider to your agent, it exposes the following tools (all prefixed with browser_ by default):

Navigation

Tool	Description
browser_search	Search using Google, DuckDuckGo, or Bing
browser_navigate	Navigate to a URL (optionally in new tab)
browser_go_back	Go back in browser history
browser_wait	Wait for specified seconds (1-30)

Page Interaction

Tool	Description
browser_click	Click an element by index
browser_input_text	Type text into a form field
browser_scroll	Scroll up or down
browser_find_text	Find and scroll to specific text
browser_send_keys	Send keyboard keys (Enter, Tab, etc.)

JavaScript

Tool	Description
browser_evaluate_js	Execute custom JavaScript code

Tab Management

Tool	Description
browser_switch_tab	Switch to a different tab by index

Content Extraction

Tool	Description
browser_snapshot	Get accessibility tree with element indices
browser_screenshot	Take a screenshot of the page
browser_get_url	Get current page URL

Workflow

The typical workflow for browser automation:

1. Navigate to a page using browser_navigate or browser_search
2. Snapshot the page using browser_snapshot to see elements and their indices
3. Interact with elements using browser_click, browser_input_text, etc.
4. Repeat snapshot and interaction as needed

The snapshot returns an accessibility tree showing interactive elements with numerical indices that you reference in other tools.

Configuration

BrowserUseToolProvider

stirrup.tools.browser_use.BrowserUseToolProvider

BrowserUseToolProvider(
    *,
    headless: bool = True,
    disable_security: bool = False,
    executable_path: str | None = None,
    cdp_url: str | None = None,
    use_cloud: bool = False,
    tool_prefix: str = "browser",
    extra_args: list[str] | None = None,
)

Bases: ToolProvider

Browser automation tool provider using browser-use library.

Provides tools for: - Navigation: search, navigate, go_back, wait - Page Interaction: click, input_text, scroll, find_text, send_keys - JavaScript: evaluate_js - Tab Management: switch_tab - Content Extraction: snapshot, screenshot, get_url

Example

from stirrup.tools.browser_use import BrowserUseToolProvider

agent = Agent( client=client, name="browser_agent", tools=[BrowserUseToolProvider(headless=False)], )

async with agent.session() as session: await session.run("Navigate to example.com and click the first link")

Initialize BrowserUseToolProvider.

Parameters:

Name	Type	Description	Default
headless	bool	Run browser in headless mode (default: True)	True
disable_security	bool	Disable browser security features (default: False)	False
executable_path	str | None	Path to Chrome/Chromium executable	None
cdp_url	str | None	Chrome DevTools Protocol URL for remote connection	None
use_cloud	bool	Use Browser Use cloud browser (requires BROWSER_USE_API_KEY env var)	False
tool_prefix	str	Prefix for tool names (default: "browser")	'browser'
extra_args	list[str] | None	Additional Chromium command line arguments	None

Source code in src/stirrup/tools/browser_use.py

def __init__(
    self,
    *,
    headless: bool = True,
    disable_security: bool = False,
    executable_path: str | None = None,
    cdp_url: str | None = None,
    use_cloud: bool = False,
    tool_prefix: str = "browser",
    extra_args: list[str] | None = None,
) -> None:
    """Initialize BrowserUseToolProvider.

    Args:
        headless: Run browser in headless mode (default: True)
        disable_security: Disable browser security features (default: False)
        executable_path: Path to Chrome/Chromium executable
        cdp_url: Chrome DevTools Protocol URL for remote connection
        use_cloud: Use Browser Use cloud browser (requires BROWSER_USE_API_KEY env var)
        tool_prefix: Prefix for tool names (default: "browser")
        extra_args: Additional Chromium command line arguments

    """
    self._headless = headless
    self._disable_security = disable_security
    self._executable_path = executable_path
    self._cdp_url = cdp_url
    self._use_cloud = use_cloud
    self._tool_prefix = tool_prefix
    self._extra_args = extra_args

    self._session: BrowserSession | None = None

__aenter__ async

__aenter__() -> list[Tool[Any, Any]]

Enter async context: start browser and return tools.

Source code in src/stirrup/tools/browser_use.py

async def __aenter__(self) -> list[Tool[Any, Any]]:
    """Enter async context: start browser and return tools."""
    if self._use_cloud and not os.environ.get("BROWSER_USE_API_KEY"):
        raise ValueError(
            "BROWSER_USE_API_KEY environment variable is required when use_cloud=True. "
            "Get your API key from https://cloud.browser-use.com"
        )
    self._session = BrowserSession(  # type: ignore[call-overload]
        headless=self._headless,
        disable_security=self._disable_security,
        executable_path=self._executable_path,
        cdp_url=self._cdp_url,
        use_cloud=self._use_cloud,
        args=self._extra_args,
    )
    await self._session.start()
    return self._build_tools()

__aexit__ async

__aexit__(
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> None

Exit async context: close browser.

Source code in src/stirrup/tools/browser_use.py

async def __aexit__(
    self,
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> None:
    """Exit async context: close browser."""
    if self._session:
        await self._session.stop()
        self._session = None

Configuration Options

Parameter	Type	Default	Description
headless	bool	True	Run browser without visible window
disable_security	bool	False	Disable browser security features
executable_path	str \| None	None	Path to Chrome/Chromium
cdp_url	str \| None	None	CDP URL for remote browser
tool_prefix	str	"browser"	Prefix for tool names
extra_args	list[str] \| None	None	Extra Chromium args

Cloud Browser

To use a cloud-hosted browser:

import os

browser_provider = BrowserUseToolProvider(
    use_cloud=True,  # Requires BROWSER_USE_API_KEY env var
)

This requires setting the BROWSER_USE_API_KEY environment variable.

Example

See the full example at examples/browser_use_example.py.