Getting Started with AgentCore Browser

The following sections show how you can get started with the AgentCore Browser tool.

Prerequisites

Before using the Browser Tool, ensure you meet the following requirements:

• You have an active AWS account with access to Amazon Bedrock AgentCore

• Your network allows secure WebSocket connections

Quick start

The following example demonstrates how to start a remote browser session, interact with it programmatically using Playwright, and observe the session in real time via Live View.

In this setup, Playwright is used to drive the browser automation. Simultaneously, clients can watch the browser's behavior in Live View as Playwright executes tasks. There are two primary ways to connect to the remote browser:

• Automation endpoint – Enables agents to interact with the browser programmatically using automation frameworks like Playwright

• Live View stream – Allows human users to watch the agent's interaction with the browser in real time and optionally take control for manual input.

You can set up the Browser Tool quickly by installing and using the Amazon Bedrock AgentCore SDK.

# Clone the SDK examples repository
git clone https://github.com/awslabs/amazon-bedrock-agentcore-samples.git

# Follow the README instructions to install dependencies
cd amazon-bedrock-agentcore-samples
pip install -r requirements.txt

# Install a browser automation framework such as Playwright (for Python) 
# to programmatically control and interact with browser
pip install playwright

# For browser visualization, you'll need the BrowserViewerServer component
cd 01-tutorials/05-AgentCore-tools/02-Agent-Core-browser-tool/interactive_tools

After installing the SDK and Playwright, you can start a browser session with the following code:

from playwright.sync_api import sync_playwright, Playwright, BrowserType
from bedrock_agentcore.tools.browser_client import browser_session
from browser_viewer import BrowserViewerServer
import time
from rich.console import Console

console = Console()

def run(playwright: Playwright):
    # Create the browser session and keep it alive
    with browser_session('us-west-2') as client:
        ws_url, headers = client.generate_ws_headers()

        # Start viewer server
        viewer = BrowserViewerServer(client, port=8005)
        viewer_url = viewer.start(open_browser=True)

        # Connect using headers
        chromium: BrowserType = playwright.chromium
        browser = chromium.connect_over_cdp(
            ws_url,
            headers=headers
        )

        context = browser.contexts[0]
        page = context.pages[0]

        try:
            page.goto("https://amazon.com/")
            console.print(page.title())
            # Keep running
            while True:
                time.sleep(120)
        except KeyboardInterrupt:
            console.print("\n\n[yellow]Shutting down...[/yellow]")
            if 'client' in locals():
                client.stop()
                console.print("✅ Browser session terminated")
        except Exception as e:
            console.print(f"\n[red]Error: {e}[/red]")
            import traceback
            traceback.print_exc()

with sync_playwright() as playwright:
    run(playwright)

This example:

• Creates a browser session using the browser_session client

• Retrieve the WebSocket connection details required for automation and live view.

• Start the viewer server, which launches a browser window to display the remote browser session via Live View.

• Connect Playwright to the remote browser via automation endpoint and navigate to Amazon.com.

• Keep the session alive until manually interrupted.

• Handle cleanup gracefully by terminating the session and releasing resources when the program exits.

The BrowserViewerServer component provides a local web server that connects to the remote browser session and displays it in a browser window, allowing you to see and interact with the browser in real-time.