Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

docs: fix custom tool registry documentation to prevent common pitfalls

Cursor Agent1c70a9dbc561
diff --git a/AGENTS.md b/AGENTS.md
index 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, BrowserSession
tools = 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, ActionResult
tools = 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 Tools
Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/tools/available
diff --git a/docs/customize/tools/add.mdx b/docs/customize/tools/add.mdx
index 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, ActionResult
tools = 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 parameters
diff --git a/docs/customize/tools/basics.mdx b/docs/customize/tools/basics.mdx
index 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, BrowserSession
tools = 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>