# Interact with web applications using Amazon Bedrock AgentCore Browser
The Amazon Bedrock AgentCore Browser provides a secure, isolated browser environment for your agents to interact with web applications. It runs in a containerized environment, keeping web activity separate from your system. It includes security features such as session isolation, built-in observability through live viewing, CloudTrail logging, and session replay capabilities.
![\[Architecture showing the built-in tools offering and Browser and CI tools.\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/browser-tool.png)
The Amazon Bedrock AgentCore Browser provides session-based web browsing with comprehensive observability. The workflow consists of four key steps:
1. **Create a Browser Tool**
You start by creating a Browser Tool enabling web browsing capabilities for your agent to interact with web applications, fill forms, navigate websites, and extract information in a fully managed environment. You can choose between the AWS managed Browser (aws.browser.v1) for quick setup, or create a custom browser with advanced features like session recording, custom network settings, and specific IAM execution roles.
1. **Start a browser session**
Launch isolated sessions with configurable timeouts (default: 15 minutes, maximum: 8 hours). Run multiple sessions simultaneously.
1. **Interact with the browser**
Once a session is started, you can interact with the browser using WebSocket-based streaming APIs. The Automation endpoint enables your agent to perform browser actions such as navigating to websites, clicking elements, filling out forms, taking screenshots, and more. Libraries like Strands, Nova Act, or Playwright can be used to simplify these interactions. Meanwhile, the Live View endpoint allows an end user to watch the browser session in real time and interact with it directly through the live stream.
1. **Monitor and record sessions**
All browser sessions provide built-in observability which includes Live View for real-time monitoring, Session recording (available for custom browsers), and CloudWatch metrics for real-time performance insights. Session recording captures DOM changes, user actions, console logs, and network events. Recorded sessions are stored in your Amazon S3 bucket and can be replayed through the AWS Console for detailed analysis capabilities including video playback, timeline navigation, user action tracking, and comprehensive logs for troubleshooting and optimization.
**Why use remote browsers for agent development?**
A remote browser runs in a separate environment rather than on the local machine. For agent development, remote browsers allow AI agents to interact with the web as humans do. Key capabilities include:
+ Navigate websites, fill forms, click buttons, parse dynamic content
+ Serverless infrastructure that scales automatically
+ Visual understanding through screenshots
+ Human intervention with live interactive view
+ Session isolation for security
+ Complex web application navigation
+ Comprehensive audit capabilities
**Security Features**
The Browser Tool includes several security features to help protect your environment:
+ Isolation: Containerized environment separate from your system
+ Ephemeral sessions: Temporary sessions that reset after each use
+ Automatic termination when time-to-live expires
**Topics**
+ [Get started with AgentCore Browser](browser-quickstart.md)
+ [Fundamentals](browser-resource-session-management.md)
+ [Observability](browser-observability.md)
+ [Features](browser-features.md)
+ [Troubleshoot AgentCore Browser](browser-tool-troubleshooting.md)
# Get started with AgentCore Browser
AgentCore Browser enables your agents to interact with web pages through a managed Chrome browser. In this guide, you’ll create an AI agent that navigates a website and extracts information — in under 5 minutes.
**Topics**
+ [Prerequisites](#browser-prerequisites)
+ [Step 1: Install dependencies](#browser-strands-install)
+ [Step 2: Create your agent](#browser-strands-create)
+ [Step 3: Run the agent](#browser-strands-run)
+ [Step 4: View the browser session live](#browser-strands-live-view)
+ [Find your resources](#browser-find-resources)
+ [Next steps](#browser-next-steps)
+ [Using AgentCore Browser with Nova Act](browser-quickstart-nova-act.md)
+ [Using AgentCore Browser with Playwright](browser-quickstart-playwright.md)
## Prerequisites
Before you start, ensure you have:
+ Python 3.10 or newer ( [python.org/downloads](https://www.python.org/downloads/) )
+ Boto3 installed ( [Boto3 documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) )
+ AWS credentials configured — verify with:
```
aws sts get-caller-identity
```
If this command fails, see [Configuration and credential file settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) in the AWS CLI documentation.
+ Anthropic Claude Sonnet 4.0 model access [enabled](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) in the Amazon Bedrock console
+ AWS Region where Amazon Bedrock AgentCore is available (see [Supported AWS Regions](agentcore-regions.md) )
**IAM permissions**
Attach this policy to your IAM identity. In the IAM Console, find your user or role, choose **Add permissions** > **Create inline policy** , switch to JSON view, and paste:
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "BedrockAgentCoreBrowserFullAccess",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:CreateBrowser",
"bedrock-agentcore:ListBrowsers",
"bedrock-agentcore:GetBrowser",
"bedrock-agentcore:DeleteBrowser",
"bedrock-agentcore:StartBrowserSession",
"bedrock-agentcore:ListBrowserSessions",
"bedrock-agentcore:GetBrowserSession",
"bedrock-agentcore:StopBrowserSession",
"bedrock-agentcore:UpdateBrowserStream",
"bedrock-agentcore:ConnectBrowserAutomationStream",
"bedrock-agentcore:ConnectBrowserLiveViewStream"
],
"Resource": "arn:aws:bedrock-agentcore::++++:browser/*"
},
{
"Sid": "BedrockModelAccess",
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel",
"bedrock:InvokeModelWithResponseStream"
],
"Resource": [
"*"
]
}
]
}
```
**Note**
Replace `` with your actual AWS Region and `` with your AWS account ID.
## Step 1: Install dependencies
```
pip install bedrock-agentcore strands-agents strands-agents-tools playwright nest-asyncio
```
## Step 2: Create your agent
Create a file named `browser_agent.py` :
**Note**
Replace `` with your AWS Region (for example, `us-west-2` ).
```
from strands import Agent
from strands_tools.browser import AgentCoreBrowser
# Initialize the Browser tool
browser_tool = AgentCoreBrowser(region="")
# Create an agent with the Browser tool
agent = Agent(tools=[browser_tool.browser])
# Test the agent with a web search prompt
prompt = "what are the services offered by Bedrock AgentCore? Use the documentation link if needed: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html"
print(f"\n\nPrompt: {prompt}\n\n")
response = agent(prompt)
print("\n\nAgent Response:")
print(response.message["content"][0]["text"])
```
## Step 3: Run the agent
```
python browser_agent.py
```
You should see the agent navigate the website and return details about AgentCore services. If you encounter errors, verify your IAM permissions, model access, and AWS credentials.
## Step 4: View the browser session live
While your agent is running, you can watch it in real-time through the AWS Console:
1. Open the [AgentCore Browser Console](https://us-west-2.console.aws.amazon.com/bedrock-agentcore/builtInTools)
1. Navigate to **Built-in tools** in the left navigation
1. Select the Browser tool (for example, `AgentCore Browser Tool` , or your custom browser)
1. In the **Browser sessions** section, find your active session with status **Ready**
1. In the **Live view / recording** column, click the provided "View live session" URL
The live view provides a real-time video stream with interactive controls to take over or release control from automation.
## Find your resources
After using AgentCore Browser, view your resources in the AWS Console:
| \$1 | Resource | Location |
| --- | --- | --- |
| 1 | Live View | Browser Console > Tool Name > **View live session** |
| 2 | Session Recordings and Replay | Browser Console > Tool Name > **View recording** |
| 3 | Browser Logs | **CloudWatch** > **Log groups** > `/aws/bedrock-agentcore/browser/` |
| 4 | Recording Files | **S3** > Your bucket > `browser-recordings/` prefix |
| 5 | Custom Browsers | **AgentCore Console** > **Built-in tools** > Your custom browser |
| 6 | IAM Roles | **IAM** > **Roles** > Search for your execution role |
## Next steps
Now that you have AgentCore Browser working, explore these advanced features:
+ [Session Recording and Replay](browser-session-recording.md) - Record and replay sessions for debugging
+ [Using AgentCore Browser with Nova Act](browser-quickstart-nova-act.md) and [Using AgentCore Browser with Playwright](browser-quickstart-playwright.md) - Use other frameworks like Nova Act or Playwright
+ [Fundamentals](browser-resource-session-management.md) - Learn about API operations and custom browsers
# Using AgentCore Browser with Nova Act
You can build a browser agent using Nova Act to automate web interactions:
**Step 1: Install dependencies**
Create a project folder (if you have not already):
```
mkdir agentcore-browser-quickstart
cd agentcore-browser-quickstart
python3 -m venv .venv
source .venv/bin/activate
```
**Note**
On Windows, use: `.venv\Scripts\activate`
Install the required packages:
```
pip install bedrock-agentcore nova-act rich boto3
```
These packages provide:
+ `bedrock-agentcore` : The SDK for Amazon Bedrock AgentCore tools including AgentCore Browser
+ `nova-act` : The SDK for Nova Act which includes the model and orchestrator for browser automation
+ `rich` : Library for rich text and beautiful formatting in the terminal
+ `boto3` : AWS SDK for Python (Boto3) to create, configure, and manage AWS services
**Step 2: Get Nova Act API Key**
Navigate to [Nova Act](https://nova.amazon.com/act) page and generate an API key using your amazon.com credentials. (Note this currently works only for US based amazon.com accounts)
Create a file named `nova_act_browser_agent.py` and add the following code:
**Write a browser agent using Nova Act**
The following Python code shows how to write a browser agent using Nova Act. For information about obtaining the API key for Nova Act, see [Amazon Nova Act documentation](https://nova.amazon.com/act).
```
from bedrock_agentcore.tools.browser_client import browser_session
from nova_act import NovaAct
from rich.console import Console
import argparse
import json
import boto3
console = Console()
from boto3.session import Session
boto_session = Session()
region = boto_session.region_name
print("using region", region)
def browser_with_nova_act(prompt, starting_page, nova_act_key, region="us-west-2"):
result = None
with browser_session(region) as client:
ws_url, headers = client.generate_ws_headers()
try:
with NovaAct(
cdp_endpoint_url=ws_url,
cdp_headers=headers,
nova_act_api_key=nova_act_key,
starting_page=starting_page,
) as nova_act:
result = nova_act.act(prompt)
except Exception as e:
console.print(f"NovaAct error: {e}")
finally:
return result
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("--prompt", required=True, help="Browser Search instruction")
parser.add_argument("--starting-page", required=True, help="Starting URL")
parser.add_argument("--nova-act-key", required=True, help="Nova Act API key")
parser.add_argument("--region", default="us-west-2", help="AWS region")
args = parser.parse_args()
result = browser_with_nova_act(
args.prompt, args.starting_page, args.nova_act_key, args.region
)
console.print(f"\n[cyan] Response[/cyan] {result.response}")
console.print(f"\n[bold green]Nova Act Result:[/bold green] {result}")
```
**Step 3: Run the agent**
Execute the script (Replace with your Nova Act API key in the command):
```
python nova_act_browser_agent.py --prompt "What are the common usecases of Bedrock AgentCore?" --starting-page "https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html" --nova-act-key "your-nova-act-API-key"
```
**Expected output**
You should see the agent’s response containing details of the common usecases of Amazon Bedrock AgentCore. The agent navigates the website, performs the search, and extracts the requested information.
If you encounter errors, verify:
+ Your IAM role/user has the correct permissions
+ Your Nova Act API key is correct
+ Your AWS credentials are properly configured
**Step 4: View the browser session live**
While your browser script is running, you can view the session in real-time through the AWS Console:
1. Open the [Amazon Bedrock AgentCore Browser Console](https://us-west-2.console.aws.amazon.com/bedrock-agentcore/builtInTools)
1. Navigate to **Built-in tools** in the left navigation
1. Select the Browser tool (for example, `AgentCore Browser Tool` , or your custom browser)
1. In the **Browser sessions** section, find your active session with status **Ready**
1. In the **Live view / recording** column, click the provided "View live session" URL
1. The live view opens in a new browser window, displaying the real-time browser session
The live view interface provides:
+ Real-time video stream of the browser session
+ Interactive controls to take over or release control from automation
+ Ability to terminate the session
# Using AgentCore Browser with Playwright
You can use the Playwright automation framework with the Browser Tool:
**Step 1: Install dependencies**
Create a project folder (if you didn’t create one before) and install the required packages:
```
mkdir agentcore-browser-quickstart
cd agentcore-browser-quickstart
python3 -m venv .venv
source .venv/bin/activate
```
**Note**
On Windows, use: `.venv\Scripts\activate`
Install the required packages:
```
pip install bedrock-agentcore playwright boto3 nest-asyncio
```
These packages provide:
+ `bedrock-agentcore` : The SDK for Amazon Bedrock AgentCore tools including AgentCore Browser
+ `playwright` : Python library for browser automation
+ `boto3` : AWS SDK for Python (Boto3) to create, configure, and manage AWS services
+ `nest-asyncio` : Allows running asyncio event loops within existing event loops
**Step 2: Control browser with Playwright**
You can use Browser directly without an agent framework or an LLM. This is useful when you want programmatic control over browser automation. Amazon Bedrock AgentCore provides integration with Playwright for browser automation.
**Async Playwright example**
Create a file named `direct_browser_playwright.py` and add the following code:
```
from playwright.async_api import async_playwright, Playwright, BrowserType
from bedrock_agentcore.tools.browser_client import browser_session
import asyncio
async def run(playwright: Playwright):
# Create and maintain a browser session
with browser_session('us-west-2') as client:
# Get WebSocket URL and authentication headers
ws_url, headers = client.generate_ws_headers()
# Connect to the remote browser
chromium: BrowserType = playwright.chromium
browser = await chromium.connect_over_cdp(
ws_url,
headers=headers
)
# Get the browser context and page
context = browser.contexts[0]
page = context.pages[0]
try:
# Navigate to a website
await page.goto("https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html")
# Print the page title
title = await page.title()
print(f"Page title: {title}")
# Keep the session alive for 2 minutes to allow viewing
print("\n\nBrowser session is active. Check the AWS Console for live view.")
await asyncio.sleep(120)
finally:
# Clean up resources
await page.close()
await browser.close()
async def main():
async with async_playwright() as playwright:
await run(playwright)
# Run the async function
if __name__ == "__main__":
asyncio.run(main())
```
**Sync Playwright example with live view**
Alternatively, you can use the sync API with integrated live view server:
```
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
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/")
print(page.title())
time.sleep(120)
finally:
page.close()
browser.close()
with sync_playwright() as playwright:
run(playwright)
```
**Run the script**
Execute either script:
```
python direct_browser_playwright.py
```
**Expected output**
You should see the page title printed (for example, `Page title: What is Amazon Bedrock AgentCore? - Amazon Bedrock AgentCore` ). The script keeps the browser session active for 2 minutes before closing.
Both examples:
+ Create a managed browser session using Amazon Bedrock AgentCore Browser
+ Connect to the remote Chrome browser using Playwright’s Chrome DevTools Protocol (CDP)
+ Navigate to AgentCore documentation and print the page title
+ Keep the session alive for 2 minutes, allowing you to view it in the AWS Console
+ Properly close the browser and clean up resources
# Fundamentals
The following topics show how the Amazon Bedrock AgentCore Browser works and how you can create the resources and manage sessions.
**Topics**
+ [Creating a Browser Tool and starting a session](#browser-create-session)
+ [Resource management](#browser-resource-management)
+ [Using Browser Tool](browser-using-tool.md)
+ [Managing Browser Sessions](browser-managing-sessions.md)
## Creating a Browser Tool and starting a session
1. **Create a Browser Tool**
When configuring a Browser Tool, choose the public network setting, recording configuration for session replay, and permissions through an IAM runtime role that defines what AWS resources the Browser Tool can access.
1. **Start a session**
The Browser Tool uses a session-based model. After creating a Browser Tool, you start a session with a configurable timeout period (default is 15 minutes). Sessions automatically terminate after the timeout period. Multiple sessions can be active simultaneously for a single Browser Tool, with each session maintaining its own state and environment.
1. **Interact with the browser**
Once a session is started, you can interact with the browser using WebSocket-based streaming APIs. The Automation endpoint enables your agent to perform browser actions such as navigating to websites, clicking elements, filling out forms, taking screenshots, and more. Libraries like browser-use or Playwright can be used to simplify these interactions.
Meanwhile, the Live View endpoint allows an end user to watch the browser session in real time and interact with it directly through the live stream.
1. **Stop the session**
When you’re finished using the browser session, you should stop it to release resources and avoid unnecessary charges. Sessions can be stopped manually or will automatically terminate after the configured timeout period.
### Permissions
To use the Amazon Bedrock AgentCore Browser, you need the following permissions in your IAM policy:
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "BedrockAgentCoreInBuiltToolsFullAccess",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:CreateBrowser",
"bedrock-agentcore:ListBrowsers",
"bedrock-agentcore:GetBrowser",
"bedrock-agentcore:DeleteBrowser",
"bedrock-agentcore:StartBrowserSession",
"bedrock-agentcore:ListBrowserSessions",
"bedrock-agentcore:GetBrowserSession",
"bedrock-agentcore:StopBrowserSession",
"bedrock-agentcore:UpdateBrowserStream",
"bedrock-agentcore:ConnectBrowserAutomationStream",
"bedrock-agentcore:ConnectBrowserLiveViewStream"
],
"Resource": "arn:aws:bedrock-agentcore:us-east-1:111122223333:browser/*"
}
]
}
```
If you’re using session recording with S3, the execution role you provide when creating a browser needs the following permissions:
```
{
"Sid": "BedrockAgentCoreBuiltInToolsS3Policy",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:ListMultipartUploadParts",
"s3:AbortMultipartUpload"
],
"Resource": "arn:aws:s3:::example-s3-bucket/example-prefix/*",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{accountId}}"
}
}
}
```
You should also add the following trust policy to the execution role:
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "BedrockAgentCoreBuiltInTools",
"Effect": "Allow",
"Principal": {
"Service": "bedrock-agentcore.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:*"
}
}
}]
}
```
### Browser setup for API operations
Run the following commands to set up your Browser Tool that is common to all control plane and data plane API operations.
```
import boto3
import uuid
REGION = ""
CP_ENDPOINT_URL = f"https://bedrock-agentcore-control.{REGION}.amazonaws.com"
DP_ENDPOINT_URL = f"https://bedrock-agentcore.{REGION}.amazonaws.com"
cp_client = boto3.client(
'bedrock-agentcore-control',
region_name=REGION,
endpoint_url=CP_ENDPOINT_URL
)
dp_client = boto3.client(
'bedrock-agentcore',
region_name=REGION,
endpoint_url=DP_ENDPOINT_URL
)
```
## Resource management
The AgentCore Browser provides two types of resources:
System ARNs
System ARNs are default resources pre-created for ease of use. These ARNs have default configuration with the most restrictive options and are available for all regions where Amazon Bedrock AgentCore is available.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-resource-session-management.html)
Custom ARNs
Custom ARNs allow you to configure a browser tool with your own settings. You can choose the public network setting, recording configuration, security settings, and permissions through an IAM runtime role that defines what AWS resources the browser tool can access.
### Network settings
The AgentCore Browser supports the public network mode. This mode allows the tool to access public internet resources. This option enables integration with external APIs and services.
### Session management
The AgentCore Browser sessions have the following characteristics:
Session timeout
Default: 900 seconds (15 minutes)
Configurable: Can be adjusted when creating sessions, up to 8 hours
Session recording
Browser sessions can be recorded for later review
Recordings include network traffic and console logs
Recordings are stored in an S3 bucket specified during browser creation
Live view
Sessions can be viewed in real-time using the live view feature
Live view is available at: /browser-streams/aws.browser.v1/sessions/ \$1 session\$1id\$1/live-view
Automatic termination
Sessions automatically terminate after the configured timeout period
Multiple sessions
Multiple sessions can be active simultaneously for a single browser tool. Each session maintains its own state and environment. There can be up to a maximum of 500 sessions.
Retention policy
The time to live (TTL) retention policy for the session data is 30 days.
#### Using isolated sessions
AgentCore Tools enable isolation of each user session to ensure secure and consistent reuse of context across multiple tool invocations. Session isolation is especially important for AI agent workloads due to their dynamic and multi-step execution patterns.
Each tool session runs in a dedicated microVM with isolated CPU, memory, and filesystem resources. This architecture guarantees that one user’s tool invocation cannot access data from another user’s session. Upon session completion, the microVM is fully terminated, and its memory is sanitized, thereby eliminating any risk of cross-session data leakage.
# Using Browser Tool
## Creating an AgentCore Browser
You can create a Browser Tool using the Amazon Bedrock AgentCore console, AWS CLI, or AWS SDK.
**Example**
1. **To create a Browser Tool using the console**
1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home\$1](https://console.aws.amazon.com/bedrock-agentcore/home#).
1. In the navigation pane, choose **Built-in tools**.
1. Choose **Create browser tool**.
1. Provide a unique **Tool name** and optional **Description**.
1. Under **Network settings** , choose **Public network** which allows access to public internet resources.
1. Under **Session recording** , you can enable recording of browser sessions to an S3 bucket for later review.
1. Under **Permissions** , specify an IAM execution role that defines what AWS resources the Browser Tool can access.
1. Choose **Create**.
1. To create a Browser Tool using the AWS CLI, use the `create-browser` command:
```
aws bedrock-agentcore-control create-browser \
--region \
--name "my-browser" \
--description "My browser for web interaction" \
--network-configuration '{
"networkMode": "PUBLIC"
}' \
--recording '{
"enabled": true,
"s3Location": {
"bucket": "my-bucket-name",
"prefix": "sessionreplay"
}
}' \
--execution-role-arn "arn:aws:iam::123456789012:role/my-execution-role"
```
1. To create a Browser Tool using the AWS SDK for Python (Boto3), use the `create_browser` method:
**Request Syntax**
The following shows the request syntax:
```
response = cp_client.create_browser(
name="my_custom_browser",
description="Test browser for development",
networkConfiguration={
"networkMode": "PUBLIC"
},
executionRoleArn="arn:aws:iam::123456789012:role/Sessionreplay",
clientToken=str(uuid.uuid4()),
recording={
"enabled": True,
"s3Location": {
"bucket": "session-record-123456789012",
"prefix": "replay-data"
}
}
)
```
1. To create a new browser instance using the API, use the following call:
```
# Using awscurl
awscurl -X PUT \
"https://bedrock-agentcore-control..amazonaws.com/browsers" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region \
-d '{
"name": "test_browser_1",
"description": "Test sandbox for development",
"networkConfiguration": {
"networkMode": "PUBLIC"
},
"recording": {
"enabled": true,
"s3Location": {
"bucket": "",
"prefix": "sessionreplay"
}
},
"executionRoleArn": "arn:aws:iam::123456789012:role/my-execution-role"
}'
```
## Get AgentCore Browser tool
You can get information about the Browser tool in your account and view their details, status, and configurations.
**Example**
1. **To get information about the Browser tool using the console**
1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home\$1](https://console.aws.amazon.com/bedrock-agentcore/home#).
1. In the navigation pane, choose **Built-in tools**.
1. The browser tools are listed in the **Browser tools** section.
1. You can choose a tool that you created to view it’s details such as name, ID, status, and creation date for each browser tool.
1. To get information about a Browser tool using the AWS CLI, use the `get-browser` command:
```
aws bedrock-agentcore-control get-browser \
--region \
--browser-id ""
```
1. To get information about the Browser tool using the AWS SDK for Python (Boto3), use the `get_browser` method:
**Request Syntax**
The following shows the request syntax:
```
response = cp_client.get_browser(
browserId=""
)
```
1. To get the browser tool using the API, use the following call:
```
# Using awscurl
awscurl -X GET \
"https://bedrock-agentcore-control..amazonaws.com/browsers/" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region
```
## Listing AgentCore Browser tools
You can list all browser tools in your account to view their details, status, and configurations.
**Example**
1. **To list browser tools using the console**
1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home\$1](https://console.aws.amazon.com/bedrock-agentcore/home#).
1. In the navigation pane, choose **Built-in tools**.
1. The browser tools are listed in the **Browser tools** section.
1. You can view details such as name, ID, status, and creation date for each browser tool.
1. To list browser tools using the AWS CLI, use the `list-browsers` command:
```
aws bedrock-agentcore-control list-browsers \
--region
```
You can filter the results by type:
```
aws bedrock-agentcore-control list-browsers \
--region \
--type SYSTEM
```
You can also limit the number of results and use pagination:
```
aws bedrock-agentcore-control list-browsers \
--region \
--max-results 10 \
--next-token ""
```
1. To list browser tools using the AWS SDK for Python (Boto3), use the `list_browsers` method:
**Request Syntax**
The following shows the request syntax:
```
response = cp_client.list_browsers(type="CUSTOM")
```
1. To list browser tools using the API, use the following call:
```
# Using awscurl
awscurl -X POST \
"https://bedrock-agentcore-control..amazonaws.com/browsers" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region
```
You can filter the results by type:
```
awscurl -X POST \
"https://bedrock-agentcore-control..amazonaws.com/browsers?type=SYSTEM" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region
```
You can also limit the number of results and use pagination:
```
awscurl -X POST \
"https://bedrock-agentcore-control..amazonaws.com/browsers?maxResults=1&nextToken=" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region
```
## Deleting an AgentCore Browser
When you no longer need a browser tool, you can delete it to free up resources. Before deleting a browser tool, make sure to stop all active sessions associated with it.
**Example**
1. **To delete a Browser tool using the console**
1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home\$1](https://console.aws.amazon.com/bedrock-agentcore/home#).
1. Navigate to **Built-in tools** and select your browser tool.
1. Choose **Delete** from the **Actions** menu.
1. Confirm the deletion by typing the browser tool name in the confirmation dialog.
1. Choose **Delete**.
**Note**
You cannot delete a browser tool that has active sessions. Stop all sessions before attempting to delete the tool.
1. To delete a Browser tool using the AWS CLI, use the `delete-browser` command:
```
aws bedrock-agentcore-control delete-browser \
--region \
--browser-id ""
```
1. To delete a Browser tool using the AWS SDK for Python (Boto3), use the `delete_browser` method:
**Request Syntax**
The following shows the request syntax:
```
response = cp_client.delete_browser(
browserId=""
)
```
1. To delete a browser tool using the API, use the following call:
```
# Using awscurl
awscurl -X DELETE \
"https://bedrock-agentcore-control..amazonaws.com/browsers/" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore-control \
--region
```
# Managing Browser Sessions
## Starting a browser session
After creating a browser, you can start a session to interact with web applications.
**Example**
1. To start a Browser session using the AWS CLI, use the `start-browser-session` command:
```
aws bedrock-agentcore start-browser-session \
--region \
--browser-identifier "my-browser" \
--name "my-browser-session" \
--session-timeout-seconds 900 \
--view-port width=1456,height=819
```
1. To start a Browser session using the AWS SDK for Python (Boto3), use the `start_browser_session` method:
**Request Syntax**
The following shows the request syntax:
```
response = dp_client.start_browser_session(
browserIdentifier="aws.browser.v1",
name="browser-session-1",
sessionTimeoutSeconds=3600,
viewPort={
'height': 819,
'width': 1456
}
)
```
1. To start a browser session using the BrowserClient class for more control over the session lifecycle:
```
from bedrock_agentcore.tools.browser_client import BrowserClient
# Create a browser client
client = BrowserClient(region="us-west-2")
# Start a browser session
client.start()
print(f"Session ID: {client.session_id}")
try:
# Generate WebSocket URL and headers
url, headers = client.generate_ws_headers()
# Perform browser operations with your preferred automation tool
finally:
# Always close the session when done
client.stop()
```
1. To create a new browser session using the API, use the following call:
```
# Using awscurl
awscurl -X PUT \
"https://bedrock-agentcore..amazonaws.com/browsers/aws.browser.v1/sessions/start" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region \
-d '{
"name": "browser-session-abc12345",
"description": "browser sandbox session",
"sessionTimeoutSeconds": 300,
"viewPort": {
"height": 819,
"width": 1456
}
}'
```
## Get Browser session
You can get information about a browser session that you have created.
**Example**
1. To get information about a browser session using the AWS CLI, use the `get-browser-session` command:
```
aws bedrock-agentcore get-browser-session \
--region \
--browser-identifier "aws.browser.v1" \
--session-id ""
```
1. To get information about a browser session using the AWS SDK for Python (Boto3), use the `get_browser_session` method:
**Request Syntax**
The following shows the request syntax:
```
response = dp_client.get_browser_session(
browserIdentifier="aws.browser.v1",
sessionId=""
)
```
1. To get information about a browser session using the API, use the following call:
```
# Using awscurl
awscurl -X GET \
"https://bedrock-agentcore..amazonaws.com/browsers/aws.browser.v1/sessions/get?sessionId=" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region
{
"browserIdentifier": "aws.browser.v1",
"createdAt": "2025-07-14T22:16:40.713152248Z",
"lastUpdatedAt": "2025-07-14T22:16:40.713152248Z",
"name": "testBrowserSession1752531400",
"sessionId": "",
"sessionReplayArtifact": null,
"sessionTimeoutSeconds": 900,
"status": "TERMINATED",
"streams": {
"automationStream": {
"streamEndpoint": "wss://bedrock-agentcore..amazonaws.com/browser-streams/aws.browser.v1/sessions//automation",
"streamStatus": "ENABLED"
},
"liveViewStream": {
"streamEndpoint": "https://bedrock-agentcore..amazonaws.com/browser-streams/aws.browser.v1/sessions//live-view"
}
},
"viewPort": {
"height": 819,
"width": 1456
}
}
```
## Interacting with a browser session
Once you have started a Browser session, you can interact with it using the WebSocket API. You can also use the InvokeBrowser API for direct operating system-level control, including mouse clicks, keyboard input, and full-screen screenshots. For more information, see [Browser OS action](browser-invoke.md).
**Example**
1. ====== To interact with a Browser session using the console
1. Navigate to your active Browser session.
1. Use the browser interface to navigate to websites, interact with web elements, and perform other browser actions.
1. You can view the browser activity in real-time through the live view feature.
1. To interact with a Browser session programmatically, use the WebSocket-based streaming API with the following URL format:
```
https://bedrock-agentcore..amazonaws.com/browser-streams/{browser_id}/sessions/{session_id}/automation
```
You can use libraries like Playwright to establish a connection with the WebSocket and control the browser. Here’s an example:
```
from playwright.sync_api import sync_playwright, Playwright, BrowserType
import os
import base64
from bedrock_agentcore.tools.browser_client import browser_session
def main(playwright: Playwright):
# Keep browser session alive during usage
with browser_session('us-west-2') as client:
# Generate CDP endpoint and headers
ws_url, headers = client.generate_ws_headers()
# Connect to browser using headers
chromium: BrowserType = playwright.chromium
browser = chromium.connect_over_cdp(ws_url, headers=headers)
# Use the first available context or create one
context = browser.contexts[0] if browser.contexts else browser.new_context()
page = context.pages[0] if context.pages else context.new_page()
page.goto("https://amazon.com/")
print("Navigated to Amazon")
# Create CDP session for screenshot
cdp_client = context.new_cdp_session(page)
screenshot_data = cdp_client.send("Page.captureScreenshot", {
"format": "jpeg",
"quality": 80,
"captureBeyondViewport": True
})
# Decode and save screenshot
image_data = base64.b64decode(screenshot_data['data'])
with open("screenshot.jpeg", "wb") as f:
f.write(image_data)
print("✅ Screenshot saved as screenshot.jpeg")
page.close()
browser.close()
with sync_playwright() as p:
main(p)
```
The following example code shows how you can perform live view using the WebSocket-based streaming API.
```
https://bedrock-agentcore..amazonaws.com/browser-streams/{browser_id}/sessions/{session_id}/live-view
```
Below is the code.
```
import time
from rich.console import Console
from bedrock_agentcore.tools.browser_client import browser_session
from browser_viewer import BrowserViewerServer
console = Console()
def main():
try:
# Step 1: Create browser session
with browser_session('us-west-2') as client:
print("\r ✅ Browser ready! ")
ws_url, headers = client.generate_ws_headers()
# Step 2: Start viewer server
console.print("\n[cyan]Step 3: Starting viewer server...[/cyan]")
viewer = BrowserViewerServer(client, port=8005)
viewer_url = viewer.start(open_browser=True)
# Keep running
while True:
time.sleep(1)
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()
if __name__ == "__main__":
main()
```
## Listing browser sessions
You can list all active browser sessions to monitor and manage your resources. This is useful for tracking active sessions, identifying long-running sessions, or finding sessions that need to be stopped.
**Example**
1. To list Browser sessions using the AWS CLI, use the `list-browser-sessions` command:
```
aws bedrock-agentcore list-browser-sessions \
--region \
--browser-id "" \
--max-results 10
```
You can also filter sessions by status:
```
aws bedrock-agentcore list-browser-sessions \
--region \
--browser-id "" \
--status "READY"
```
1. To list Browser sessions using the AWS SDK for Python (Boto3), use the `list_browser_sessions` method:
**Request Syntax**
The following shows the request syntax:
```
response = dp_client.list_browser_sessions(
browserIdentifier="aws.browser.v1"
)
```
You can also filter sessions by status:
```
# List only active sessions
filtered_response = dp_client.list_browser_sessions(
browserIdentifier="aws.browser.v1",
status="READY"
)
# Print filtered session information
for session in filtered_response['items']:
print(f"Ready Session ID: {session['sessionId']}")
print(f"Name: {session['name']}")
print("---")
```
1. To list browser sessions using the API, use the following call:
```
# Using awscurl
awscurl -X POST \
"https://bedrock-agentcore..amazonaws.com/browsers//sessions/list" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region \
-d '{
"maxResults": 10
}'
```
You can also filter sessions by status:
```
# Using awscurl
awscurl -X POST \
"https://bedrock-agentcore..amazonaws.com/browsers/aws.browser.v1/sessions/list" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region \
-d '{
"maxResults": 10,
"status": "READY"
}'
```
## Stopping a browser session
When you are finished using a Browser session, you should stop it to release resources and avoid unnecessary charges.
**Example**
1. To stop a Browser session using the AWS CLI, use the `stop-browser-session` command:
```
aws bedrock-agentcore stop-browser-session \
--region \
--browser-id "" \
--session-id ""
```
1. To stop a Browser session using the AWS SDK for Python (Boto3), use the `stop_browser_session` method:
**Request Syntax**
The following shows the request syntax:
```
response = dp_client.stop_browser_session(
browserIdentifier="aws.browser.v1",
sessionId="",
)
```
1. To stop a browser session using the API, use the following call:
```
# Using awscurl
awscurl -X PUT \
"https://bedrock-agentcore..amazonaws.com/browsers/aws.browser.v1/sessions/stop?sessionId=" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region
```
## Updating browser streams
You can update browser streams to enable or disable automation. This is useful when you need to enter sensitive information like login credentials that you don’t want the agent to see.
**Example**
1.
```
response = dp_client.update_browser_stream(
browserIdentifier="aws.browser.v1",
sessionId="",
streamUpdate={
"automationStreamUpdate": {
"streamStatus": "DISABLED" # or "ENABLED"
}
}
)
```
1.
```
awscurl -X PUT \
"https://bedrock-agentcore..amazonaws.com/browsers/aws.browser.v1/sessions/streams/update?sessionId=" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region \
-d '{
"streamUpdate": {
"automationStreamUpdate": {
"streamStatus": "ENABLED"
}
}
}'
```
1.
```
aws bedrock-agentcore update-browser-stream \
--region \
--browser-id "" \
--session-id "" \
--stream-update automationStreamUpdate={streamStatus=ENABLED}
```
# Observability
The Amazon Bedrock AgentCore Browser provides built-in observability features including live view, session recording, session replay, and CloudWatch metrics.
**Topics**
+ [Live View](browser-dcv-integration.md)
+ [Session Recording and Replay](browser-session-recording.md)
+ [CloudWatch Metrics](browser-metrics.md)
# Live View
Amazon Bedrock AgentCore’s Live View is powered by [AWS DCV](https://docs.aws.amazon.com/dcv/). Each browser session launches a dedicated DCV server that streams the browser interface and enables real-time user interaction.
To embed the Live View into your web application, use the BrowserLiveView React component from the [Amazon Bedrock AgentCore TypeScript SDK](https://github.com/aws/bedrock-agentcore-sdk-typescript). The component wraps the [AWS DCV Web Client](https://docs.aws.amazon.com/dcv/latest/websdkguide/what-is.html) internally and handles connection setup, SigV4 authentication, and video rendering, so you can integrate a live browser stream with minimal code while retaining full control over your UI.
## Using the BrowserLiveView component
The BrowserLiveView component requires a SigV4-presigned Live View URL. After starting a browser session (see [Managing browser sessions](browser-managing-sessions.md)), generate the presigned URL using the [generateLiveViewUrl](https://github.com/aws/bedrock-agentcore-sdk-typescript/blob/main/src/tools/browser/client.ts#L380) method from the TypeScript SDK’s Browser class. The method signs the Live View stream endpoint with SigV4 credentials and returns a time-limited URL that you pass to the BrowserLiveView component.
Install the Amazon Bedrock AgentCore TypeScript SDK:
```
npm install bedrock-agentcore
```
Import the BrowserLiveView component and render it with the presigned URL. The component handles WebSocket connection, DCV protocol negotiation, video stream decoding, and frame rendering. It auto-scales to fit its parent container while preserving aspect ratio.
```
import { BrowserLiveView }
from 'bedrock-agentcore/browser/live-view'
```
The remoteWidth and remoteHeight must match the viewport configured for the browser session. Mismatched values cause cropping or black bars.
The Live View begins streaming as soon as the presigned URL is valid and the browser session is active. If the container remains empty, verify that the presigned URL has not expired and that the browser session is still running.
For a complete walkthrough including a sample React application, see [Embed a live AI browser agent in your React app with Amazon Bedrock AgentCore](https://aws.amazon.com/blogs/machine-learning/embed-a-live-ai-browser-agent-in-your-react-app-with-amazon-bedrock-agentcore/).
# Session Recording and Replay
Browser session recording and replay provides comprehensive observability for debugging, auditing, or training purposes. When you create a browser with session recording enabled, Amazon Bedrock AgentCore automatically captures browser interactions and stores them in your specified Amazon S3 bucket for later analysis.
Session replay captures comprehensive browser interaction data that enables you to view replays and understand the actions that occurred during browser sessions. This functionality helps you resolve errors and improve future invocations by providing detailed insights into browser behavior.
Information collected during session replay includes:
+ Session DOM changes and mutations
+ User actions including clicks, scrolls, and form interactions
+ Console logs and error messages
+ Chrome DevTools Protocol (CDP) events
+ Network events and HTTP requests
## Prerequisites for session recording
To enable session recording, you need:
+ An Amazon S3 bucket to store recording data
+ An IAM execution role with permissions to write to your Amazon S3 bucket
+ A custom browser tool configured with recording enabled
## Configure IAM role for recording
To enable session recording, you need an IAM execution role with permissions to write recording data to Amazon S3 and log activity to CloudWatch. For detailed instructions on setting up permissions, see [Permissions](browser-resource-session-management.md#browser-permissions).
The execution role requires additional permissions beyond the standard browser permissions:
```
{
"Sid": "S3Permissions",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListBucket",
"s3:ListMultipartUploadParts",
"s3:AbortMultipartUpload"
],
"Resource": [
"arn:aws:s3:::your-recording-bucket",
"arn:aws:s3:::your-recording-bucket/*"
]
},
{
"Sid": "CloudWatchLogsPermissions",
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams"
],
"Resource": "*"
}
```
Replace `your-recording-bucket` with your actual Amazon S3 bucket name.
## Step 1: Create a browser tool with recording
Create a custom browser tool with recording enabled. For detailed instructions on creating browser tools, see [Creating an AgentCore Browser](browser-using-tool.md#browser-create).
When creating your browser tool, ensure you:
+ Enable session recording in the configuration
+ Specify your Amazon S3 bucket and prefix for storing recordings
+ Use the IAM execution role from Step 1
Example using Python SDK:
```
import boto3
import uuid
region = "us-west-2"
bucket = "your-recording-bucket"
client = boto3.client("bedrock-agentcore-control", region_name=region)
response = client.create_browser(
name="MyRecordingBrowser",
description="Browser with session recording enabled",
networkConfiguration={"networkMode": "PUBLIC"},
executionRoleArn="arn:aws:iam::123456789012:role/AgentCoreBrowserRecordingRole",
clientToken=str(uuid.uuid4()),
recording={
"enabled": True,
"s3Location": {
"bucket": bucket,
"prefix": "browser-recordings"
}
}
)
browser_identifier = response.get("browserId") or response.get("browserIdentifier")
print(f"Created browser with recording: {browser_identifier}")
print(f"Recordings will be stored at: s3://{bucket}/browser-recordings/")
```
## Step 2: Use the recording-enabled browser
Use your recording-enabled browser with any automation framework. All browser interactions will be automatically recorded. Example using Strands:
```
from strands import Agent
from strands_tools.browser import AgentCoreBrowser
# Use the browser created with recording
browser_identifier = "your-browser-identifier"
region = "us-west-2"
browser_tool = AgentCoreBrowser(region=region, identifier=browser_identifier)
agent = Agent(tools=[browser_tool.browser])
prompt = (
"Navigate to https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html "
"and summarize the key features of AgentCore."
)
response = agent(prompt)
print("Agent Response:")
print(response.message["content"][0]["text"])
```
All interactions during this session will be automatically recorded and uploaded to your Amazon S3 bucket when the session ends.
## Step 3: Monitor live sessions and replay recordings
The AWS Console provides comprehensive tools for both real-time monitoring and recorded session analysis.
### Live view monitoring
Monitor browser sessions in real-time and interact with active sessions:
**To access live view in the console**
1. Open the Amazon Bedrock AgentCore console and navigate to **Built-in tools**
1. Select your browser tool from the list (for example, `MyRecordingBrowser` )
1. In the **Browser sessions** section, locate an active session with status **Ready** or **In progress**
1. In the **Live view / recording** column, click the provided "View live session" URL
1. The live view opens in a new browser window, displaying the real-time browser session
The live view interface provides:
+ Real-time video stream of the browser session
+ Interactive controls to take over or release control from automation
+ Session status indicators and connection information
+ Ability to interact directly with the browser when control is enabled
### Session replay and analysis
Access detailed session recordings and analysis through the console replay interface:
**To access session replay in the console**
1. Navigate to your browser tool and select a completed session with **Terminated** status
1. Click **View Recording** for the session you want to analyze
1. The session replay page displays with comprehensive analysis tools
**Session analysis features**
The console provides multiple analysis tools:
+ **Video Player** : Interactive playback with timeline scrubber for navigation
+ **Pages Navigation** : Panel showing all visited pages with time ranges
+ **User Actions** : All user interactions with timestamps, methods, and details
+ **Page DOM** : DOM structure and HTML content for each page
+ **Console Logs** : Browser console output, errors, and log messages
+ **CDP Events** : Chrome DevTools Protocol events with parameters and results
+ **Network Events** : HTTP requests, responses, status codes, and timing
**Navigate recordings**
Use these methods to navigate through recordings:
+ Click on pages in the Pages panel to jump to specific moments
+ Click on user actions to see where they occurred in the timeline
+ Use the video timeline scrubber for precise navigation
+ Choose **View recording** links in action tables to jump to specific interactions
## Step 4: Access recordings programmatically
Access live view and recording insights programmatically using the Amazon Bedrock AgentCore SDK and APIs for custom integration and automated analysis.
### Programmatic live view access
Connect to live browser sessions using the browser client and viewer server:
```
import time
from rich.console import Console
from bedrock_agentcore.tools.browser_client import browser_session
from browser_viewer import BrowserViewerServer
console = Console()
def main():
try:
# Create browser session
with browser_session('us-west-2') as client:
print("✅ Browser ready!")
ws_url, headers = client.generate_ws_headers()
# Start viewer server
console.print("[cyan]Starting viewer server...[/cyan]")
viewer = BrowserViewerServer(client, port=8005)
viewer_url = viewer.start(open_browser=True)
# Keep running
while True:
time.sleep(1)
except KeyboardInterrupt:
console.print("[yellow]Shutting down...[/yellow]")
if 'client' in locals():
client.stop()
console.print("✅ Browser session terminated")
if __name__ == "__main__":
main()
```
### Programmatic recording access
Access recording data directly from Amazon S3 for custom analysis workflows:
```
import boto3
s3_client = boto3.client('s3', region_name='us-west-2')
# List recordings in your bucket
bucket_name = "your-recording-bucket"
prefix = "browser-recordings/"
response = s3_client.list_objects_v2(Bucket=bucket_name, Prefix=prefix)
print(f"Recordings in s3://{bucket_name}/{prefix}:")
for obj in response.get('Contents', []):
print(f" {obj['Key']} ({obj['Size']} bytes)")
print(f" Last Modified: {obj['LastModified']}")
print()
```
Recording data structure:
```
s3://your-recording-bucket/browser-recordings/
└── session-id/
├── batch_1.ndjson.gz
├── batch_2.ndjson.gz
└── batch_3.ndjson.gz
```
Each session creates a folder with the session ID, and recording data is uploaded in chunks as the session progresses.
## Session replay programmatic examples
For advanced use cases, you can build custom session replay viewers and integrate recording data into your own analysis workflows.
The following GitHub examples show a standalone session replay viewer and what the complete browser experience looks like when using the browser session replay feature.
For additional examples, see [AgentCore Browser examples on GitHub](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/05-AgentCore-tools/02-Agent-Core-browser-tool/interactive_tools/).
### Standalone Session Replay Viewer
The standalone session replay viewer is a separate tool for viewing recorded browser sessions directly from Amazon S3 without creating a new browser.
+ Connect directly to S3 to view recordings
+ View any past recording by specifying its session ID
+ Display error messages when artifacts are missing from S3, with console replay URLs specific to session ID
+ Interactive video playback interface with timeline navigation
+ Action markers on timeline showing form fills, clicks, and navigation events
+ Observability table displaying pages traveled with duration and URL details
+ Console events, CDP logs, and network logs for each page interaction
+ Session duration tracking integrated at page level
+ Real-time action verification with visual correlation between video and action data
```
# View the latest recording in a bucket
python view_recordings.py --bucket session-record-test-123456789012 --prefix replay-data
# View a specific recording
python view_recordings.py --bucket session-record-test-123456789012 --prefix replay-data --session 01JZVDG02M8MXZY2N7P3PKDQ74
# Use a specific AWS profile
python view_recordings.py --bucket session-record-test-123456789012 --prefix replay-data --profile my-profile
```
For reference, see [Standalone session replay viewer on GitHub](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/05-AgentCore-tools/02-Agent-Core-browser-tool/interactive_tools/live_view_sessionreplay/view_recordings.py).
### Complete Browser Experience with Recording and Replay
A comprehensive tool for creating browser sessions with recording capabilities and advanced replay features.
+ Create browser sessions with automatic recording to S3
+ Live view with interactive control (take/release)
+ Adjust display resolution on the fly
+ Automatic session recording to S3
+ Integrated session replay viewer with video player interface
+ Timeline scrubbing with precise action location tracking
+ Page-by-page analysis with navigation timeline and URL copying
+ Form filling action verification with click location details
+ Session duration tracking integrated at page level
+ Real-time action verification with visual correlation between video and action data
```
# View the latest recording in a bucket
python -m live_view_sessionreplay.browser_interactive_session
```
For reference, see [Interactive browser session on GitHub](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/05-AgentCore-tools/02-Agent-Core-browser-tool/interactive_tools/live_view_sessionreplay/browser_interactive_session.py).
# CloudWatch Metrics
You can view the following metrics in Amazon CloudWatch:
+ Session counts: The number of browser sessions that have been requested
+ Session duration: The length of time browser sessions are active
+ Error rates: The frequency of errors encountered during browser sessions
+ Resource utilization: CPU, memory, and network usage by browser sessions
These metrics can be used to monitor the usage and performance of your browser sessions, set up alarms for abnormal behavior, and optimize your resource allocation.
For more information, see [AgentCore generated built-in tools observability data](observability-tool-metrics.md).
# Features
Amazon Bedrock AgentCore Browser provides advanced features including CAPTCHA reduction, browser extensions, session profiles, proxy configuration, and OS-level interaction.
**Topics**
+ [Reducing CAPTCHAs with Web Bot Auth](browser-web-bot-auth.md)
+ [Using browser extensions](browser-extensions.md)
+ [Using browser profiles](browser-profiles.md)
+ [Using browser proxies](browser-proxies.md)
+ [Using browser enterprise policies](browser-enterprise-policies.md)
+ [Configure Root Certificate Authority for Amazon Bedrock AgentCore Browser](browser-root-ca-certificates.md)
+ [Browser OS action](browser-invoke.md)
# Reducing CAPTCHAs with Web Bot Auth
**Note**
Amazon Bedrock AgentCore Browser Web Bot Auth (Preview) is based on the draft IETF Web Bot Auth protocol, which is subject to change as the specification evolves toward finalization.
\$1 **Current Implementation:**
\$1 \$1 Implementation details, API parameters, and signing mechanisms may change as we align with the finalized protocol specification \$1 WAF provider support and policies vary. Not all websites will recognize or allow signed agent traffic \$1 Domain owners retain full control over their bot policies and may block, monitor, or rate-limit agent traffic regardless of cryptographic signatures
\$1 For the latest protocol specification, see the [IETF draft](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture).
Amazon Bedrock AgentCore Browser reduces CAPTCHA challenges through Web Bot Auth, a draft IETF protocol that cryptographically identifies AI agents to websites and bot control vendors.
## Overview
AI agents frequently encounter anti-bot mechanisms when browsing websites, including CAPTCHA challenges, rate limiting, and request blocking. These security measures are designed to prevent malicious automated traffic but often block legitimate AI agents as well.
Websites implement these defenses because they cannot reliably distinguish between legitimate agents and malicious bots. Traditional identification methods like IP addresses or User-Agent strings can be easily spoofed and do not provide verifiable identity.
Web Bot Auth addresses this challenge by implementing the [IETF HTTP Message Signatures for automated traffic Architecture](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture) draft protocol. This protocol enables AI agents to cryptographically sign their HTTP requests, providing websites with verifiable proof of the agent’s identity.
When Web Bot Auth is enabled, Amazon Bedrock AgentCore Browser automatically signs each HTTP request with a private key and includes verification headers. Bot control vendors (such as Cloudflare, Akamai Technologies, and HUMAN Security) can verify these signatures against public key directories and apply appropriate policies configured by website owners.
This approach provides a standardized method for legitimate automation to identify itself while preserving website owners' control over access policies.
## How it works
Web Bot Auth uses the IETF HTTP Message Signatures standard to cryptographically sign HTTP requests:
1. **Agent Registration** : Amazon Bedrock AgentCore registers with bot control vendors (Cloudflare, reCAPTCHA, etc.) and provides public keys for verification
1. **Request Signing** : When enabled, the Browser Tool automatically signs each HTTP request using a private key
1. **Signature Headers** : Three headers are added to each request:
+ `Signature` : The cryptographic signature
+ `Signature-Agent` : Points to the public key directory for verification
+ `Signature-Input` : Specifies which components were signed
1. **Verification** : The website’s bot control system fetches the public key and verifies the signature to confirm the request comes from Amazon Bedrock AgentCore
1. **Policy Application** : Based on the verified identity, the website can apply appropriate policies. Domain owners can configure their bot control systems to:
+ **Block all traffic** : Reject all automated requests regardless of authentication
+ **Allow only signed bots** : Accept requests only from verified agents with valid Web Bot Auth signatures
+ **Allow signed bots from specific directories** : Permit authenticated agents to access only certain paths or resources on the website
## Enabling Web Bot Auth
To enable Web Bot Auth, you need to configure it when creating a Browser Tool:
**Example**
1. To create a Browser Tool with Web Bot Auth enabled using the AWS CLI:
```
aws bedrock-agentcore-control create-browser \
--region \
--name "my-browser-with-auth" \
--description "Browser with Web Bot Auth enabled" \
--network-configuration '{"networkMode": "PUBLIC"}' \
--execution-role-arn "arn:aws:iam:::role/" \
--browser-signing '{"enabled": true}'
```
1. To create a Browser Tool with Web Bot Auth enabled using Boto3:
```
import boto3
client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = client.create_browser(
name='my-browser-with-auth',
description='Browser with Web Bot Auth enabled',
networkConfiguration={
'networkMode': 'PUBLIC'
},
executionRoleArn='arn:aws:iam:::role/',
browserSigning={
'enabled': True
}
)
```
1. ====== To enable Web Bot Auth in the console
1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home\$1](https://console.aws.amazon.com/bedrock-agentcore/home#).
1. In the navigation pane, choose **Built-in tools**.
1. Choose **Create browser tool**.
1. Provide a unique **Tool name** and optional **Description**.
1. Under **Network settings** , choose **Public network**.
1. In the **Web Bot Auth configuration** section, select the **Use Web Bot Auth** check box.
1. Under **Permissions** , specify an IAM execution role that defines what AWS resources the Browser Tool can access.
1. Configure other browser settings as needed and choose **Create**.
**Important**
Web Bot Auth requires an execution role with a trust policy, but does not require any managed or inline policies. The feature is disabled by default and must be explicitly enabled during browser creation. You should add the following trust policy to the execution role: [source,json,subs="verbatim,attributes"] ---- \$1 "Version":"2012-10-17", "Statement": [\$1 "Sid": "BedrockAgentCoreBuiltInTools", "Effect": "Allow", "Principal": \$1 "Service": "bedrock-agentcore.amazonaws.com" \$1, "Action": "sts:AssumeRole", "Condition": \$1 "StringEquals": \$1 "aws:SourceAccount": "111122223333" \$1, "ArnLike": \$1 "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:\$1" \$1 \$1 \$1] \$1 ----
## Supported Bot Control Vendors
Amazon Bedrock AgentCore currently supports Web Bot Auth with the following bot control vendors:
+ **Cloudflare**
+ **HUMAN Security**
+ **Akamai Technologies**
+ **DataDome**
Additional bot control vendors will be supported as partnerships are established. The authentication works transparently - once enabled, your agents can browse websites protected by these services with reduced friction.
## Considerations
+ **Transparent Operation** : Web Bot Auth works automatically once enabled. No additional code changes are required in your agent applications.
+ **Performance Impact** : Signing requests adds minimal latency to HTTP requests.
+ **Vendor Coverage** : The feature only works with websites that use supported bot control vendors. Websites using other anti-bot solutions may still present challenges.
+ **Policy Dependent** : Even with authentication, website owners control their bot policies. Some sites may still restrict or monitor agent traffic based on their specific requirements.
# Using browser extensions
Browser Extensions allow you to install custom extensions into browser sessions at session creation time. This enables you to customize browser behavior with your own extensions for automation tasks, web scraping, testing, and more.
## Overview
Browser Extensions in Amazon Bedrock AgentCore work as follows:
1. You provide a list of browser extension ZIP files stored in your own Amazon S3 buckets
1. The service validates that you have access to these Amazon S3 objects using your credentials
1. During browser session startup, extensions are downloaded from your Amazon S3 bucket and installed to the browser session
## Prerequisites
Before using browser extensions, ensure you have:
+ Completed the general Browser [Prerequisites](browser-quickstart.md#browser-prerequisites)
+ An Amazon Amazon S3 bucket to store your extension ZIP files
+ IAM permissions to access the Amazon S3 bucket containing your extensions. Add the following permissions to your IAM policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ExtensionS3Access",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3::://*"
]
}
]
}
```
**Note**
The Amazon S3 bucket must be in the same AWS account as the browser session. Extensions have a 10 MB file size limit and a maximum of 10 extensions per session.
## Preparing Extension Files
To prepare an extension for use with Browser Tool:
1. **Create a Chrome Extension**
Your extension should follow the standard Chromium extension format and adhere to [Chromium extension guidelines](https://www.chromium.org/developers/design-documents/extensions/) . Each extension must include a valid `manifest.json` file.
1. **Create a ZIP File**
Zip the extension directory contents (not the parent folder):
```
cd my-extension
zip -r ../my-extension.zip.
```
1. **Upload to S3**
Upload the ZIP file to your Amazon S3 bucket:
```
aws s3 cp my-extension.zip s3://my-extensions-bucket/extensions/my-extension.zip
```
## Creating a browser session with extensions
You can create a browser session with extensions using the AWS CLI, SDK, or API.
**Example**
1. To start a browser session with extensions using the AWS CLI:
```
aws bedrock-agentcore start-browser-session \
--region \
--browser-identifier "aws.browser.v1" \
--name "my-session-with-extensions" \
--session-timeout-seconds 1800 \
--extensions '[
{
"location": {
"s3": {
"bucket": "my-extensions-bucket",
"prefix": "extensions/my-extension.zip"
}
}
}
]'
```
1. To start a browser session with extensions using the AWS SDK for Python (Boto3):
```
import boto3
region = "us-west-2"
client = boto3.client('bedrock-agentcore', region_name=region)
response = client.start_browser_session(
browserIdentifier="aws.browser.v1",
name="my-session-with-extensions",
sessionTimeoutSeconds=1800,
viewPort={
'height': 1080,
'width': 1920
},
extensions=[
{
"location": {
"s3": {
"bucket": "my-extensions-bucket",
"prefix": "extensions/my-extension.zip"
}
}
},
{
"location": {
"s3": {
"bucket": "my-extensions-bucket",
"prefix": "extensions/another-extension.zip",
"versionId": "abc123" # Optional - for versioned S3 buckets
}
}
}
]
)
print(f"Session ID: {response['sessionId']}")
print(f"Status: {response['status']}")
print(f"Automation Stream: {response['streams']['automationStream']['streamEndpoint']}")
```
1. To start a browser session with extensions using the API:
```
# Using awscurl
awscurl -X PUT \
"https://bedrock-agentcore..amazonaws.com/browsers/aws.browser.v1/sessions/start" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region \
-d '{
"name": "my-session-with-extensions",
"sessionTimeoutSeconds": 1800,
"viewPort": {
"height": 1080,
"width": 1920
},
"extensions": [
{
"location": {
"s3": {
"bucket": "my-extensions-bucket",
"prefix": "extensions/my-extension.zip"
}
}
},
{
"location": {
"s3": {
"bucket": "my-extensions-bucket",
"prefix": "extensions/another-extension.zip"
}
}
}
]
}'
```
# Using browser profiles
Browser profiles enable you to persist and reuse browser profile data across multiple browser sessions. A browser profile stores session information including cookies and local storage.
For example, you can authenticate to a website once in a browser session and save the profile data to browser profile resource. When you start a new browser session with that saved profile, your authentication state is preserved, and you remain logged in. This enables agents to perform tasks on authenticated websites without requiring manual intervention.
## Overview
Browser profiles in Amazon Bedrock AgentCore work as follows:
1. Create a browser profile resource that will be reuse across browser sessions
1. Start a browser session and perform actions (such as login a website or put item in shopping cart) that populate cookies and localstorage
1. Save the profile data from current browser session to the browser profile resource
1. Start new browser sessions using the saved profile to restore the previous state
## Prerequisites
Before using browser profiles, ensure you have:
+ Completed the general Browser [Prerequisites](browser-quickstart.md#browser-prerequisites)
+ IAM permissions to manage profile resources. Add the following permissions to your IAM policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "BedrockAgentCoreBrowserProfileManagementAccess",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:CreateBrowserProfile",
"bedrock-agentcore:ListBrowserProfiles",
"bedrock-agentcore:GetBrowserProfile",
"bedrock-agentcore:DeleteBrowserProfile"
],
"Resource": "arn:aws:bedrock-agentcore:::browser-profile/*"
}
]
}
```
+ IAM permissions to save and load profiles. Add the following permissions to your IAM policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "BedrockAgentCoreBrowserProfileUsageAccess",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:StartBrowserSession",
"bedrock-agentcore:SaveBrowserSessionProfile"
],
"Resource": [
"arn:aws:bedrock-agentcore:::browser-profile/*",
"arn:aws:bedrock-agentcore:::browser-custom/*",
"arn:aws:bedrock-agentcore:::browser/*"
]
}
]
}
```
## Getting started with browser profiles
This section walks you through creating a browser profile, saving session data to it, and reusing the profile in subsequent sessions.
### Step 1: Create a browser profile
Create a browser profile resource to store session data.
**Example**
1. To create a browser profile using the AWS CLI:
```
aws bedrock-agentcore-control create-browser-profile \
--region \
--name "profile_demo" \
--description "example profile"
```
1. To create a browser profile using the AWS SDK for Python (Boto3):
```
import boto3
region = "us-west-2"
client = boto3.client('bedrock-agentcore-control', region_name=region)
response = client.create_browser_profile(
name="profile_demo",
description="example profile"
)
profile_id = response['profileId']
print(f"Created profile: {profile_id}")
```
1. To create a browser profile using the API:
```
awscurl -X PUT \
"https://bedrock-agentcore-control..amazonaws.com/browser-profiles" \
-H "Content-Type: application/json" \
--service bedrock-agentcore-control \
--region \
-d '{
"name": "profile_demo",
"description": "example profile",
"clientToken": "FC21DD1F-FA7B-40EC-8D3A-12E029A1BFF3"
}'
```
### Step 2: Start a browser session and perform actions
Start a browser session and perform actions such as login a website. The session state, including cookies and local storage, will be captured.
**Example**
1. To start a browser session using the AWS CLI:
```
aws bedrock-agentcore start-browser-session \
--region \
--browser-identifier "aws.browser.v1" \
--name "my-session" \
--session-timeout-seconds 3600
```
Use the returned session ID to interact with the browser and perform your desired actions (for example, login into a website).
1. To start a browser session using Boto3:
```
import boto3
region = "us-west-2"
client = boto3.client('bedrock-agentcore', region_name=region)
response = client.start_browser_session(
browserIdentifier="aws.browser.v1",
name="my-session",
sessionTimeoutSeconds=3600
)
session_id = response['sessionId']
print(f"Session ID: {session_id}")
# Use the session to perform actions (e.g., login to a website)
# ... your browser automation code here ...
```
1. To start a browser session using the API:
```
awscurl -X PUT \
"https://bedrock-agentcore..amazonaws.com/browsers/aws.browser.v1/sessions/start" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region \
-d '{
"name": "my-session",
"sessionTimeoutSeconds": 3600
}'
```
### Step 3: Save the session to a profile
After performing actions in the browser session, save the current state to your browser profile. This captures cookies, local storage, and other session data.
**Example**
1. To save a browser session to a profile using the AWS CLI:
```
aws bedrock-agentcore save-browser-session-profile \
--region \
--profile-identifier "" \
--browser-identifier "aws.browser.v1" \
--session-id ""
```
1. To save a browser session to a profile using Boto3:
```
import boto3
region = "us-west-2"
client = boto3.client('bedrock-agentcore', region_name=region)
response = client.save_browser_session_profile(
profileIdentifier=profile_id, # From Step 1
browserIdentifier="aws.browser.v1",
sessionId=session_id # From Step 2
)
print(f"Profile saved successfully")
```
1. To save a browser session to a profile using the API:
```
awscurl -X PUT \
"https://bedrock-agentcore..amazonaws.com/browser-profiles//save" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region \
-d '{
"browserIdentifier": "aws.browser.v1",
"sessionId": "",
"clientToken": "52866F95-4468-4B6C-920C-09A00D36F04E"
}'
```
### Step 4: Start a new session with the profile
Start a new browser session using the saved profile. The session will be initialized with the saved state, including authentication cookies and local storage.
**Example**
1. To start a browser session with a profile using the AWS CLI:
```
aws bedrock-agentcore start-browser-session \
--region \
--browser-identifier "aws.browser.v1" \
--name "session-with-profile" \
--session-timeout-seconds 3600 \
--profile-configuration '{
"profileIdentifier":""
}'
```
1. To start a browser session with a profile using Boto3:
```
import boto3
region = "us-west-2"
client = boto3.client('bedrock-agentcore', region_name=region)
response = client.start_browser_session(
browserIdentifier="aws.browser.v1",
name="session-with-profile",
sessionTimeoutSeconds=3600,
profileConfiguration={
"profileIdentifier": profile_id # From Step 1
}
)
new_session_id = response['sessionId']
print(f"New session started with profile: {new_session_id}")
print("Session is now authenticated with saved cookies and state")
```
1. To start a browser session with a profile using the API:
```
awscurl -X PUT \
"https://bedrock-agentcore..amazonaws.com/browsers/aws.browser.v1/sessions/start" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region \
-d '{
"name": "session-with-profile",
"sessionTimeoutSeconds": 3600,
"profileConfiguration": {
"profileIdentifier": ""
},
"clientToken": "8FAAFF7F-7803-4C40-A7BD-139C6D008646"
}'
```
## Browser profile operations
This section describes additional operations for managing browser profiles.
### Listing browser profiles
You can list all browser profiles in your account.
**Example**
1. To list browser profiles using the AWS CLI:
```
aws bedrock-agentcore-control list-browser-profiles \
--region
```
1. To list browser profiles using Boto3:
```
import boto3
region = "us-west-2"
client = boto3.client('bedrock-agentcore-control', region_name=region)
response = client.list_browser_profiles()
for profile in response.get('items', []):
print(f"Profile ID: {profile['profileId']}")
print(f"Name: {profile['name']}")
print(f"Status: {profile['status']}")
print("---")
```
1. To list browser profiles using the API:
```
awscurl -X POST \
"https://bedrock-agentcore-control..amazonaws.com/browser-profiles/list" \
-H "Content-Type: application/json" \
--service bedrock-agentcore-control \
--region
```
### Getting browser profile details
You can retrieve details about a specific browser profile.
**Example**
1. To get browser profile details using the AWS CLI:
```
aws bedrock-agentcore-control get-browser-profile \
--region \
--profile-id ""
```
1. To get browser profile details using Boto3:
```
import boto3
region = "us-west-2"
client = boto3.client('bedrock-agentcore-control', region_name=region)
response = client.get_browser_profile(
profileId=profile_id
)
print(f"Profile ID: {response['profileId']}")
print(f"Name: {response['name']}")
print(f"Description: {response.get('description', 'N/A')}")
print(f"Status: {response['status']}")
print(f"Created: {response['createdAt']}")
```
1. To get browser profile details using the API:
```
awscurl -X GET \
"https://bedrock-agentcore-control..amazonaws.com/browser-profiles/" \
-H "Content-Type: application/json" \
--service bedrock-agentcore-control \
--region
```
### Deleting a browser profile
When you no longer need a browser profile, you can delete it to free up resources.
**Example**
1. To delete a browser profile using the AWS CLI:
```
aws bedrock-agentcore-control delete-browser-profile \
--region \
--profile-id ""
```
1. To delete a browser profile using Boto3:
```
import boto3
region = "us-west-2"
client = boto3.client('bedrock-agentcore-control', region_name=region)
response = client.delete_browser_profile(
profileId=profile_id
)
print(f"Profile deleted successfully")
```
1. To delete a browser profile using the API:
```
awscurl -X DELETE \
"https://bedrock-agentcore-control..amazonaws.com/browser-profiles/" \
-H "Content-Type: application/json" \
--service bedrock-agentcore-control \
--region
```
## Use cases
Browser profiles are useful for:
+ **Persistent authentication** : Maintain login sessions across multiple browser invocations without re-authenticating each time
+ **Multi-step workflows** : Execute complex workflows that span multiple sessions while preserving state and context (in cookies or localstorage)
+ **Automated tasks** : Enable AI agents to perform tasks on authenticated websites without manual intervention
## Considerations
+ **Profile Persistence** : Profile data is saved when you explicitly call the save operation. Ensure you save the profile before terminating the session to preserve the state.
+ **Session Isolation** : Each browser session using a profile operates independently. Changes made in one session are not visible in other concurrent sessions.
+ **Profile Loading** : Saved profile changes only apply to new sessions. Active sessions continue using the profile state from when they were started and will not reflect updates made to the profile after session starts.
+ **Security** : Browser profiles may contain sensitive data such as authentication cookies. Ensure proper IAM policies are in place to restrict access to profile resources.
+ **Profile Updates** : When you save a session to a profile, it overwrites the previous profile data. Consider your workflow carefully to avoid losing important state information.
+ **Cookie Expiration** : Cookies have their own expiration times set by websites. Browser profiles preserve cookies, but expired cookies are automatically removed by the browser according to their expiration dates.
# Using browser proxies
Amazon Bedrock AgentCore Browser supports routing browser traffic through your own external proxy servers. This enables organizations to:
+ **Achieve IP stability** by routing traffic through proxies with known egress IPs, eliminating re-authentication cycles caused by rotating AWS IP addresses
+ **Support IP allowlisting** by providing stable, controllable egress addresses for services that require IP-based access controls
+ **Integrate with corporate infrastructure** by routing through your existing proxy servers for access to internal webpages and resources
## Overview
When you create a browser session with proxy configuration, AgentCore Browser configures the browser to route HTTP and HTTPS traffic through your specified proxy servers.
![\[Browser proxies request flow showing traffic routing from the browser session through a customer-managed proxy server to destination websites.\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/browser-proxies-flow.png)
Request flow:
1. You call `StartBrowserSession` with a `proxyConfiguration` specifying your proxy server.
1. If using authentication, AgentCore retrieves proxy credentials from AWS Secrets Manager.
1. The browser session starts with your proxy configuration applied.
1. Browser traffic routes through your proxy server based on your domain routing rules.
1. Your proxy server forwards requests to destination websites.
The proxy server is infrastructure you own and manage. AgentCore Browser connects to it as a client.
Proxy configuration applies the Chromium `--proxy-server` flag to the browser instance at startup, directing traffic through the specified proxy at the browser level. For scenarios that require network-layer enforcement—for example, when browser-level settings could be modified during runtime—deploy browser sessions within your own VPC. See [Configure Amazon Bedrock AgentCore Runtime and tools for VPC](agentcore-vpc.md).
## Prerequisites
Before configuring browser proxies, ensure you have:
+ **General browser prerequisites** – Complete the standard browser tool setup. See [Get started with AgentCore Browser](browser-quickstart.md).
+ **Proxy server** – An HTTP/HTTPS proxy server that is accessible from the public internet (or reachable within your VPC if using VPC configuration) and supports the HTTP CONNECT method for HTTPS traffic tunneling.
+ ** AWS Secrets Manager secret** (if using authentication) – A secret containing proxy credentials in JSON format with `username` and `password` keys.
+ **IAM permissions** (if using authentication) – The IAM identity calling `StartBrowserSession` must have `secretsmanager:GetSecretValue` permission for the credential secret.
## Getting started
This section shows the simplest configuration to route browser traffic through a proxy.
### Step 1: Create a credentials secret (if using authentication)
If your proxy requires authentication, create a secret in AWS Secrets Manager:
```
aws secretsmanager create-secret \
--name "my-proxy-credentials" \
--secret-string '{"username":"","password":""}'
```
Credential format requirements:
| Field | Allowed characters |
| --- | --- |
| `username` | Alphanumeric plus `@ . _ + = -` |
| `password` | Alphanumeric plus @ . \$1 \$1 = - \$1 \$1 \$1 % \$1 |
Characters not allowed: colon ( `:` ), newlines, spaces, quotes.
### Step 2: Add IAM permissions
Add this policy to the IAM identity that will create browser sessions:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "secretsmanager:GetSecretValue",
"Resource": "arn:aws:secretsmanager:AWS Region:AWS account:secret:secret-name*"
}
]
}
```
### Step 3: Create a browser session with proxy
You can create a browser session with proxy configuration using the AWS CLI, SDK, or API.
**Example**
1. To start a browser session with a proxy using the AWS CLI:
```
aws bedrock-agentcore start-browser-session \
--browser-identifier "aws.browser.v1" \
--name "my-proxy-session" \
--proxy-configuration '{
"proxies": [{
"externalProxy": {
"server": "your-proxy-hostname",
"port": 8080,
"credentials": {
"basicAuth": {
"secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name"
}
}
}
}]
}'
```
For proxies using IP allowlisting instead of credentials, omit the `credentials` field:
```
aws bedrock-agentcore start-browser-session \
--browser-identifier "aws.browser.v1" \
--name "my-proxy-session" \
--proxy-configuration '{
"proxies": [{
"externalProxy": {
"server": "your-proxy-hostname",
"port": 8080
}
}]
}'
```
1. To start a browser session with a proxy using the AWS SDK for Python (Boto3):
```
import boto3
client = boto3.client('bedrock-agentcore', region_name='region')
response = client.start_browser_session(
browserIdentifier="aws.browser.v1",
name="my-proxy-session",
proxyConfiguration={
"proxies": [{
"externalProxy": {
"server": "your-proxy-hostname",
"port": 8080,
"credentials": {
"basicAuth": {
"secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name"
}
}
}
}]
}
)
print(f"Session ID: {response['sessionId']}")
```
For proxies using IP allowlisting instead of credentials, omit the `credentials` field:
```
proxyConfiguration={
"proxies": [{
"externalProxy": {
"server": "your-proxy-hostname",
"port": 8080
}
}]
}
```
1. To start a browser session with a proxy using the API:
```
PUT /browsers/aws.browser.v1/sessions/start HTTP/1.1
Host: bedrock-agentcore.region.amazonaws.com
Content-Type: application/json
Authorization: AWS4-HMAC-SHA256 ...
{
"name": "my-proxy-session",
"proxyConfiguration": {
"proxies": [{
"externalProxy": {
"server": "your-proxy-hostname",
"port": 8080,
"credentials": {
"basicAuth": {
"secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name"
}
}
}
}]
}
}
```
## Configuration options
### Domain-based routing
Use `domainPatterns` to route specific domains through designated proxies:
**Example**
1.
```
aws bedrock-agentcore start-browser-session \
--browser-identifier "aws.browser.v1" \
--name "domain-routing-session" \
--proxy-configuration '{
"proxies": [
{
"externalProxy": {
"server": "corp-proxy.example.com",
"port": 8080,
"domainPatterns": [".company.com", ".internal.corp"]
}
},
{
"externalProxy": {
"server": "general-proxy.example.com",
"port": 8080
}
}
]
}'
```
1.
```
proxyConfiguration={
"proxies": [
{
"externalProxy": {
"server": "corp-proxy.example.com",
"port": 8080,
"domainPatterns": [".company.com", ".internal.corp"]
}
},
{
"externalProxy": {
"server": "general-proxy.example.com",
"port": 8080
}
}
]
}
```
1.
```
{
"proxyConfiguration": {
"proxies": [
{
"externalProxy": {
"server": "corp-proxy.example.com",
"port": 8080,
"domainPatterns": [".company.com", ".internal.corp"]
}
},
{
"externalProxy": {
"server": "general-proxy.example.com",
"port": 8080
}
}
]
}
}
```
With this configuration:
+ Requests to \$1.company.com and \$1.internal.corp route through `corp-proxy.example.com`
+ All other requests route through `general-proxy.example.com` (default)
Domain pattern format:
| Pattern | Matches | Does not match |
| --- | --- | --- |
| `.example.com` | `example.com` , `www.example.com` , `api.example.com` | `notexample.com` |
| `example.com` | `example.com` (exact match only) | `www.example.com` |
Use `.example.com` (leading dot) for subdomains. Do not use \$1.example.com.
### Bypass domains
Use `bypass.domainPatterns` for domains that should connect directly without any proxy:
**Example**
1.
```
aws bedrock-agentcore start-browser-session \
--browser-identifier "aws.browser.v1" \
--name "bypass-session" \
--proxy-configuration '{
"proxies": [{
"externalProxy": {
"server": "proxy.example.com",
"port": 8080
}
}],
"bypass": {
"domainPatterns": [".amazonaws.com"]
}
}'
```
1.
```
proxyConfiguration={
"proxies": [{
"externalProxy": {
"server": "proxy.example.com",
"port": 8080
}
}],
"bypass": {
"domainPatterns": [".amazonaws.com"]
}
}
```
1.
```
{
"proxyConfiguration": {
"proxies": [{
"externalProxy": {
"server": "proxy.example.com",
"port": 8080
}
}],
"bypass": {
"domainPatterns": [".amazonaws.com"]
}
}
}
```
**Note**
Proxy configuration is a browser-level routing setting and does not provide network-level traffic control. For network-layer enforcement, deploy browser sessions in your VPC. See [Configure Amazon Bedrock AgentCore Runtime and tools for VPC](agentcore-vpc.md).
### Routing precedence
Traffic routes according to this precedence (highest to lowest):
1. **Bypass domains** – Domains matching `bypass.domainPatterns` connect directly.
1. **Proxy domain patterns** – Domains matching a proxy’s `domainPatterns` route through that proxy (first match wins based on array order).
1. **Default proxy** – Unmatched domains route through the proxy without `domainPatterns`.
## Complete examples
The following examples show a full proxy configuration with domain patterns, bypass domains, and authentication credentials.
**Example**
1.
```
aws bedrock-agentcore start-browser-session \
--browser-identifier "aws.browser.v1" \
--name "proxy-session" \
--proxy-configuration '{
"proxies": [{
"externalProxy": {
"server": "proxy-hostname",
"port": 8080,
"domainPatterns": [".company.com"],
"credentials": {
"basicAuth": {
"secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name"
}
}
}
}],
"bypass": {
"domainPatterns": [".amazonaws.com"]
}
}'
```
1.
```
import boto3
client = boto3.client('bedrock-agentcore', region_name='region')
response = client.start_browser_session(
browserIdentifier="aws.browser.v1",
name="proxy-session",
proxyConfiguration={
"proxies": [{
"externalProxy": {
"server": "proxy-hostname",
"port": 8080,
"domainPatterns": [".company.com"],
"credentials": {
"basicAuth": {
"secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name"
}
}
}
}],
"bypass": {
"domainPatterns": [".amazonaws.com"]
}
}
)
print(f"Session ID: {response['sessionId']}")
```
1.
```
PUT /browsers/aws.browser.v1/sessions/start HTTP/1.1
Host: bedrock-agentcore.region.amazonaws.com
Content-Type: application/json
Authorization: AWS4-HMAC-SHA256 ...
{
"name": "proxy-session",
"proxyConfiguration": {
"proxies": [{
"externalProxy": {
"server": "proxy-hostname",
"port": 8080,
"domainPatterns": [".company.com"],
"credentials": {
"basicAuth": {
"secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name"
}
}
}
}],
"bypass": {
"domainPatterns": [".amazonaws.com"]
}
}
}
```
## Use cases
### IP stability for session-based portals
Healthcare and financial portals often validate sessions based on source IP address. Rotating AWS IP addresses cause frequent re-authentication. Route traffic through a proxy with stable egress IPs to maintain session continuity.
### Corporate infrastructure integration
Organizations that route traffic through corporate proxies can extend this practice to AgentCore Browser sessions, enabling access to internal webpages and resources that require proxy-based connectivity.
### Geographic content access
Access region-specific content or test regional website variations by routing traffic through proxies in specific geographic locations.
### Partner network access
Route partner-specific traffic through dedicated proxy infrastructure while using general proxies for other traffic.
## Session behavior
### Configuration lifecycle
+ **Set at creation** – Proxy configuration is set once at session creation. Configuration changes at runtime are not supported. Create a new session to use different settings.
+ **Session-scoped** – Each browser session has independent proxy configuration.
+ **Timeout** – Standard session timeouts apply. Proxy configuration is discarded when the session ends.
### Connectivity behavior
+ **Fail-open** – Proxy connectivity is not validated at session creation. Sessions configured with unavailable proxies will show errors when loading pages.
+ **Runtime errors** – Connection failures appear as browser error pages, visible in Live View for troubleshooting.
+ **No automatic retry** – Failed requests are not automatically retried.
## Cross-account secret access
If the credentials secret is in a different AWS account, configure the following:
**Secret resource policy** (in the account owning the secret):
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::caller-account-id:root"},
"Action": "secretsmanager:GetSecretValue",
"Resource": "*"
}]
}
```
**KMS key policy** (if using a customer-managed KMS key):
```
{
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::caller-account-id:root"},
"Action": "kms:Decrypt",
"Resource": "*"
}
```
## Security considerations
### Credential protection
+ Credentials are stored in AWS Secrets Manager and fetched using your IAM credentials.
+ Credentials are never returned in API responses. `GetBrowserSession` returns only `secretArn`.
+ Credentials are not written to logs.
### Access control
+ IAM permissions control which identities can use which credential secrets.
+ Cross-account access requires explicit resource policies.
## Performance considerations
+ **Capacity** – Ensure your proxy can handle expected request volume.
+ **Bypass** – Add AWS endpoints to `bypass.domainPatterns` for latency-sensitive calls.
+ **Proximity** – Use proxies geographically close to your AWS Region.
## Constraints
| Constraint | Limit | Adjustable |
| --- | --- | --- |
| Maximum proxies per session | 5 | Yes |
| Maximum domain patterns per proxy | 100 | Yes |
| Maximum bypass domain patterns | 100 | Yes |
| Server hostname length | 253 characters | No |
| Domain pattern length | 253 characters | No |
| Port range | 1–65535 | No |
To request an increase for adjustable constraints, contact AWS support.
## Limitations
Before configuring browser proxies, review these limitations to ensure the feature meets your requirements:
| Limitation | Details |
| --- | --- |
| Traffic routing | Proxy configuration is a browser-level setting applied at session startup. It is not a network-level control and does not guarantee that all traffic will transit the proxy. For network-layer enforcement, use [Configure Amazon Bedrock AgentCore Runtime and tools for VPC](agentcore-vpc.md). |
| Supported protocols | HTTP and HTTPS proxies only. SOCKS4 and SOCKS5 proxies are not supported. |
| Authentication | HTTP Basic authentication or no authentication (IP allowlisting). NTLM, Kerberos, and certificate-based authentication are not supported. |
| Proxy changes | Proxy configuration is set once at session creation. Configuration changes at runtime are not supported. Create a new session to change proxy settings. |
| Proxy rotation | Automatic proxy rotation for IP cycling or load distribution is not supported. Create new sessions to rotate proxies. |
| Connection validation | Proxy connectivity is not validated at session creation. Connection errors appear at runtime. |
# Using browser enterprise policies
Enterprise policies allow you to control browser behavior using the [Chromium enterprise policy](https://www.chromium.org/administrators/linux-quick-start/) mechanism. You provide policy files as JSON in your Amazon S3 bucket, and the service applies them to browser sessions automatically.
## Overview
Chromium enterprise policies can be applied at two enforcement levels:
+ **Managed** – Required and mandated by an administrator. These cannot be overridden. Managed policies are written to `/etc/chromium/policies/managed/`.
+ **Recommended** – Set at user level and take lower precedence to managed policies in the event of a conflict. Recommended policies are written to `/etc/chromium/policies/recommended/`.
For more details about Chrome policy types and precedence, see the [Chromium Linux Quick Start](https://www.chromium.org/administrators/linux-quick-start/).
Managed policies can be set using the `CreateBrowser` API and apply to all sessions created with that custom browser. Recommended policies are set at session level using the `StartBrowserSession` API and apply only to that specific session. They need to be re-applied to every new session.
You create JSON policy files following the [Chrome Enterprise Policy List](https://chromeenterprise.google/policies/) , upload them to your Amazon S3 bucket, and reference them when creating a browser or starting a session.
## Prerequisites
Before using enterprise policies, ensure you have:
+ Completed the general Browser [Prerequisites](browser-quickstart.md#browser-prerequisites)
+ An Amazon S3 bucket in the same region as your browser to store policy JSON files
+ IAM permissions to access the Amazon S3 bucket containing your policy files. Add the following permissions to your IAM policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EnterprisePolicyS3Access",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3::://*"
]
}
]
}
```
+ Policy JSON files following the Chromium enterprise policy format. Each file must contain valid policy keys from the [Chrome Enterprise Policy List](https://chromeenterprise.google/policies/).
## Preparing policy files
Create JSON files containing the policies you want to apply. Each file should contain a flat JSON object with policy keys and values.
**Example managed policy file**
This file disables autofill and password saving:
```
{
"AutofillAddressEnabled": false,
"AutofillCreditCardEnabled": false,
"PasswordManagerEnabled": false
}
```
**Example recommended policy file**
This file is used to set policies at session level:
```
{
"BookmarkBarEnabled": true,
"SpellCheckServiceEnabled": false,
"TranslateEnabled": false
}
```
Upload the policy files to your Amazon S3 bucket:
```
aws s3 cp managed-policies.json s3://my-policy-bucket/policies/managed-policies.json
aws s3 cp recommended-policies.json s3://my-policy-bucket/policies/recommended-policies.json
```
**Note**
You can specify up to 10 enterprise policy files. The Amazon S3 bucket must be in the same region as the browser.
## Creating a custom browser with managed policies
To enforce enterprise policies that cannot be overridden, create a custom browser with managed policies. Managed policies are applied to every session created with this browser.
**Example**
1.
```
aws bedrock-agentcore-control create-browser \
--region \
--name "my-managed-browser" \
--enterprise-policies '[
{
"type": "MANAGED",
"location": {
"s3": {
"bucket": "my-policy-bucket",
"prefix": "policies/managed-policies.json"
}
}
}
]'
```
1.
```
import boto3
region = "us-west-2"
client = boto3.client('bedrock-agentcore-control', region_name=region)
response = client.create_browser(
name="my-managed-browser",
enterprisePolicies=[
{
"type": "MANAGED",
"location": {
"s3": {
"bucket": "my-policy-bucket",
"prefix": "policies/managed-policies.json"
}
}
}
]
)
browser_id = response['browserId']
print(f"Created browser: {browser_id}")
```
1.
```
awscurl -X PUT \
"https://bedrock-agentcore-control..amazonaws.com/browsers" \
-H "Content-Type: application/json" \
--service bedrock-agentcore-control \
--region \
-d '{
"name": "my-managed-browser",
"enterprisePolicies": [
{
"type": "MANAGED",
"location": {
"s3": {
"bucket": "my-policy-bucket",
"prefix": "policies/managed-policies.json"
}
}
}
]
}'
```
## Starting a session with recommended policies
Recommended policies can be applied to sessions using the default browser ( `aws.browser.v1` ) as well as custom browsers that may already include managed policies.
**Tip**
For the default browser, set `browserIdentifier` to `aws.browser.v1`.
**Example**
1.
```
aws bedrock-agentcore start-browser-session \
--region \
--browser-identifier "" \
--name "my-session-with-policies" \
--session-timeout-seconds 1800 \
--enterprise-policies '[
{
"type": "RECOMMENDED",
"location": {
"s3": {
"bucket": "my-policy-bucket",
"prefix": "policies/recommended-policies.json"
}
}
}
]'
```
1.
```
import boto3
region = "us-west-2"
client = boto3.client('bedrock-agentcore', region_name=region)
response = client.start_browser_session(
browserIdentifier="",
name="my-session-with-policies",
sessionTimeoutSeconds=1800,
enterprisePolicies=[
{
"type": "RECOMMENDED",
"location": {
"s3": {
"bucket": "my-policy-bucket",
"prefix": "policies/recommended-policies.json"
}
}
}
]
)
print(f"Session ID: {response['sessionId']}")
```
1.
```
awscurl -X PUT \
"https://bedrock-agentcore..amazonaws.com/browsers//sessions/start" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--service bedrock-agentcore \
--region \
-d '{
"name": "my-session-with-policies",
"sessionTimeoutSeconds": 1800,
"enterprisePolicies": [
{
"type": "RECOMMENDED",
"location": {
"s3": {
"bucket": "my-policy-bucket",
"prefix": "policies/recommended-policies.json"
}
}
}
]
}'
```
## Considerations
+ You can specify up to 10 enterprise policy files.
+ Each policy file must have a `.json` extension and cannot exceed 5 MB in size.
+ The Amazon S3 bucket must be in the same region as the browser.
+ Policy files are read from Amazon S3 at the time of the API call. Changes to policy files in Amazon S3 after calling `CreateBrowser` or `StartBrowserSession` are not reflected.
+ Policy JSON files must contain valid keys from the [Chrome Enterprise Policy List](https://chromeenterprise.google/policies/).
# Configure Root Certificate Authority for Amazon Bedrock AgentCore Browser
By default, Amazon Bedrock AgentCore Browser sessions trust only publicly recognized certificate authorities. If your agents need to access internal services, corporate websites, or resources behind a TLS-intercepting proxy that use certificates signed by a private CA, you must provide your custom root CA certificates when starting a session.
Amazon Bedrock AgentCore retrieves the PEM-encoded certificate content from AWS Secrets Manager using your caller credentials, validates the X.509 format and expiry, and installs the certificates into the session’s OS trust store. This enables the browser to establish trusted HTTPS connections to your internal resources.
## How it works
Root Certificate Authority for Amazon Bedrock AgentCore Browser works as follows:
1. You provide a list of certificate locations, each pointing to a secret in AWS Secrets Manager that contains a PEM-encoded root CA certificate.
1. Amazon Bedrock AgentCore uses your caller credentials to retrieve each certificate from AWS Secrets Manager.
1. Each certificate is validated for correct X.509 PEM format and checked to ensure it has not expired and is not used before its validity start date.
1. Valid certificates are deployed to the session’s OS trust store, making them available to the browser and any network clients within the sandbox.
Certificates configured at the tool level (through `CreateBrowser` ) are combined with any certificates provided at session start time. This allows you to set organization-wide certificates on the tool and add session-specific certificates as needed.
**Note**
Certificate configuration is a one-time operation per session. Once certificates are installed, they cannot be modified for the duration of that session.
## Prerequisites
Before configuring root CA certificates, ensure you have the following:
+ Completed the general [Prerequisites](browser-quickstart.md#browser-prerequisites).
+ Your root CA certificates stored as secrets in AWS Secrets Manager. Each secret must contain valid PEM-encoded X.509 certificate
+ IAM permissions to read the certificate secrets from AWS Secrets Manager. Add the following permissions to your IAM policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerCertificateAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:::secret:"
}
]
}
```
## Store your certificate in AWS Secrets Manager
Before you can use a root CA certificate with Amazon Bedrock AgentCore Browser, you must store it as a secret in AWS Secrets Manager. The secret value must be the PEM-encoded certificate content.
**Example**
1.
```
aws secretsmanager create-secret \
--name "my-corporate-root-ca" \
--description "Corporate root CA certificate for AgentCore sessions" \
--secret-string file://my-root-ca.pem \
--region
```
1.
```
import boto3
client = boto3.client('secretsmanager', region_name='')
# Read the PEM certificate file
with open('my-root-ca.pem', 'r') as f:
cert_content = f.read()
response = client.create_secret(
Name='my-corporate-root-ca',
Description='Corporate root CA certificate for AgentCore sessions',
SecretString=cert_content
)
print(f"Secret ARN: {response['ARN']}")
```
Note the secret ARN from the output. You will use this ARN when starting sessions with certificate configuration.
**Important**
The secret must contain a valid PEM-encoded X.509 certificate. The certificate must not be expired and must be within its validity period. Amazon Bedrock AgentCore validates the certificate format and expiry before installing it.
## Start a browser session with custom certificates
To start a browser session that trusts your custom root CA certificates, include the `certificates` parameter in your `StartBrowserSession` request.
**Example**
1.
```
aws bedrock-agentcore start-browser-session \
--browser-identifier "aws.browser.v1" \
--name "session-with-custom-ca" \
--certificates '[
{
"location": {
"secretsManager": {
"secretArn": "arn:aws:secretsmanager:::secret:"
}
}
}
]'
```
1.
```
import boto3
client = boto3.client('bedrock-agentcore', region_name='')
response = client.start_browser_session(
browserIdentifier="aws.browser.v1",
name="session-with-custom-ca",
certificates=[
{
"location": {
"secretsManager": {
"secretArn": "arn:aws:secretsmanager:::secret:"
}
}
}
]
)
print(f"Session ID: {response['sessionId']}")
print(f"Status: {response['status']}")
```
1.
```
{
"name": "session-with-custom-ca",
"certificates": [
{
"location": {
"secretsManager": {
"secretArn": "arn:aws:secretsmanager:::secret:"
}
}
}
]
}
```
## Using multiple certificates
You can provide multiple root CA certificates in a single browser session. This is useful when your environment requires trust for multiple internal certificate authorities, such as separate CAs for different internal services or environments.
**Example**
1.
```
aws bedrock-agentcore start-browser-session \
--browser-identifier "aws.browser.v1" \
--name "session-with-multiple-cas" \
--certificates '[
{
"location": {
"secretsManager": {
"secretArn": "arn:aws:secretsmanager:::secret:corporate-root-ca"
}
}
},
{
"location": {
"secretsManager": {
"secretArn": "arn:aws:secretsmanager:::secret:proxy-ca"
}
}
}
]'
```
1.
```
response = client.start_browser_session(
browserIdentifier="aws.browser.v1",
name="session-with-multiple-cas",
certificates=[
{
"location": {
"secretsManager": {
"secretArn": "arn:aws:secretsmanager:::secret:corporate-root-ca"
}
}
},
{
"location": {
"secretsManager": {
"secretArn": "arn:aws:secretsmanager:::secret:proxy-ca"
}
}
}
]
)
```
## Configure certificates at the tool level
You can configure certificates at the tool level when creating a custom browser. Certificates configured at the tool level are automatically applied to every session started with that tool, in addition to any certificates provided at session start time.
This is useful for organization-wide certificates that should be trusted by all browser sessions.
**Example**
1.
```
response = client.create_browser(
name="corporate-browser",
description="Browser with corporate CA trust",
certificates=[
{
"location": {
"secretsManager": {
"secretArn": "arn:aws:secretsmanager:::secret:corporate-root-ca"
}
}
}
]
)
browser_id = response['browserIdentifier']
print(f"Browser ID: {browser_id}")
```
When you start a session with a browser that has certificates configured, the tool-level certificates are combined with any session-level certificates. Tool-level certificates are applied first, followed by session-level certificates.
## Certificate requirements and limits
Certificates must meet the following requirements:
| Requirement | Details |
| --- | --- |
| Format | PEM-encoded X.509 certificate |
| Storage | AWS Secrets Manager secret (as a string value, not binary) |
| Validity | Certificate must not be expired and must be within its validity period (between `notBefore` and `notAfter` dates) |
| Maximum certificates per session | 10 per session and 10 per tool. A session can have up to 20 certificates in total. |
| Secret ARN format | `arn:aws:secretsmanager:region:account-id:secret:secret-name` |
| Location type | Only AWS Secrets Manager is supported as a certificate location |
# Browser OS action
The InvokeBrowser API provides direct operating system-level control over Amazon Bedrock AgentCore Browser sessions. While the WebSocket-based automation endpoint uses Chrome DevTools Protocol (CDP) for browser interaction, InvokeBrowser operates at the OS level, enabling actions that CDP cannot handle — such as interacting with print dialogs, keyboard shortcuts, right-click context menus, JavaScript alerts, and capturing full-screen screenshots.
## Overview
The Amazon Bedrock AgentCore Browser provides two ways to interact with a browser session:
+ **WebSocket-based automation (CDP)** : Uses the Chrome DevTools Protocol over a WebSocket connection. This is ideal for standard browser automation tasks such as navigating pages, clicking DOM elements, filling forms, and extracting page content. Libraries like Playwright and browser-use connect through this endpoint.
+ **OS-level actions (InvokeBrowser)** : Uses a REST API to perform operating system-level interactions through mouse, keyboard, and screenshot actions. This complements CDP by handling scenarios where browser-level automation is insufficient.
Use InvokeBrowser when your agent needs to:
+ Interact with native OS dialogs such as print dialogs, file upload/download dialogs, or authentication prompts that are outside the browser DOM
+ Dismiss JavaScript alerts, confirms, or prompts that block CDP execution
+ Use keyboard shortcuts (for example, ctrl\$1a, ctrl\$1p) that trigger OS-level behavior
+ Interact with right-click context menus rendered by the operating system
+ Capture full desktop screenshots that include content outside the browser viewport, such as OS notifications or multi-window layouts
+ Perform drag-and-drop operations that span across browser windows or between the browser and the desktop
InvokeBrowser follows the same pattern as InvokeCodeInterpreter: a single unified operation with action-type dispatch. You send a request with exactly one action, and receive a corresponding result.
## Supported actions
InvokeBrowser supports the following action types through the `BrowserAction` union. Exactly one action member must be set per request.
### Mouse actions
For all mouse actions, coordinate values ( `x` , `y` ) must be strictly within the browser session viewport bounds. Valid ranges are 1 < x < viewportWidth-2 and 1 < y < viewportHeight-2. The default viewport size is 1456×819 pixels, which can be configured when starting a session using the `viewPort` parameter.
| Action | Required fields | Optional fields | Description |
| --- | --- | --- | --- |
| `mouseClick` | `x` (Integer), `y` (Integer) | `button` (MouseButton), `clickCount` (Integer) | Click at the specified coordinates. `clickCount` : 1–10. `button` : LEFT, RIGHT, MIDDLE. |
| `mouseMove` | `x` (Integer), `y` (Integer) | — | Move cursor to the specified coordinates. |
| `mouseDrag` | `startX` (Integer), `startY` (Integer), `endX` (Integer), `endY` (Integer) | `button` (MouseButton) | Drag from start to end position. `button` defaults to LEFT. |
| `mouseScroll` | `x` (Integer), `y` (Integer) | `deltaX` (Integer), `deltaY` (Integer) | Scroll at the specified position. `deltaX` / `deltaY` : -1000 to 1000. Negative `deltaY` scrolls down. |
### Keyboard actions
| Action | Required fields | Optional fields | Description |
| --- | --- | --- | --- |
| `keyType` | `text` (String) | — | Type a string of text. Maximum length: 10,000 characters. |
| `keyPress` | `key` (String) | `presses` (Integer) | Press a key N times. `presses` : 1–100. Defaults to 1. |
| `keyShortcut` | `keys` (KeyList) | — | Press a key combination (for example, `["ctrl", "s"]` ). Maximum 5 keys. |
### Screenshot action
| Action | Required fields | Optional fields | Description |
| --- | --- | --- | --- |
| `screenshot` | — | `format` (ScreenshotFormat) | Capture the full OS desktop (not just the browser viewport). Format: PNG only. |
## Considerations
+ **ASCII-only text input** : The `keyType` action supports ASCII characters only. Non-ASCII characters (such as Unicode or multi-byte characters) are skipped during input.
+ **No key name validation** : The `keyPress` and `keyShortcut` actions do not validate whether the specified key names are supported. If you provide an unrecognized key name, the API returns a SUCCESS status without performing the intended action. Refer to the supported key names listed above.
+ **Supported key names** : Key names for `keyPress` and `keyShortcut` actions must be in lowercase. Supported keys include single characters ( `a` – `z` , `0` – `9` ), and named keys such as `enter` , `tab` , `space` , `backspace` , `delete` , `escape` , `ctrl` , `alt` , `shift`.
## Request and response format
### Request
```
POST /browsers/{browserIdentifier}/sessions/invoke HTTP/1.1
x-amzn-browser-session-id: sessionId
Content-type: application/json
```
The request body contains an `action` field with exactly one member of the `BrowserAction` union set:
```
{
"action": {
"mouseClick": {
"x": 100,
"y": 200,
"button": "LEFT",
"clickCount": 1
}
}
}
```
### Response
The `sessionId` is returned via the `x-amzn-browser-session-id` response header. The response body contains a `result` field with the corresponding action result.
On success:
```
{
"result": {
"mouseClick": {
"status": "SUCCESS",
"error": null
}
}
}
```
On failure, the `status` field is set to FAILED and the `error` field contains a description of the failure.
## Examples
The following examples show how to invoke browser actions using the AWS CLI, AWS SDK for Python (Boto3), and the API.
**Example**
1. To click at a specific position:
```
aws bedrock-agentcore invoke-browser \
--region \
--browser-identifier "aws.browser.v1" \
--session-id "" \
--action '{"mouseClick": {"x": 100, "y": 200, "button": "LEFT", "clickCount": 1}}'
```
To type text:
```
aws bedrock-agentcore invoke-browser \
--region \
--browser-identifier "aws.browser.v1" \
--session-id "" \
--action '{"keyType": {"text": "Hello, world!"}}'
```
To press a keyboard shortcut:
```
aws bedrock-agentcore invoke-browser \
--region \
--browser-identifier "aws.browser.v1" \
--session-id "" \
--action '{"keyShortcut": {"keys": ["ctrl", "s"]}}'
```
To take a screenshot:
```
aws bedrock-agentcore invoke-browser \
--region \
--browser-identifier "aws.browser.v1" \
--session-id "" \
--action '{"screenshot": {"format": "PNG"}}'
```
1. To click at a specific position:
```
response = dp_client.invoke_browser(
browserIdentifier="aws.browser.v1",
sessionId="",
action={
"mouseClick": {
"x": 100,
"y": 200,
"button": "LEFT",
"clickCount": 1
}
}
)
print(f"Status: {response['result']['mouseClick']['status']}")
```
To type text:
```
response = dp_client.invoke_browser(
browserIdentifier="aws.browser.v1",
sessionId="",
action={
"keyType": {
"text": "Hello, world!"
}
}
)
```
To take a screenshot and save it:
```
import base64
response = dp_client.invoke_browser(
browserIdentifier="aws.browser.v1",
sessionId="",
action={
"screenshot": {
"format": "PNG"
}
}
)
if response['result']['screenshot']['status'] == 'SUCCESS':
image_data = base64.b64decode(response['result']['screenshot']['data'])
with open("screenshot.png", "wb") as f:
f.write(image_data)
print("Screenshot saved as screenshot.png")
```
1. To click at a specific position:
```
awscurl -X POST \
"https://bedrock-agentcore..amazonaws.com/browsers/aws.browser.v1/sessions/invoke" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "x-amzn-browser-session-id: " \
--service bedrock-agentcore \
--region \
-d '{
"action": {
"mouseClick": {
"x": 100,
"y": 200,
"button": "LEFT",
"clickCount": 1
}
}
}'
```
To take a screenshot:
```
awscurl -X POST \
"https://bedrock-agentcore..amazonaws.com/browsers/aws.browser.v1/sessions/invoke" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "x-amzn-browser-session-id: " \
--service bedrock-agentcore \
--region \
-d '{
"action": {
"screenshot": {
"format": "PNG"
}
}
}'
```
# Troubleshoot AgentCore Browser
This section provides solutions to common issues you might encounter when using the Amazon Bedrock AgentCore Browser.
## Permission denied errors
**Symptom:** Errors mentioning access denied or insufficient permissions.
**Solution:**
+ Verify your IAM user or role has the required Browser permissions
+ Check your AWS credentials: `aws sts get-caller-identity`
+ For recording: Verify the execution role has Amazon S3 write permissions
+ For recording: Confirm the trust policy allows `bedrock-agentcore.amazonaws.com` to assume the role
## Model access denied
**Symptom:** Errors about model access or authorization when running agents.
**Solution:**
+ Navigate to the Amazon Bedrock console
+ Go to **Model access** in the left navigation
+ Enable **Anthropic Claude Sonnet 4**
+ Verify you’re in the correct region (match the region in your code)
## Browser session timeout
**Symptom:** Browser sessions end unexpectedly or timeout errors occur.
**Solution:**
+ Check the `sessionTimeoutSeconds` parameter when starting sessions
+ Default timeout is 900 seconds (15 minutes)
+ Increase timeout for longer sessions: `sessionTimeoutSeconds=1800`
+ Sessions automatically stop after the timeout period
## Recording not appearing in Amazon S3
**Symptom:** No recording files in your Amazon S3 bucket after session completes.
**Solution:**
+ Verify the execution role has correct Amazon S3 permissions
+ Confirm the Amazon S3 bucket name and prefix are correct
+ Check the execution role trust policy includes bedrock-agentcore service
+ Review CloudWatch Logs for Amazon S3 upload errors
+ Ensure the session ran for at least a few seconds (very short sessions may not generate recordings)
## Playwright connection errors
**Symptom:** Cannot connect to browser with Playwright or WebSocket errors.
**Solution:**
+ Verify you installed playwright: `pip install playwright`
+ Confirm the browser session started successfully before connecting
+ Check that the session is still active (not timed out)
+ Verify your network allows WebSocket connections
## Agent cannot make progress due to CAPTCHA checks
**Issue:** Your agent gets blocked by CAPTCHA verification when using the Browser tool to interact with websites.
**Cause:** Anti-bot measures on popular websites detect automated browsing and require human verification.
**Solution:** Structure your agent to avoid search engines and implement the following architecture pattern:
+ Use the Browser tool only for specific page actions, not general web searching
+ Use non-browser MCP tools like Tavily search for general web search operations
+ Consider adding a live view feature to your agent application that allows end users to take control and solve CAPTCHAs when needed
## CORS errors when integrating with browser applications
**Issue:** Cross-Origin Resource Sharing (CORS) errors occur when building browser-based web applications that call a custom Amazon Bedrock AgentCore runtime server.
**Cause:** Browser security policies block cross-origin requests to your runtime server during local development or self-hosted deployment.
**Solution:** Add CORS middleware to your BedrockAgentCoreApp to handle cross-origin requests from your frontend:
```
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from fastapi.middleware.cors import CORSMiddleware
app = BedrockAgentCoreApp()
# Add CORS middleware to allow browser requests
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Customize in production
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Handle browser preflight requests to /invocations
@app.options("/invocations")
async def options_handler():
return {"message": "OK"}
@app.entrypoint
def my_agent(payload):
return {"response": "Hello from agent"}
```
**Important**
In production environments, replace allow\$1origins=["\$1"] with specific domain origins for better security.
## Session Replay and Web Bot Auth don’t work in new browser windows or contexts
**Issue:** Session Replay and Web Bot Auth features are not available when your automation code creates new browser windows or contexts.
**Cause:** These features rely on browser extensions that only work in the default browser context provided by Amazon Bedrock AgentCore. When you create a new context using methods like `browser.new_context()` in Playwright, the extensions are not available.
**Solution:** Use the default browser context provided when you connect to the browser session. Avoid creating new contexts or windows if you need Session Replay or Web Bot Auth functionality.
```
# ✓ Use the existing default context
context = browser.contexts[0]
page = context.pages[0]
# ✗ Don't create new contexts - Session Replay and Web Bot Auth won't work
# context = browser.new_context()
```
## Browser extensions issues
### Extension download fails with access denied
**Symptom:** Session fails to start with errors related to Amazon S3 access when using extensions.
**Solution:**
+ Verify your IAM user or role has `s3:GetObject` and `s3:GetObjectHead` permission on the extension bucket
+ Confirm the Amazon S3 bucket is owned by the same AWS account making the API call
+ Check that the bucket name and prefix (object key) are correct
+ If using versioned buckets, ensure you have `s3:GetObjectVersion` permission
### Extension rejected due to invalid format
**Symptom:** Session fails to start with validation errors about the extension file format.
**Solution:**
+ Ensure the extension file is in ZIP format
+ Verify the ZIP file contains a valid Chrome extension structure with a valid `manifest.json` file
+ Check that the extension follows Chrome extension guidelines
+ Ensure the ZIP was created from the extension directory contents, not the parent folder
## Browser profile issues
### Failed to save browser session profile due to concurrent operation on the profile
**Symptom:** `SaveBrowserSessionProfile` throws `ConflictException`.
**Solution:**
+ Retry `SaveBrowserSessionProfile` at a later time
+ Use exponential backoff with jitter if retrying from agent or code
### Failed to save browser session profile due to concurrent operation on the session
**Symptom:** `SaveBrowserSessionProfile` throws `ConflictException`.
**Solution:**
+ Retry `SaveBrowserSessionProfile` at a later time
+ Use exponential backoff with jitter if retrying from agent or code
### Authentication fails when loading a saved browser profile
**Symptom:** A browser session loaded from a saved profile requires re-authentication even though the profile was saved with valid authentication cookies.
**Cause:** Cookies stored in the browser profile have expired. Websites set expiration times on cookies (such as authentication tokens), and the browser automatically removes expired cookies according to these expiration dates. When you load a profile, any cookies that have expired since the profile was saved will not be available.
**Solution:**
+ Re-authenticate in the browser session to obtain fresh cookies
+ Save the profile again after re-authentication to update it with new cookies
+ For workflows requiring long-term authentication, consider the typical cookie lifetime of your target websites when planning profile usage
+ Implement periodic re-authentication in your automation workflow if cookie expiration is expected
+ Save profiles more frequently for critical authentication states to minimize the time between saves and subsequent use
**Note**
Cookie expiration times are set by websites and cannot be modified by browser profiles. Session cookies typically expire when the browser session ends, while persistent cookies expire based on their Max-Age or Expires attributes.
## Troubleshooting Root Certificate Authority issues
The following table describes common errors and their resolutions when configuring root CA certificates for Amazon Bedrock AgentCore Browser.
| Error | Cause | Resolution |
| --- | --- | --- |
| Certificate secret not found in Secrets Manager | The secret ARN does not exist or the secret has been deleted. | Verify the secret ARN is correct and the secret exists in the specified Region. |
| Access denied to certificate secret in Secrets Manager | The caller does not have `secretsmanager:GetSecretValue` permission on the secret. | Add the `secretsmanager:GetSecretValue` permission to your IAM policy for the specified secret ARN. |
| Certificate content is not valid PEM/X.509 format | The secret value is not a valid PEM-encoded X.509 certificate. | Ensure the secret contains a properly formatted PEM certificate starting with `-----BEGIN CERTIFICATE-----` and ending with `-----END CERTIFICATE-----`. |
| Certificate has expired | The certificate’s `notAfter` date is in the past. | Replace the expired certificate with a valid one in AWS Secrets Manager and retry. |
| Certificate is not yet valid | The certificate’s `notBefore` date is in the future. | Wait until the certificate’s validity period begins, or use a certificate that is currently valid. |
| Number of certificates exceeds the maximum allowed | More than 10 certificates were provided at the session level or tool level. | Reduce the number of certificates to 10 or fewer per session and 10 or fewer per tool. |
| Certificate location is required | A certificate entry was provided without a location. | Ensure each certificate in the array includes a `location` with a `secretsManager` entry containing a valid `secretArn`. |
| Certificates configuration is not enabled | The certificates feature is not enabled for your account. | Contact AWS Support to enable the certificates feature for your account. |
## Troubleshooting browser proxies
### Errors when starting a session with proxy
**Symptom:** `StartBrowserSession` returns an HTTP 400 error with a message beginning with `Failed to set up browser proxy:`.
**Cause:** The proxy configuration or credentials secret is invalid.
**Solution:**
+ `Proxy credentials secret not found in Secrets Manager` – The secret ARN does not match any secret in the target account and Region. Verify the ARN is correct and that the secret has not been deleted or scheduled for deletion.
+ `Invalid proxy credentials secret configuration (check encryption key for cross-account access)` – The secret exists but cannot be accessed. Ensure the calling identity has `secretsmanager:GetSecretValue` permission. For cross-account secrets, see [Cross-account secret access](browser-proxies.md#browser-proxies-cross-account).
+ `Proxy credentials secret must be a JSON object with username and password fields` – Update the secret value to a valid JSON object: `{"username": "…", "password": "…"}`.
+ `Failed to parse proxy credentials from secret` – The secret value could not be read as proxy credentials. Verify the secret contains a plain JSON string (not binary) with `username` and `password` fields.
+ `Field 'username' is missing or empty in secret` or `Field 'password' is missing or empty in secret` – Ensure both `username` and `password` are present and non-empty in the secret.
+ `Field 'username' contains invalid characters` or `Field 'password' contains invalid characters` – Use only the characters listed in the error message. See [Step 1: Create a credentials secret (if using authentication)](browser-proxies.md#browser-proxies-step1) for allowed characters.
+ `Field 'username' exceeds maximum length of 256 characters` or `Field 'password' exceeds maximum length of 256 characters` – Shorten the credential to 256 characters or fewer.
### Proxy connection errors in browser
**Symptom:** A browser session starts successfully, but page navigation fails for proxied domains with HTTP 502 errors or `net::ERR_INVALID_AUTH_CREDENTIALS`.
**Cause:** The browser cannot connect to the proxy server, or the proxy server rejects the provided credentials. These are Chromium network errors, not AWS API errors.
**Solution:**
+ **HTTP 502 on proxied pages** – Verify the proxy hostname, port, and that the server is running and reachable from the public internet (or from your VPC if using VPC configuration).
+ `net::ERR_INVALID_AUTH_CREDENTIALS` – Update the secret in Secrets Manager with valid credentials for the proxy server.
+ Use `GetBrowserSession` to confirm the active proxy settings. Credentials are never returned in the response.
**Note**
These errors are visible in Live View and through the automation API.
## Troubleshooting InvokeBrowser OS actions
The following table describes common errors when using the InvokeBrowser API for OS-level browser actions.
| Exception | HTTP code | Description |
| --- | --- | --- |
| `ValidationException` | 400 | Invalid input. For coordinate-based actions ( `mouseClick` , `mouseMove` , `mouseDrag` , `mouseScroll` ), coordinates must be strictly within the session viewport bounds (1 < x < viewportWidth-2, 1 < y < viewportHeight-2). The default viewport size is 1456×819 pixels. Also returned for disabled actions or invalid parameter values. |
| `AccessDeniedException` | 403 | Insufficient permissions or action not allowed for the session. |
| `ResourceNotFoundException` | 404 | Invalid `browserIdentifier` or `sessionId`. |
| `ServiceQuotaExceededException` | 402 | Service quota has been exceeded. |
| `ThrottlingException` | 429 | Rate limit exceeded. |
| `InternalServerException` | 500 | Unexpected failure in execution. |
**Solution:**
+ Verify that coordinate values are within the session viewport dimensions. Use the `screenshot` action to capture the current screen and confirm the visible area.
+ Check that the browser session is still active and has not timed out.
+ Ensure your IAM identity has the `bedrock-agentcore:InvokeBrowser` permission.