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:
- Initial Navigation: Launch browser session and navigate to target URL
- Element Discovery: Generate interactive element snapshot with reference identifiers
- Targeted Interactions: Execute user actions using element references
- 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_SESSIONenvironment variable - Profile Persistence: Store configuration and state data via the
AGENT_BROWSER_PROFILEenvironment 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:
- Element Identification: Utilize CSS selectors and XPath expressions for precise element targeting
- Event Handling: Implement comprehensive event listeners for user interactions
- Data Synchronization: Maintain consistency between browser state and external systems
- 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 "user@example.com"
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