# 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}
```