The Browser Tool

Most of the web your agent needs is not a clean JSON API. It's a single-page React app that renders nothing until JavaScript runs, a vendor portal behind a login wall, a booking flow with multi-step forms, a dashboard that only exists as a screenshot. A plain requests.get() or even a Gateway OpenAPI target gets you the empty HTML shell and nothing else.

AgentCore Browser is a fully managed, pre-built, cloud-based browser that gives an agent a secure, isolated environment to interact with web applications the way a human does: navigate, fill forms, click, parse JS-rendered content, take screenshots, upload and download files. It is one of the two built-in Tools in AgentCore — the other is the Code Interpreter — and it is deliberately framework- and model-agnostic: you drive it with Playwright, browser-use, Amazon Nova Act, or Strands, and the model behind your agent can be anything.

There are two flavors of the resource:

• System browser — the managed default, identified as aws.browser.v1 (created with --type SYSTEM). No setup; just start a session against it.
• Custom browser — created with --type CUSTOM, where you control session recording, network settings, an execution IAM role, Web Bot Auth, browser profiles, proxies, and extensions.

Keep one distinction crisp from the start. A Browser is the long-lived resource (it has an ARN like arn:aws:bedrock-agentcore:<region>:<account>:browser/*). A Browser session is an ephemeral runtime instance you start against that resource and then interact with. You create a browser rarely; you start and stop sessions constantly.

Every use of the Browser Tool follows the same four steps:

1. Create a Browser Tool. Either use the managed default aws.browser.v1, or create a custom browser when you need recording, custom network settings, an execution role, Web Bot Auth, profiles, proxies, or extensions.
2. Start a session. Each session is isolated and has a configurable timeout — default 15 minutes (900 s), max 8 hours. You can run many concurrently.
3. Interact. Two channels per session: the WebSocket/CDP "automation" stream (driven by Playwright, browser-use, or Nova Act) for DOM-level work, and the Live View stream for a human to watch or take over.
4. Monitor & record. Live View, session recording (custom browsers only), CloudWatch metrics, CloudTrail, and S3 replay.

The resource types map onto two ARN shapes:

Networking. The Browser currently runs in PUBLIC mode — set as networkConfiguration.networkMode="PUBLIC". The GA launch blog references a VPC mode, but the documentation only documents PUBLIC; treat VPC as not-yet-documented and verify the live page before assuming it.

The security story is per-session microVM isolation: each session runs in its own microVM with isolated CPU, memory, and filesystem. When a session completes the microVM is terminated and its memory sanitized, so nothing leaks between sessions or tenants. Scaling is serverless and automatic, and everything is IAM-governed.

The concrete numbers are [VOLATILE] — teach the shape, verify the live quotas page before you design around any single value. As researched:

The isolation model is what makes the Browser safe to point at hostile websites: a page can run arbitrary JavaScript, but it runs inside a throwaway microVM with no access to your other sessions, and the whole thing is wiped on completion.

The agent loop is: a natural-language query goes to your framework, the LLM turns it into structured instructions, those become browser actuation commands (Playwright/Puppeteer/Selenium), and those execute over a secure WebSocket using the Chrome DevTools Protocol (CDP) — the page responds, a screenshot comes back, and the loop continues.

Every session exposes its streams under session.streams:

• automationStream — wss://.../automation, the CDP channel the agent (Playwright/browser-use/Nova Act) drives.
• liveViewStream — a human-facing stream you can watch live in the console.

From the SDK, the BrowserClient hands you both. generate_ws_headers() returns the CDP WebSocket URL plus the SigV4-signed headers you must attach to authenticate; generate_live_view_url(expires=120) returns a time-boxed Live View URL.

from bedrock_agentcore.tools.browser_client import browser_session

with browser_session("us-west-2", viewport={"width": 1920, "height": 1080}) as browser:
    ws_url, headers = browser.generate_ws_headers()        # CDP WebSocket URL + signed headers
    live_view = browser.generate_live_view_url(expires=120)  # human watch/interact, 120 s

The Live View URL itself is of the form https://bedrock-agentcore.<Region>.amazonaws.com/browser-streams/{browser_id}/sessions/{session_id}/live-view. The samples repo also ships a BrowserViewerServer helper that hosts a small viewer for you.

Take/release control is the safety mechanism that protects credentials. A human watching Live View can take control — and you can hide that moment from the agent by disabling the automation stream before the human types a password, then re-enabling it afterward. You do this with update_browser_stream:

# Hand control to the human: disable the agent's CDP automation stream
client.update_browser_stream(
    browserIdentifier="aws.browser.v1",
    sessionId=session_id,
    streamUpdate={"automationStreamUpdate": {"streamStatus": "DISABLED"}},
)

# ... human enters credentials in Live View; the agent cannot observe the keystrokes ...

# Return control to the agent
client.update_browser_stream(
    browserIdentifier="aws.browser.v1",
    sessionId=session_id,
    streamUpdate={"automationStreamUpdate": {"streamStatus": "ENABLED"}},
)

While the automation stream is DISABLED, the agent is blind to the page; only the human (via Live View) is driving. This is the canonical pattern for "the agent does everything except the login".

Because the automation stream is plain CDP, any framework that can attach to a CDP endpoint works — you just have to get the signed headers onto the WebSocket.

Playwright connects with connect_over_cdp, passing the URL and headers from generate_ws_headers(). Screenshots go through a CDP session:

from playwright.sync_api import sync_playwright

with browser_session("us-west-2") as browser:
    ws_url, headers = browser.generate_ws_headers()
    with sync_playwright() as p:
        chromium = p.chromium.connect_over_cdp(ws_url, headers=headers)
        context = chromium.contexts[0]
        page = context.pages[0]
        page.goto("https://example.com")
        # Full-page screenshot via the Chrome DevTools Protocol
        cdp = context.new_cdp_session(page)
        shot = cdp.send("Page.captureScreenshot", {"format": "png", "captureBeyondViewport": True})

Amazon Nova Act takes the same CDP endpoint and headers directly. It needs a Nova Act API key and the nova-act PyPI package; there is also an AgentCoreBrowserSessionProvider. AWS published an agentic QA-automation reference built on this (per-test isolated sessions, parallelized with pytest-xdist):

from nova_act import NovaAct

ws_url, headers = browser.generate_ws_headers()
with NovaAct(
    cdp_endpoint_url=ws_url,
    cdp_headers=headers,
    nova_act_api_key=NOVA_ACT_API_KEY,
    starting_page="https://example.com",
) as nova:
    nova.act("search for a wireless keyboard and add the cheapest to the cart")

browser-use also connects over the CDP ws_url plus headers. Watch the version: some versions of browser-use stopped forwarding custom headers to the CDP WebSocket, which breaks AgentCore's header-based auth. Pin a version that forwards headers (see browser-use issue #3111). Strands sits one level up — it orchestrates the agent and lets Playwright actuate (the AWS payments-plus-browser sample is built this way).

Some interactions live outside the DOM — native dialogs, OS alerts, keyboard shortcuts, full-desktop screenshots, drag-and-drop. For those you use the second per-session channel: the OS-level InvokeBrowser REST API, which actuates the operating system itself, not just the page.

It's a single endpoint, POST /browsers/{browserIdentifier}/sessions/invoke, with the session passed in the x-amzn-browser-session-id header. Coordinates must satisfy 1 < x < viewportWidth-2 and 1 < y < viewportHeight-2.

The actions:

curl -X POST \
  "https://bedrock-agentcore.us-west-2.amazonaws.com/browsers/aws.browser.v1/sessions/invoke" \
  -H "x-amzn-browser-session-id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "mouseClick",
    "mouseClick": { "x": 720, "y": 410, "button": "LEFT", "clickCount": 1 }
  }'

Two silent traps to internalize: a keyType with non-ASCII characters is silently skipped, and an invalid key name in keyPress/keyShortcut returns SUCCESS but does nothing. If a shortcut "works" in the API response but the page doesn't react, suspect a bad key name rather than a bug in your logic.

IAM. The caller (your agent or backend) needs the relevant bedrock-agentcore:* actions, scoped to arn:aws:bedrock-agentcore:<region>:<account>:browser/*:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "bedrock-agentcore:CreateBrowser",
      "bedrock-agentcore:GetBrowser",
      "bedrock-agentcore:ListBrowsers",
      "bedrock-agentcore:DeleteBrowser",
      "bedrock-agentcore:StartBrowserSession",
      "bedrock-agentcore:GetBrowserSession",
      "bedrock-agentcore:ListBrowserSessions",
      "bedrock-agentcore:StopBrowserSession",
      "bedrock-agentcore:UpdateBrowserStream",
      "bedrock-agentcore:ConnectBrowserAutomationStream",
      "bedrock-agentcore:ConnectBrowserLiveViewStream"
    ],
    "Resource": "arn:aws:bedrock-agentcore:us-west-2:123456789012:browser/*"
  }]
}

Note the split: control-plane create/get/list/delete and data-plane start/stop/get/list sessions plus the Connect...Stream and UpdateBrowserStream actions. The two Connect* actions are what gate the automation and Live View WebSockets.

Recording is a custom-browser-only feature. When you create a custom browser you point recording at your own S3 bucket; AgentCore captures DOM, actions, console, and network so you can replay the session in the console. The browser's execution role needs S3 write permissions (s3:PutObject, s3:ListMultipartUploadParts, s3:AbortMultipartUpload), and its trust policy allows bedrock-agentcore.amazonaws.com to sts:AssumeRole, conditioned on aws:SourceAccount/aws:SourceArn.

client.create_browser(
    name="checkout-bot",
    networkConfiguration={"networkMode": "PUBLIC"},
    executionRoleArn="arn:aws:iam::123456789012:role/AgentCoreBrowserExec",
    recording={"enabled": True, "s3Location": {"bucket": "my-replays", "prefix": "sessions/"}},
)

# Data plane: start a session against it (or against aws.browser.v1)
client.start_browser_session(
    browserIdentifier="aws.browser.v1",
    sessionTimeoutSeconds=3600,
    viewPort={"height": 819, "width": 1456},
)

Web Bot Auth (Preview, [VOLATILE]). A draft IETF protocol (HTTP Message Signatures) that reduces CAPTCHA friction: when enabled, the browser signs each request and adds Signature, Signature-Agent, and Signature-Input headers. Preview vendors that honor it: Cloudflare, HUMAN Security, Akamai, DataDome. Enable it at create time — create_browser(..., browserSigning={'enabled': True}) (CLI --browser-signing '{"enabled": true}'). It's disabled by default, only helps on supported-vendor sites, and site owners can still block you. Since it is Preview, verify status on the live docs before relying on it.

The cost gotcha — stop your sessions. A session bills until its TTL even if you've walked away from it, and you cannot delete a browser that still has active sessions. Always stop sessions explicitly (or rely on the browser_session context manager, which stops on exit). Forgetting this is the most common way to run up a surprise bill.