Skip to content

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

Add Playwright integration example to documentation

Magnus Müller73fa4b56dbb3
diff --git a/docs/customize/examples/playwright-integration.mdx b/docs/customize/examples/playwright-integration.mdx
new file mode 100644
index 000000000..216a8a944
--- /dev/null
+++ b/docs/customize/examples/playwright-integration.mdx
@@ -0,0 +1,393 @@
+---
+title: "Playwright Integration"
+description: "Advanced example showing Playwright and Browser-Use working together"
+icon: "wand-magic-sparkles"
+mode: "wide"
+---
+
+## Key Features
+
+1. Browser-Use and Playwright sharing the same Chrome instance via CDP
+2. Take actions with Playwright and continue with Browser-Use actions
+3. Let the agent call Playwright functions like screenshot or click on selectors for deterministic steps
+
+
+## Installation
+
+```bash
+uv pip install playwright aiohttp
+```
+
+## Full Example
+
+```python
+import asyncio
+import os
+import subprocess
+import sys
+import tempfile
+
+from pydantic import BaseModel, Field
+
+# Check for required dependencies first - before other imports
+try:
+ import aiohttp # type: ignore
+ from playwright.async_api import Browser, Page, async_playwright # type: ignore
+except ImportError as e:
+ print(f'❌ Missing dependencies for this example: {e}')
+ print('This example requires: playwright aiohttp')
+ print('Install with: uv add playwright aiohttp')
+ print('Also run: playwright install chromium')
+ sys.exit(1)
+
+from browser_use import Agent, BrowserSession, ChatOpenAI, Tools
+from browser_use.agent.views import ActionResult
+
+# Global Playwright browser instance - shared between custom actions
+playwright_browser: Browser | None = None
+playwright_page: Page | None = None
+
+
+# Custom action parameter models
+class PlaywrightFillFormAction(BaseModel):
+ """Parameters for Playwright form filling action."""
+
+ customer_name: str = Field(..., description='Customer name to fill')
+ phone_number: str = Field(..., description='Phone number to fill')
+ email: str = Field(..., description='Email address to fill')
+ size_option: str = Field(..., description='Size option (small/medium/large)')
+
+
+class PlaywrightScreenshotAction(BaseModel):
+ """Parameters for Playwright screenshot action."""
+
+ filename: str = Field(default='playwright_screenshot.png', description='Filename for screenshot')
+ quality: int | None = Field(default=None, description='JPEG quality (1-100), only for .jpg/.jpeg files')
+
+
+class PlaywrightGetTextAction(BaseModel):
+ """Parameters for getting text using Playwright selectors."""
+
+ selector: str = Field(..., description='CSS selector to get text from. Use "title" for page title.')
+
+
+async def start_chrome_with_debug_port(port: int = 9222):
+ """
+ Start Chrome with remote debugging enabled.
+ Returns the Chrome process.
+ """
+ # Create temporary directory for Chrome user data
+ user_data_dir = tempfile.mkdtemp(prefix='chrome_cdp_')
+
+ # Chrome launch command
+ chrome_paths = [
+ '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', # macOS
+ '/usr/bin/google-chrome', # Linux
+ '/usr/bin/chromium-browser', # Linux Chromium
+ 'chrome', # Windows/PATH
+ 'chromium', # Generic
+ ]
+
+ chrome_exe = None
+ for path in chrome_paths:
+ if os.path.exists(path) or path in ['chrome', 'chromium']:
+ try:
+ # Test if executable works
+ test_proc = await asyncio.create_subprocess_exec(
+ path, '--version', stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
+ )
+ await test_proc.wait()
+ chrome_exe = path
+ break
+ except Exception:
+ continue
+
+ if not chrome_exe:
+ raise RuntimeError('❌ Chrome not found. Please install Chrome or Chromium.')
+
+ # Chrome command arguments
+ cmd = [
+ chrome_exe,
+ f'--remote-debugging-port={port}',
+ f'--user-data-dir={user_data_dir}',
+ '--no-first-run',
+ '--no-default-browser-check',
+ '--disable-extensions',
+ 'about:blank', # Start with blank page
+ ]
+
+ # Start Chrome process
+ process = await asyncio.create_subprocess_exec(*cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+ # Wait for Chrome to start and CDP to be ready
+ cdp_ready = False
+ for _ in range(20): # 20 second timeout
+ try:
+ async with aiohttp.ClientSession() as session:
+ async with session.get(
+ f'http://localhost:{port}/json/version', timeout=aiohttp.ClientTimeout(total=1)
+ ) as response:
+ if response.status == 200:
+ cdp_ready = True
+ break
+ except Exception:
+ pass
+ await asyncio.sleep(1)
+
+ if not cdp_ready:
+ process.terminate()
+ raise RuntimeError('❌ Chrome failed to start with CDP')
+
+ return process
+
+
+async def connect_playwright_to_cdp(cdp_url: str):
+ """
+ Connect Playwright to the same Chrome instance Browser-Use is using.
+ This enables custom actions to use Playwright functions.
+ """
+ global playwright_browser, playwright_page
+
+ playwright = await async_playwright().start()
+ playwright_browser = await playwright.chromium.connect_over_cdp(cdp_url)
+
+ # Get or create a page
+ if playwright_browser and playwright_browser.contexts and playwright_browser.contexts[0].pages:
+ playwright_page = playwright_browser.contexts[0].pages[0]
+ elif playwright_browser:
+ context = await playwright_browser.new_context()
+ playwright_page = await context.new_page()
+
+
+# Create custom tools that use Playwright functions
+tools = Tools()
+
+
+ "Fill out a form using Playwright's precise form filling capabilities. This uses Playwright selectors for reliable form interaction.",
+ param_model=PlaywrightFillFormAction,
+)
+async def playwright_fill_form(params: PlaywrightFillFormAction, browser_session: BrowserSession):
+ """
+ Custom action that uses Playwright to fill forms with high precision.
+ This demonstrates how to create Browser-Use actions that leverage Playwright's capabilities.
+ """
+ try:
+ if not playwright_page:
+ return ActionResult(error='Playwright not connected. Run setup first.')
+
+ # Filling form with Playwright's precise selectors
+
+ # Wait for form to be ready and fill basic fields
+ await playwright_page.wait_for_selector('input[name="custname"]', timeout=10000)
+ await playwright_page.fill('input[name="custname"]', params.customer_name)
+ await playwright_page.fill('input[name="custtel"]', params.phone_number)
+ await playwright_page.fill('input[name="custemail"]', params.email)
+
+ # Handle size selection - check if it's a select dropdown or radio buttons
+ size_select = playwright_page.locator('select[name="size"]')
+ size_radio = playwright_page.locator(f'input[name="size"][value="{params.size_option}"]')
+
+ if await size_select.count() > 0:
+ # It's a select dropdown
+ await playwright_page.select_option('select[name="size"]', params.size_option)
+ elif await size_radio.count() > 0:
+ # It's radio buttons
+ await playwright_page.check(f'input[name="size"][value="{params.size_option}"]')
+ else:
+ raise ValueError(f'Could not find size input field for value: {params.size_option}')
+
+ # Get form data to verify it was filled
+ form_data = {}
+ form_data['name'] = await playwright_page.input_value('input[name="custname"]')
+ form_data['phone'] = await playwright_page.input_value('input[name="custtel"]')
+ form_data['email'] = await playwright_page.input_value('input[name="custemail"]')
+
+ # Get size value based on input type
+ if await size_select.count() > 0:
+ form_data['size'] = await playwright_page.input_value('select[name="size"]')
+ else:
+ # For radio buttons, find the checked one
+ checked_radio = playwright_page.locator('input[name="size"]:checked')
+ if await checked_radio.count() > 0:
+ form_data['size'] = await checked_radio.get_attribute('value')
+ else:
+ form_data['size'] = 'none selected'
+
+ success_msg = f'✅ Form filled successfully with Playwright: {form_data}'
+
+ return ActionResult(
+ extracted_content=success_msg, include_in_memory=True, long_term_memory=f'Filled form with: {form_data}'
+ )
+
+ except Exception as e:
+ error_msg = f'❌ Playwright form filling failed: {str(e)}'
+ return ActionResult(error=error_msg)
+
+
+ "Take a screenshot using Playwright's screenshot capabilities with high quality and precision.",
+ param_model=PlaywrightScreenshotAction,
+)
+async def playwright_screenshot(params: PlaywrightScreenshotAction, browser_session: BrowserSession):
+ """
+ Custom action that uses Playwright's advanced screenshot features.
+ """
+ try:
+ if not playwright_page:
+ return ActionResult(error='Playwright not connected. Run setup first.')
+
+ # Taking screenshot with Playwright
+
+ # Use Playwright's screenshot with full page capture
+ screenshot_kwargs = {'path': params.filename, 'full_page': True}
+
+ # Add quality parameter only for JPEG files
+ if params.quality is not None and params.filename.lower().endswith(('.jpg', '.jpeg')):
+ screenshot_kwargs['quality'] = params.quality
+
+ await playwright_page.screenshot(**screenshot_kwargs)
+
+ success_msg = f'✅ Screenshot saved as {params.filename} using Playwright'
+
+ return ActionResult(
+ extracted_content=success_msg, include_in_memory=True, long_term_memory=f'Screenshot saved: {params.filename}'
+ )
+
+ except Exception as e:
+ error_msg = f'❌ Playwright screenshot failed: {str(e)}'
+ return ActionResult(error=error_msg)
+
+
+ "Extract text from elements using Playwright's powerful CSS selectors and XPath support.", param_model=PlaywrightGetTextAction
+)
+async def playwright_get_text(params: PlaywrightGetTextAction, browser_session: BrowserSession):
+ """
+ Custom action that uses Playwright's advanced text extraction with CSS selectors and XPath.
+ """
+ try:
+ if not playwright_page:
+ return ActionResult(error='Playwright not connected. Run setup first.')
+
+ # Extracting text with Playwright selectors
+
+ # Handle special selectors
+ if params.selector.lower() == 'title':
+ # Use page.title() for title element
+ text_content = await playwright_page.title()
+ result_data = {
+ 'selector': 'title',
+ 'text_content': text_content,
+ 'inner_text': text_content,
+ 'tag_name': 'TITLE',
+ 'is_visible': True,
+ }
+ else:
+ # Use Playwright's robust element selection and text extraction
+ element = playwright_page.locator(params.selector).first
+
+ if await element.count() == 0:
+ error_msg = f'❌ No element found with selector: {params.selector}'
+ return ActionResult(error=error_msg)
+
+ text_content = await element.text_content()
+ inner_text = await element.inner_text()
+
+ # Get additional element info
+ tag_name = await element.evaluate('el => el.tagName')
+ is_visible = await element.is_visible()
+
+ result_data = {
+ 'selector': params.selector,
+ 'text_content': text_content,
+ 'inner_text': inner_text,
+ 'tag_name': tag_name,
+ 'is_visible': is_visible,
+ }
+
+ success_msg = f'✅ Extracted text using Playwright: {result_data}'
+
+ return ActionResult(
+ extracted_content=str(result_data),
+ include_in_memory=True,
+ long_term_memory=f'Extracted from {params.selector}: {result_data["text_content"]}',
+ )
+
+ except Exception as e:
+ error_msg = f'❌ Playwright text extraction failed: {str(e)}'
+ return ActionResult(error=error_msg)
+
+
+async def main():
+ """
+ Main function demonstrating Browser-Use + Playwright integration with custom actions.
+ """
+ print('🚀 Advanced Playwright + Browser-Use Integration with Custom Actions')
+
+ chrome_process = None
+ try:
+ # Step 1: Start Chrome with CDP debugging
+ chrome_process = await start_chrome_with_debug_port()
+ cdp_url = 'http://localhost:9222'
+
+ # Step 2: Connect Playwright to the same Chrome instance
+ await connect_playwright_to_cdp(cdp_url)
+
+ # Step 3: Create Browser-Use session connected to same Chrome
+ browser_session = BrowserSession(cdp_url=cdp_url)
+
+ # Step 4: Create AI agent with our custom Playwright-powered tools
+ agent = Agent(
+ task="""
+ Please help me demonstrate the integration between Browser-Use and Playwright:
+
+ 1. First, navigate to https://httpbin.org/forms/post
+ 2. Use the 'playwright_fill_form' action to fill the form with these details:
+ - Customer name: "Alice Johnson"
+ - Phone: "555-9876"
+ - Email: "[email protected]"
+ - Size: "large"
+ 3. Take a screenshot using the 'playwright_screenshot' action and save it as "form_demo.png"
+ 4. Extract the title of the page using 'playwright_get_text' action with selector "title"
+ 5. Finally, submit the form and tell me what happened
+
+ This demonstrates how Browser-Use AI can orchestrate tasks while using Playwright's precise capabilities for specific operations.
+ """,
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+ tools=tools, # Our custom tools with Playwright actions
+ browser_session=browser_session,
+ )
+
+ print('🎯 Starting AI agent with custom Playwright actions...')
+
+ # Step 5: Run the agent - it will use both Browser-Use actions and our custom Playwright actions
+ result = await agent.run()
+
+ # Keep browser open briefly to see results
+ print(f'✅ Integration demo completed! Result: {result}')
+ await asyncio.sleep(2) # Brief pause to see results
+
+ except Exception as e:
+ print(f'❌ Error: {e}')
+ raise
+
+ finally:
+ # Clean up resources
+ if playwright_browser:
+ await playwright_browser.close()
+
+ if chrome_process:
+ chrome_process.terminate()
+ try:
+ await asyncio.wait_for(chrome_process.wait(), 5)
+ except TimeoutError:
+ chrome_process.kill()
+
+ print('✅ Cleanup complete')
+
+
+if __name__ == '__main__':
+ # Run the advanced integration demo
+ asyncio.run(main())
+```
diff --git a/docs/customize/tools/add.mdx b/docs/customize/tools/add.mdx
index eb88ad127..e17cbd730 100644
--- a/docs/customize/tools/add.mdx
+++ b/docs/customize/tools/add.mdx
@@ -15,6 +15,7 @@ Examples:
- calling LLMs
- get 2fa codes
- send emails
+- Playwright integration (see [GitHub example](https://github.com/browser-use/browser-use/blob/main/examples/browser/playwright_integration.py))
- ...
Simply add `@tools.action(...)` to your function.
@@ -83,3 +84,10 @@ def fill_bank_form(account_number: str) -> str:
# Only works on mybank.com
return f'Filled form for account {account_number}'
```
+
+## Advanced Example
+
+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.
diff --git a/docs/docs.json b/docs/docs.json
index 58d40acfa..cd67ff003 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -129,6 +129,7 @@
"customize/examples/fast-agent",
"customize/examples/chain-agents",
"customize/examples/parallel-browser",
+ "customize/examples/playwright-integration",
"customize/examples/sensitive-data",
"customize/examples/secure",
"customize/examples/more-examples",
@@ -248,4 +249,4 @@
"linkedin": "https://linkedin.com/company/browser-use"
}
}
-}
+}
\ No newline at end of file