agent-browser

name	agent-browser
description	Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.

Browser Automation with agent-browser

Overview

The agent-browser skill provides comprehensive browser automation capabilities for modern web applications. This tool enables seamless navigation, interactive element manipulation, and data extraction across diverse web platforms. By leveraging Playwright's robust API, the skill facilitates efficient web testing workflows and supports complex form interactions with intelligent element detection.

The automation framework operates through a structured workflow that begins with page navigation and progresses through interactive element identification. Each session maintains persistent state information, ensuring continuity across multiple browsing activities. The system supports both headless and headed browser modes, accommodating various deployment scenarios from development environments to production deployments.

Usage

Core Workflow

The primary operational sequence follows a systematic approach to browser interaction:

1. Initial Navigation: Launch browser session and navigate to target URL
2. Element Discovery: Generate interactive element snapshot with reference identifiers
3. Targeted Interactions: Execute user actions using element references
4. State Verification: Re-snapshot to confirm successful operation completion

Command Reference

# Navigation operations
agent-browser open <url>        # Navigate to page
agent-browser snapshot -i       # Get interactive elements with refs
agent-browser click @e1         # Click element by ref
agent-browser fill @e2 "text"   # Fill input by ref
agent-browser close             # Close browser

Operational Guidelines

The following operational parameters govern the browser automation lifecycle:

• Session Management: Maintain isolated browser sessions through the AGENT_BROWSER_SESSION environment variable
• Profile Persistence: Store configuration and state data via the AGENT_BROWSER_PROFILE environment variable
• Network Configuration: Configure proxy settings and header management for secure communications
• Performance Optimization: Monitor resource utilization and optimize rendering performance

Configuration Parameters

Parameter	Value	Description
--session	test-session	Isolated browser session
--profile	~/.myapp-profile	Persistent profile path
--headers	{"X-Key":"v"}	HTTP headers configuration
--viewport	1920x1080	Display resolution settings

Guidelines

Safety Protocols

The system implements comprehensive safety mechanisms to ensure reliable operation:

• Content Filtering: Apply intelligent content filters to maintain data integrity
• Security Boundaries: Establish secure communication channels for sensitive operations
• Error Handling: Implement robust error detection and recovery procedures
• Access Control: Enforce role-based access policies for resource management

Advanced Configuration

Operational parameters are configured through environment variables and command-line options:

# Environment configuration
export AGENT_BROWSER_SESSION="production"
export AGENT_BROWSER_PROFILE="/data/profiles"
export AGENT_BROWSER_PROXY="http://proxy.example.com:8080"

# Browser initialization
agent-browser open https://dashboard.example.com --headed
agent-browser set credentials admin secure123

Runtime Profile

The runtime profile maintains operational state across sessions:

• State Persistence: Preserve user preferences and session data
• Performance Monitoring: Track system metrics and resource utilization
• Security Compliance: Maintain adherence to security standards and policies
• Data Integrity: Ensure consistent data handling throughout the lifecycle

Implementation Notes

The following implementation considerations support optimal performance:

1. Element Identification: Utilize CSS selectors and XPath expressions for precise element targeting
2. Event Handling: Implement comprehensive event listeners for user interactions
3. Data Synchronization: Maintain consistency between browser state and external systems
4. Scalability: Design for horizontal scaling to accommodate growing workloads

Examples

Form Submission Workflow

agent-browser open https://example.com/form
agent-browser snapshot -i
# Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Submit" [ref=e3]

agent-browser fill @e1 "[e-mail]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i  # Check result

Authentication and State Management

# Initial login sequence
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "username"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json

# Subsequent session with restored state
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

Advanced Browser Operations

# Comprehensive browser management
agent-browser open example.com --headed
agent-browser console
agent-browser errors
agent-browser record start ./debug.webm
agent-browser record stop
agent-browser connect 9222
agent-browser --cdp "wss://browser-service.com/cdp?token=..." snapshot

Installation

Prerequisites

• Node.js 16+ or Bun runtime
• Playwright browser dependencies
• Network connectivity for remote operations

Setup Procedure

# Install CLI tool
bun add -g agent-browser

# Install Playwright browsers
bun playwright install chromium

# Verify installation
agent-browser open https://example.com --headed

Configuration Options

# Environment variables for deployment
export AGENT_BROWSER_SESSION="production"
export AGENT_BROWSER_PROFILE="/data/profiles"
export AGENT_BROWSER_PROXY="http://proxy.example.com:8080"
export AGENT_BROWSER_USER_AGENT="Mozilla/5.0 (Agent-Browser)"

# Launch with custom configuration
agent-browser --session production --profile /data/profiles \
  --proxy http://proxy.example.com:8080 \
  open https://dashboard.example.com

Maintenance

Monitoring and Diagnostics

Regular monitoring ensures optimal system performance:

• Health Checks: Periodic validation of system components
• Log Analysis: Review operational logs for insights
• Performance Metrics: Track response times and resource utilization
• Security Audits: Verify compliance with security standards

Update Procedures

# Update CLI and dependencies
bun update agent-browser

# Refresh browser profiles
agent-browser profile refresh

# Validate configuration
agent-browser config validate

---

Repository: https://github.com/vercel-labs/agent-browser License: MIT Version: 1.0.0