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
Implement GitHub-based template system
ShawnPana944905554ed1
diff --git a/browser_use/cli_templates/advanced_template.py b/browser_use/cli_templates/advanced_template.pydeleted file mode 100644index 5fdb84556..000000000--- a/browser_use/cli_templates/advanced_template.py+++ /dev/null@@ -1,51 +0,0 @@-"""-Advanced Example--This example demonstrates how to configure the Agent and Browser-with many configuration options, all set to default values.--Check out all configuration settings at https://docs.browser-use.com/customize/agent/all-parameters.-"""--import asyncio--from dotenv import load_dotenv--from browser_use import Agent, Browser, ChatBrowserUse--load_dotenv()---async def main():- browser = Browser(- use_cloud=False,- # headless=False,- # disable_security=False,- # extra_chromium_args=[],- # allowed_domains=None,- # prohibited_domains=None,- # cdp_url=None,- )-- llm = ChatBrowserUse()-- agent = Agent(- task='Find the number of stars of the browser-use repository on GitHub',- llm=llm,- browser=browser,- # use_vision='auto',- # save_conversation_path=None,- # max_failures=3,- # generate_gif=False,- # max_actions_per_step=4,- # use_thinking=True,- # flash_mode=False,- # calculate_cost=False,- # step_timeout=180,- )-- await agent.run()---if __name__ == '__main__':- asyncio.run(main())diff --git a/browser_use/cli_templates/default_template.py b/browser_use/cli_templates/default_template.pydeleted file mode 100644index 5e53725ce..000000000--- a/browser_use/cli_templates/default_template.py+++ /dev/null@@ -1,30 +0,0 @@-"""-Default browser-use example using ChatBrowserUse--The simplest way to use browser-use - capable of any web task-with minimal configuration.-"""--import asyncio--from dotenv import load_dotenv--from browser_use import Agent, Browser, ChatBrowserUse--load_dotenv()---async def main():- browser = Browser(use_cloud=False)- llm = ChatBrowserUse()- task = 'Find the number of stars of the browser-use repository on GitHub'- agent = Agent(- browser=browser,- task=task,- llm=llm,- )- await agent.run()---if __name__ == '__main__':- asyncio.run(main())diff --git a/browser_use/cli_templates/tools_template.py b/browser_use/cli_templates/tools_template.pydeleted file mode 100644index 7e86dabc7..000000000--- a/browser_use/cli_templates/tools_template.py+++ /dev/null@@ -1,46 +0,0 @@-"""-Custom Tools Example--This example demonstrates how to create custom tools that the agent can use-alongside the built-in browser actions.-"""--import asyncio--from dotenv import load_dotenv--from browser_use import ActionResult, Agent, Browser, ChatBrowserUse, Tools--load_dotenv()--# Create a Tools instance to register custom actions-tools = Tools()--[email protected]('Save text content to a file')-async def save_to_file(filename: str, content: str):- from pathlib import Path-- try:- Path(filename).write_text(content, encoding='utf-8')- return ActionResult(extracted_content=f'Saved to {filename}', include_in_memory=True)- except Exception as e:- return ActionResult(extracted_content=f'Error saving file: {e}', include_in_memory=True)---async def main():- browser = Browser(use_cloud=False)- llm = ChatBrowserUse()- task = 'Go to github.com and find the number of GitHub stars for browser-use and use the save_to_file tool to save the result to stars.txt'- agent = Agent(- task=task,- llm=llm,- browser=browser,- tools=tools,- )-- await agent.run()---if __name__ == '__main__':- asyncio.run(main())diff --git a/browser_use/init_cmd.py b/browser_use/init_cmd.pyindex 137a383ec..595726429 100644--- a/browser_use/init_cmd.py+++ b/browser_use/init_cmd.py@@ -5,8 +5,11 @@ This module provides a minimal command-line interface for generatingbrowser-use templates without requiring heavy TUI dependencies."""+import jsonimport sysfrom pathlib import Path+from urllib import request+from urllib.error import URLErrorimport clickfrom InquirerPy.base.control import Choice@@ -16,8 +19,8 @@ from rich.console import Consolefrom rich.panel import Panelfrom rich.text import Text-# Template metadata-INIT_TEMPLATES = {+# Hardcoded template metadata (fallback if GitHub fetch fails)+FALLBACK_TEMPLATES = {'default': {'file': 'default_template.py','description': 'Simplest setup - capable of any web task with minimal configuration',@@ -30,11 +33,93 @@ INIT_TEMPLATES = {'file': 'tools_template.py','description': 'Custom tool example - extend agent capabilities with your own functions',},+ 'shopping': {+ 'file': 'shopping/main.py',+ 'description': 'E-commerce automation with structured output (Pydantic models)',+ },+ 'job-application': {+ 'file': 'job-application/main.py',+ 'description': 'Automated job application form submission with resume upload',+ },}+# Export for backward compatibility with cli.py+INIT_TEMPLATES = FALLBACK_TEMPLATES+# Rich console for styled outputconsole = Console()+# GitHub template repository URL (for runtime fetching)+TEMPLATE_REPO_URL = 'https://raw.githubusercontent.com/browser-use/template-library/main'+++def _fetch_template_list() -> dict[str, dict[str, str]] | None:+ """+ Fetch template list from GitHub templates.json.++ Returns template dict if successful, None if failed.+ """+ try:+ url = f'{TEMPLATE_REPO_URL}/templates.json'+ with request.urlopen(url, timeout=5) as response:+ data = response.read().decode('utf-8')+ return json.loads(data)+ except (URLError, TimeoutError, json.JSONDecodeError, Exception):+ return None+++def _get_template_list() -> dict[str, dict[str, str]]:+ """+ Get template list - tries GitHub first, falls back to hardcoded.+ """+ templates = _fetch_template_list()+ if templates is not None:+ return templates+ return FALLBACK_TEMPLATES+++def _fetch_from_github(file_path: str) -> str | None:+ """+ Fetch template file from GitHub.++ Returns file content if successful, None if failed.+ """+ try:+ url = f'{TEMPLATE_REPO_URL}/{file_path}'+ with request.urlopen(url, timeout=5) as response:+ return response.read().decode('utf-8')+ except (URLError, TimeoutError, Exception):+ return None+++def _fetch_binary_from_github(file_path: str) -> bytes | None:+ """+ Fetch binary file from GitHub.++ Returns file content if successful, None if failed.+ """+ try:+ url = f'{TEMPLATE_REPO_URL}/{file_path}'+ with request.urlopen(url, timeout=5) as response:+ return response.read()+ except (URLError, TimeoutError, Exception):+ return None+++def _get_template_content(file_path: str) -> str:+ """+ Get template file content from GitHub.++ Raises exception if fetch fails.+ """+ content = _fetch_from_github(file_path)++ if content is not None:+ return content++ raise FileNotFoundError(f'Could not fetch template from GitHub: {file_path}')++# InquirerPy style for template selection (browser-use orange theme)inquirer_style = InquirerPyStyle({@@ -72,7 +157,7 @@ def _write_init_file(output_path: Path, content: str, force: bool = False) -> bo@click.option('--template','-t',- type=click.Choice(['default', 'advanced', 'tools'], case_sensitive=False),+ type=str,help='Template to use',)@click.option(@@ -123,6 +208,9 @@ def main(uvx browser-use init --list"""+ # Fetch template list at runtime+ INIT_TEMPLATES = _get_template_list()+# Handle --list flagif list_templates:console.print('\n[bold]Available templates:[/bold]\n')@@ -164,6 +252,14 @@ def main(def _(event):event.app.exit(result=template_list[2])+ @prompt.register_kb('4')+ def _(event):+ event.app.exit(result=template_list[3])++ @prompt.register_kb('5')+ def _(event):+ event.app.exit(result=template_list[4])+template = prompt.execute()# Handle user cancellation (Ctrl+C)@@ -174,18 +270,27 @@ def main(# Template is guaranteed to be set at this point (either from option or prompt)assert template is not None+ # Create template directory+ template_dir = Path.cwd() / template+ if template_dir.exists() and not force:+ console.print(f'[yellow]⚠[/yellow] Directory already exists: [cyan]{template_dir}[/cyan]')+ if not click.confirm('Continue and overwrite files?', default=False):+ console.print('[red]✗[/red] Cancelled')+ sys.exit(1)++ # Create directory+ template_dir.mkdir(parents=True, exist_ok=True)+# Determine output pathif output:- output_path = Path(output)+ output_path = template_dir / Path(output)else:- output_path = Path.cwd() / f'browser_use_{template}.py'+ output_path = template_dir / 'main.py'- # Read template file+ # Read template file (tries GitHub first, falls back to bundled)try:- templates_dir = Path(__file__).parent / 'cli_templates'template_file = INIT_TEMPLATES[template]['file']- template_path = templates_dir / template_file- content = template_path.read_text(encoding='utf-8')+ content = _get_template_content(template_file)except Exception as e:console.print(f'[red]✗[/red] Error reading template: {e}')sys.exit(1)@@ -194,26 +299,148 @@ def main(if _write_init_file(output_path, content, force):console.print(f'\n[green]✓[/green] Created [cyan]{output_path}[/cyan]')+ # Generate additional files for shopping template+ if template == 'shopping':+ # Generate launch_chrome_debug.py+ launcher_path = output_path.parent / 'launch_chrome_debug.py'+ launcher_content = _get_template_content('shopping/launch_chrome_debug.py')+ if _write_init_file(launcher_path, launcher_content, force):+ console.print(f'[green]✓[/green] Created [cyan]{launcher_path.name}[/cyan]')+ # Make executable on Unix systems+ if sys.platform != 'win32':+ import stat++ launcher_path.chmod(launcher_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)++ # Generate pyproject.toml+ pyproject_path = output_path.parent / 'pyproject.toml'+ pyproject_content = _get_template_content('shopping/pyproject.toml.template')+ if _write_init_file(pyproject_path, pyproject_content, force):+ console.print(f'[green]✓[/green] Created [cyan]{pyproject_path.name}[/cyan]')++ # Generate .gitignore+ gitignore_path = output_path.parent / '.gitignore'+ gitignore_content = _get_template_content('gitignore.template')+ if _write_init_file(gitignore_path, gitignore_content, force):+ console.print(f'[green]✓[/green] Created [cyan]{gitignore_path.name}[/cyan]')++ # Generate .env.example+ env_example_path = output_path.parent / '.env.example'+ env_example_content = _get_template_content('shopping/.env.example.template')+ if _write_init_file(env_example_path, env_example_content, force):+ console.print(f'[green]✓[/green] Created [cyan]{env_example_path.name}[/cyan]')++ # Generate README.md+ readme_path = output_path.parent / 'README.md'+ readme_content = _get_template_content('shopping/README.md')+ if _write_init_file(readme_path, readme_content, force):+ console.print(f'[green]✓[/green] Created [cyan]{readme_path.name}[/cyan]')++ elif template == 'job-application':+ # Generate pyproject.toml+ pyproject_path = output_path.parent / 'pyproject.toml'+ pyproject_content = _get_template_content('job-application/pyproject.toml.template')+ if _write_init_file(pyproject_path, pyproject_content, force):+ console.print(f'[green]✓[/green] Created [cyan]{pyproject_path.name}[/cyan]')++ # Generate .gitignore+ gitignore_path = output_path.parent / '.gitignore'+ gitignore_content = _get_template_content('gitignore.template')+ if _write_init_file(gitignore_path, gitignore_content, force):+ console.print(f'[green]✓[/green] Created [cyan]{gitignore_path.name}[/cyan]')++ # Generate .env.example+ env_example_path = output_path.parent / '.env.example'+ env_example_content = _get_template_content('job-application/.env.example.template')+ if _write_init_file(env_example_path, env_example_content, force):+ console.print(f'[green]✓[/green] Created [cyan]{env_example_path.name}[/cyan]')++ # Generate README.md+ readme_path = output_path.parent / 'README.md'+ readme_content = _get_template_content('job-application/README.md')+ if _write_init_file(readme_path, readme_content, force):+ console.print(f'[green]✓[/green] Created [cyan]{readme_path.name}[/cyan]')++ # Copy applicant_data.json+ applicant_data_path = output_path.parent / 'applicant_data.json'+ applicant_data_content = _get_template_content('job-application/applicant_data.json')+ if _write_init_file(applicant_data_path, applicant_data_content, force):+ console.print(f'[green]✓[/green] Created [cyan]{applicant_data_path.name}[/cyan]')++ # Copy example resume PDF (binary file - fetch from GitHub)+ resume_dst = output_path.parent / 'example_resume.pdf'+ if not resume_dst.exists() or force:+ resume_content = _fetch_binary_from_github('job-application/example_resume.pdf')+ if resume_content:+ resume_dst.write_bytes(resume_content)+ console.print(f'[green]✓[/green] Created [cyan]{resume_dst.name}[/cyan]')+ else:+ console.print(f'[yellow]⚠[/yellow] Could not fetch [cyan]{resume_dst.name}[/cyan] from GitHub')+# Create a nice panel for next stepsnext_steps = Text()- next_steps.append('\n1. Install browser-use:\n', style='bold')- next_steps.append(' uv pip install browser-use\n\n', style='dim')- next_steps.append('2. Set up your API key in .env file or environment:\n', style='bold')- next_steps.append(' BROWSER_USE_API_KEY=your-key\n', style='dim')- next_steps.append(' (Get your key at https://cloud.browser-use.com/dashboard/api)\n\n', style='dim italic')- next_steps.append('3. Run your script:\n', style='bold')- next_steps.append(f' python {output_path.name}\n', style='dim')-- console.print(- Panel(- next_steps,- title='[bold]Next steps[/bold]',- border_style='#fe750e',- padding=(1, 2),++ if template == 'shopping':+ # Shopping template has different workflow (no uv init needed)+ next_steps.append('\n1. Navigate to project directory:\n', style='bold')+ next_steps.append(f' cd {template}\n\n', style='dim')+ next_steps.append('2. Set up your API key:\n', style='bold')+ next_steps.append(' cp .env.example .env\n', style='dim')+ next_steps.append(' # Edit .env and add your BROWSER_USE_API_KEY\n', style='dim')+ next_steps.append(+ ' (Get your key at https://cloud.browser-use.com/dashboard/settings?tab=api-keys&new)\n\n',+ style='dim italic',)+ next_steps.append('3. Install dependencies:\n', style='bold')+ next_steps.append(' uv sync\n\n', style='dim')+ next_steps.append('4. Launch Chrome with debugging (in a separate terminal):\n', style='bold')+ next_steps.append(' python launch_chrome_debug.py\n', style='dim')+ next_steps.append(' (Run with --help to see options like --profile)\n', style='dim italic')+ next_steps.append(' (Keep this terminal open!)\n\n', style='dim italic')+ next_steps.append('5. Run your script (in a NEW terminal):\n', style='bold')+ next_steps.append(f' cd {template} && uv run {output_path.name}\n\n', style='dim')+ next_steps.append('📖 See README.md for detailed instructions\n', style='dim italic')+ elif template == 'job-application':+ # Job application template workflow+ next_steps.append('\n1. Navigate to project directory:\n', style='bold')+ next_steps.append(f' cd {template}\n\n', style='dim')+ next_steps.append('2. Set up your API key:\n', style='bold')+ next_steps.append(' cp .env.example .env\n', style='dim')+ next_steps.append(' # Edit .env and add your OPENAI_API_KEY\n', style='dim')+ next_steps.append(' (Get your key at https://platform.openai.com/api-keys)\n\n', style='dim italic')+ next_steps.append('3. Install dependencies:\n', style='bold')+ next_steps.append(' uv sync\n\n', style='dim')+ next_steps.append('4. Customize your data:\n', style='bold')+ next_steps.append(' # Edit applicant_data.json with your information\n', style='dim')+ next_steps.append(' # Replace example_resume.pdf with your resume\n\n', style='dim')+ next_steps.append('5. Run the application:\n', style='bold')+ next_steps.append(f' uv run {output_path.name} --resume example_resume.pdf\n\n', style='dim')+ next_steps.append('📖 See README.md for customization and troubleshooting\n', style='dim italic')+ else:+ # Default workflow for other templates+ next_steps.append('\n1. Navigate to project directory:\n', style='bold')+ next_steps.append(f' cd {template}\n\n', style='dim')+ next_steps.append('2. Initialize uv project:\n', style='bold')+ next_steps.append(' uv init\n\n', style='dim')+ next_steps.append('3. Install browser-use:\n', style='bold')+ next_steps.append(' uv add browser-use\n\n', style='dim')+ next_steps.append('4. Set up your API key in .env file or environment:\n', style='bold')+ next_steps.append(' BROWSER_USE_API_KEY=your-key\n', style='dim')+ next_steps.append(+ ' (Get your key at https://cloud.browser-use.com/dashboard/settings?tab=api-keys&new)\n\n',+ style='dim italic',+ )+ next_steps.append('5. Run your script:\n', style='bold')+ next_steps.append(f' uv run {output_path.name}\n', style='dim')++ console.print(+ Panel(+ next_steps,+ title='[bold]Next steps[/bold]',+ border_style='#fe750e',+ padding=(1, 2),)- else:- sys.exit(1)+ )if __name__ == '__main__':