Amazon Bedrock AgentCore Browser Tool Workshop

This project is tailored for the AWS Community event workshop.

Hands-on Workshop: Using Browser-Use SDK with Amazon Bedrock AgentCore Browser Tool to automate browsers with Live View

Table of Contents

1. Overview
2. Architecture
3. Technology Stack
4. Prerequisites
5. Installation
6. Usage
7. Configuration
8. Troubleshooting
9. Contributing
10. License
11. Contact
12. Acknowledgments

Overview

Amazon Bedrock AgentCore Browser Tool provides AI agents with a secure, fully managed way to interact with websites just like humans do. It allows agents to navigate web pages, fill out forms, and complete complex tasks without requiring developers to write and maintain custom automation scripts.

Key Features

Secure, Managed Web Interaction

Provides AI agents with a secure, fully managed way to interact with websites, allowing navigation, form filling, and complex task completion without requiring custom automation scripts.

Enterprise Security Features

Provides VM-level isolation with 1:1 mapping between user session and browser session, offering enterprise-grade security. Each browser session runs in an isolated sandbox environment to meet enterprise security needs.

Model-Agnostic Integration

Supports various AI models and frameworks while providing natural language abstractions for browser actions through tools like interact(), parse(), and discover(), making it particularly suitable for enterprise environments.

Architecture

How it Works

A browser tool sandbox is a secure execution environment that enables AI agents to safely interact with web browsers. When a user makes a request:

1. LLM Selection: Large Language Model (LLM) selects appropriate tools and translates commands
2. Sandbox Execution: Commands are executed within a controlled sandbox environment containing a headless browser and hosted library server (using tools like Playwright)
3. Security Isolation: Sandbox provides isolation and security by containing web interactions within a restricted space, preventing unauthorized system access
4. Feedback Loop: Agent receives feedback through screenshots and can perform automated tasks while maintaining system security

Workflow in this Workshop

┌─────────────────┐
│  User Prompt    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Browser-Use     │
│ Agent           │
└────────┬────────┘
         │
         ▼
┌─────────────────┐      ┌──────────────────┐
│ Bedrock         │◄─────►│ Live Viewer      │
│ AgentCore       │      │ (DCV Server)     │
│ Browser Tool    │      └──────────────────┘
└─────────────────┘

Technology Stack

• AWS Bedrock AgentCore: Generative AI agents.
• Python 3.11+: Core programming language.
• Browser-Use SDK: Browser automation.
• Playwright: Headless browser control.
• Amazon DCV: Remote visualization.

Prerequisites

System Requirements

• Python: 3.11 or higher
• AWS Account: With access to Amazon Bedrock AgentCore
• AWS Credentials: Properly configured (AWS CLI or environment variables)

AWS Permissions

Your IAM role/user needs the following permissions:

• Access to Amazon Bedrock AgentCore Browser Tool
• See details at: Browser Tool Credentials Configuration

Python Packages

All dependencies are listed in requirements.txt:

• bedrock-agentcore - Amazon Bedrock AgentCore SDK
• browser-use - Browser-Use SDK for browser automation
• boto3 - AWS SDK for Python
• rich - Terminal formatting
• fastapi & uvicorn - Web server for live viewer
• And other packages...

Installation

Step 1: Clone repository

git clone <repository-url>
cd BedrockAgentCore

Step 2: Create virtual environment (recommended)

You can create a virtual environment using one of the following methods:

Method 1: Using uv (Recommended - Faster)

# Install uv (if not already installed)
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Then create venv
uv venv --python 3.13
# Or specify a specific Python version
uv venv --python 3.11

# Activate venv
.venv\Scripts\activate

Note: uv will automatically detect the Python interpreter and create venv faster than standard venv.

Method 2: Using venv (Python standard)

# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux/Mac
python3 -m venv .venv
source .venv/bin/activate

Step 3: Install dependencies

After activating the virtual environment, install the required packages:

# Upgrade pip
pip install --upgrade pip

# Install all dependencies from requirements.txt
pip install --force-reinstall -U -r requirements.txt

Note: If you're using uv, you can install faster:

# Use uv to install (faster than pip)
uv pip install -r requirements.txt

Step 4: Install DCV SDK (Required for Live Viewer)

The Amazon DCV Web Client SDK is required for the live browser viewer. Install it using the automated script:

python install_dcv_sdk.py

This script will:

• Download the DCV SDK from AWS
• Automatically select the UMD build (required for browsers without ES Modules) and install it to static/dcvjs/
• Verify the installation

static/dcvjs/ is generated content and is now ignored via .gitignore. Feel free to delete that directory and re-run the installer at any time.

Manual Installation (Alternative):

If the automated script fails, you can manually install:

1. Download DCV SDK:

   # Download the SDK
   curl -O https://d1uj6qtbmh3dt5.cloudfront.net/webclientsdk/nice-dcv-web-client-sdk-1.9.100-952.zip

