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
docs: fix custom tool registry documentation to prevent common pitfalls
Cursor Agent1c70a9dbc561
diff --git a/AGENTS.md b/AGENTS.mdindex 295b75afa..4e370fa53 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -776,14 +776,14 @@ Tools are the functions that the agent has to interact with the world.## Quick Example```python theme={null}-from browser_use import Tools, ActionResult, Browser+from browser_use import Tools, ActionResult, BrowserSessiontools = Tools()@tools.action('Ask human for help with a question')-def ask_human(question: str, browser: Browser) -> ActionResult:+async def ask_human(question: str, browser_session: BrowserSession) -> ActionResult:answer = input(f'{question} > ')- return f'The human responded with: {answer}'+ return ActionResult(extracted_content=f'The human responded with: {answer}')agent = Agent(task='Ask human for help',@@ -792,8 +792,13 @@ agent = Agent()```+<Warning>+**Important**: The parameter must be named exactly `browser_session` with type `BrowserSession` (not `browser: Browser`).+The agent injects parameters by name matching, so using the wrong name will cause your tool to fail silently.+</Warning>+<Note>- Use `browser` parameter in tools for deterministic [Actor](https://docs.browser-use.com/customize/actor/basics) actions.+ Use `browser_session` parameter in tools for deterministic [Actor](https://docs.browser-use.com/customize/actor/basics) actions.</Note>@@ -821,9 +826,9 @@ from browser_use import Tools, Agent, ActionResulttools = Tools()@tools.action(description='Ask human for help with a question')-def ask_human(question: str) -> ActionResult:+async def ask_human(question: str) -> ActionResult:answer = input(f'{question} > ')- return f'The human responded with: {answer}'+ return ActionResult(extracted_content=f'The human responded with: {answer}')``````python theme={null}@@ -835,6 +840,11 @@ agent = Agent(task='...', llm=llm, tools=tools)The Agent fills your function parameters based on their names, type hints, & defaults.+<Warning>+**Common Pitfall**: Parameter names must match exactly! Use `browser_session: BrowserSession` (not `browser: Browser`).+The agent injects special parameters by **name matching**, so using incorrect names will cause your tool to fail silently.+</Warning>+# Tools: Available ToolsSource: (go to or request this content to learn more) https://docs.browser-use.com/customize/tools/availablediff --git a/docs/customize/tools/add.mdx b/docs/customize/tools/add.mdxindex 564ae650e..4e78f8a56 100644--- a/docs/customize/tools/add.mdx+++ b/docs/customize/tools/add.mdx@@ -21,14 +21,14 @@ Examples:Simply add `@tools.action(...)` to your function.```python-from browser_use import Tools, Agent+from browser_use import Tools, Agent, ActionResulttools = Tools()@tools.action(description='Ask human for help with a question')-def ask_human(question: str) -> ActionResult:+async def ask_human(question: str) -> ActionResult:answer = input(f'{question} > ')- return f'The human responded with: {answer}'+ return ActionResult(extracted_content=f'The human responded with: {answer}')``````python@@ -40,6 +40,12 @@ agent = Agent(task='...', llm=llm, tools=tools)The Agent fills your function parameters based on their names, type hints, & defaults.+<Warning>+**Common Pitfall**: Parameter names must match exactly! Use `browser_session: BrowserSession` (not `browser: Browser`).+The agent injects special parameters by **name matching**, so using incorrect names will cause your tool to fail silently.+See [Available Objects](#available-objects) below for the correct parameter names.+</Warning>+## Available Objects@@ -130,3 +136,39 @@ For a comprehensive example of custom tools with Playwright integration, see:**[Playwright Integration Example](https://github.com/browser-use/browser-use/blob/main/examples/browser/playwright_integration.py)**This shows how to create custom actions that use Playwright's precise browser automation alongside Browser-Use.++## Common Pitfalls++<Warning>+The agent injects special parameters **by name**, not by type. Using incorrect parameter names is the most common cause of tools failing silently.+</Warning>++### ❌ Wrong: Using `browser: Browser`++```python+from browser_use import Tools, ActionResult, Browser+[email protected]('My action')+def my_action(browser: Browser) -> ActionResult: # WRONG!+ # This will NOT receive the browser session+ pass+```++### ✅ Correct: Using `browser_session: BrowserSession`++```python+from browser_use import Tools, ActionResult, BrowserSession+[email protected]('My action')+async def my_action(browser_session: BrowserSession) -> ActionResult: # CORRECT!+ page = await browser_session.must_get_current_page()+ # Now you have access to the browser+ return ActionResult(extracted_content='Done')+```++### Key Points++1. **Use `browser_session: BrowserSession`** - not `browser: Browser`+2. **Use `async` functions** - recommended for consistency with browser operations+3. **Return `ActionResult`** - not plain strings (though strings work, `ActionResult` provides more control)+4. **Parameter names must match exactly** - see [Available Objects](#available-objects) for the full list of injectable parametersdiff --git a/docs/customize/tools/basics.mdx b/docs/customize/tools/basics.mdxindex 053630838..233d0f1c0 100644--- a/docs/customize/tools/basics.mdx+++ b/docs/customize/tools/basics.mdx@@ -10,14 +10,14 @@ mode: "wide"```python-from browser_use import Tools, ActionResult, Browser+from browser_use import Tools, ActionResult, BrowserSessiontools = Tools()@tools.action('Ask human for help with a question')-def ask_human(question: str, browser: Browser) -> ActionResult:+async def ask_human(question: str, browser_session: BrowserSession) -> ActionResult:answer = input(f'{question} > ')- return f'The human responded with: {answer}'+ return ActionResult(extracted_content=f'The human responded with: {answer}')agent = Agent(task='Ask human for help',@@ -26,6 +26,11 @@ agent = Agent()```+<Warning>+**Important**: The parameter must be named exactly `browser_session` with type `BrowserSession` (not `browser: Browser`).+The agent injects parameters by name matching, so using the wrong name will cause your tool to fail silently.+</Warning>+<Note>-Use `browser` parameter in tools for deterministic [Actor](/customize/actor/basics) actions.+Use `browser_session` parameter in tools for deterministic [Actor](/customize/actor/basics) actions.</Note>