2. Extract and copy files:

   # Extract the zip file
   unzip nice-dcv-web-client-sdk-1.9.100-952.zip
   
   # Copy dcvjs-umd contents to static/dcvjs/
   mkdir -p static/dcvjs
   cp -r nice-dcv-web-client-sdk-*/dcvjs-umd/* static/dcvjs/

3. Verify installation:

   # Check that dcv.js exists
   ls -lh static/dcvjs/dcv.js
   # Should show a file > 100KB

Expected Directory Structure:

static/
└── dcvjs/
    ├── dcv.js
    ├── dcv/
    │   ├── broadwayh264decoder-worker.js
    │   ├── jsmpegdecoder-worker.js
    │   ├── lz4decoder-worker.js
    │   └── microphoneprocessor.js
    └── lib/
        ├── broadway/
        ├── jsmpeg/
        └── lz4/

Step 5: Configure AWS Credentials

# Using AWS CLI
aws configure

# Or set environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-west-2

Usage

About the Notebook File

This workshop uses Jupyter Notebook: Bedrock_AgentCore_Browser-use_LiveView.ipynb

The notebook contains:

• Step-by-step detailed instructions
• Code cells to run directly
• Workflow and architecture explanations
• Real-world examples of browser automation

Notebook Structure:

1. Overview & Prerequisites - Introduction and system requirements
2. Installation - Installing dependencies and patching browser-use
3. Main Script - Main code to run browser automation with live view
4. Execution - Instructions for running and viewing results

Method 1: Running from Jupyter Notebook (Recommended)

Step 1: Install Jupyter (if not already installed)

# In the activated virtual environment
pip install jupyter jupyterlab

Step 2: Open Jupyter Notebook

jupyter notebook Bedrock_AgentCore_Browser-use_LiveView.ipynb

Or use JupyterLab (more modern interface):

jupyter lab Bedrock_AgentCore_Browser-use_LiveView.ipynb

Step 3: Run cells in order

1. Cell 1: Install dependencies

   !pip install --force-reinstall -U -r requirements.txt

2. Cell 2: Install DCV SDK (Required for live viewer)

   # This script will download and install the Amazon DCV Web Client SDK
   !python install_dcv_sdk.py

3. Cell 3: Run patch script for browser-use

   # This script will automatically patch browser_use to be compatible with Bedrock AgentCore
   !python patch_browser_use.py

4. Cell 4: Restart kernel (if needed)

   import IPython
   IPython.Application.instance().kernel.do_shutdown(True)

5. Cell 5: Run script with your prompt

   !python live_view_with_browser_use.py --prompt "Search for macbooks on amazon.com and extract the details of the first one"

Step 4: View Live Browser

• Script will automatically open browser viewer at http://localhost:8000
• You can view the browser session running in real-time
• You can control Take/Release control from the web interface

Method 2: Running from Command Line

python live_view_with_browser_use.py --prompt "Your task description here" --region us-west-2

Parameters:

• --prompt (required): Natural language task description
• --region (optional): AWS region, defaults to us-west-2

Examples:

# Search for products on Amazon
python live_view_with_browser_use.py --prompt "Search for macbooks on amazon.com and extract the details of the first one"

# Fill out registration form
python live_view_with_browser_use.py --prompt "Navigate to example.com and fill out the contact form with test data"

# Collect data
python live_view_with_browser_use.py --prompt "Go to news website and extract the top 5 headlines"

Configuration

See Prerequisites and Installation for credential setup. Refer to .env.example (if available) for required environment variables.

Troubleshooting

Error: DCV SDK Not Found

Solution:

• Run the DCV SDK installer: python install_dcv_sdk.py
• Or manually download and install DCV SDK (see Step 4 in Installation section)
• Verify that static/dcvjs/dcv.js exists and is > 100KB in size
• Check that the directory structure matches the expected layout
• If you need to refresh the SDK, simply delete static/dcvjs/ and run python install_dcv_sdk.py again (the folder is ignored by git)

Error: ModuleNotFoundError: No module named 'browser_viewer'

Solution:

• Ensure you have cloned the complete repository, including the interactive_tools directory
• Or create the browser_viewer.py file in the interactive_tools/ directory with the BrowserViewerServer class
• Note: browser_viewer.py should be in the root directory of the project

Error: Browser session timeout

Solution:

• Increase timeout in BrowserProfile (currently 1500 seconds)
• Check network connection and AWS credentials

Error: CDP connection failed

Solution:

• Ensure BrowserClient has been started successfully
• Check WebSocket URL and headers from generate_ws_headers()
• Ensure the patch script has run successfully

Error: AWS Credentials not found

Solution:

# Check credentials
aws sts get-caller-identity

# Or set environment variables
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_DEFAULT_REGION=us-west-2

Live Viewer not opening

Solution:

• Check if port 8000 is already in use
• Manually open browser at http://localhost:8000
• Check firewall settings

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Contact

For support, please create an issue on the repository.

Acknowledgments

• Amazon Bedrock AgentCore team
• Browser-Use community
• Playwright team