/agents-build

browser

Add the AgentCore Browser tool so your agent can navigate web pages, fill forms, and extract information.

When to use

• Your agent needs to interact with a website that has no API
• Your agent needs to fill forms, scrape data, or drive a web app
• You want an isolated, session-scoped browser for the agent (not a shared one)
• You want live-view / recording / replay of what the browser did, for debugging or auditing

Do NOT use this reference for:

• Calling an API — use Gateway (agents-connect)
• Running code in a sandbox — see code-interpreter.md
• Serving browser-based UIs to users — that's a different problem (the AGUI protocol, not the Browser tool)

Mental model

The Browser tool is a managed Chrome instance, one per session, running in an isolated microVM. Your agent connects to it over WebSocket (via CDP — Chrome DevTools Protocol) and drives it with an automation framework. You pick the framework:

If you're adding browsing to a Strands agent, use AgentCoreBrowser and skip the framework decision — it wraps Nova Act under the hood and fits the agent-tool mental model.

If you're not using Strands, pick between Nova Act (reasoning-driven) and Playwright (script-driven) based on whether the task is open-ended or well-defined.

Sessions are ephemeral by default (reset after each use). Default timeout is 15 minutes, max 8 hours. You can run multiple concurrent sessions.

Prerequisites

• Python 3.10+
• bedrock-agentcore SDK installed
• IAM permissions for bedrock-agentcore:*Browser* actions (scope to your browser resource ARN in production)
• AWS region that supports Browser — check the docs for the current list
• For Strands path: model access for your chosen model (Claude Sonnet 4.x is the common default)
• For Nova Act path: a Nova Act API key from nova.amazon.com/act (US-based amazon.com accounts only at time of writing)

IAM policy skeleton (attach to the caller identity — your user, role, or AgentCore Runtime execution role):

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "BrowserAccess",
    "Effect": "Allow",
    "Action": [
      "bedrock-agentcore:CreateBrowser",
      "bedrock-agentcore:GetBrowser",
      "bedrock-agentcore:ListBrowsers",
      "bedrock-agentcore:StartBrowserSession",
      "bedrock-agentcore:StopBrowserSession",
      "bedrock-agentcore:GetBrowserSession",
      "bedrock-agentcore:ListBrowserSessions",
      "bedrock-agentcore:ConnectBrowserAutomationStream",
      "bedrock-agentcore:ConnectBrowserLiveViewStream"
    ],
    "Resource": "arn:aws:bedrock-agentcore:<REGION>:<ACCOUNT_ID>:browser/*"
  }]
}

Check current IAM action names against the docs — the list evolves.

Path A — Strands agent with the Browser tool (recommended for most)

from strands import Agent
from strands_tools.browser import AgentCoreBrowser

browser_tool = AgentCoreBrowser(region="<REGION>")

agent = Agent(tools=[browser_tool.browser])

result = agent("Find the release date of the latest AgentCore SDK on GitHub.")
print(result.message["content"][0]["text"])

Install: pip install bedrock-agentcore strands-agents strands-agents-tools

The agent decides when to use the browser, opens sessions on demand, and cleans them up. Under the hood, AgentCoreBrowser uses the AWS-managed aws.browser.v1 resource — no resource creation needed.

Dropping into an AgentCore Runtime entrypoint:

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent
from strands_tools.browser import AgentCoreBrowser
from model.load import load_model  # scaffolded by `agentcore create`
import os

app = BedrockAgentCoreApp()
REGION = os.getenv("AWS_REGION", "us-west-2")

@app.entrypoint
def invoke(payload, context):
    browser_tool = AgentCoreBrowser(region=REGION)
    agent = Agent(model=load_model(), tools=[browser_tool.browser])
    result = agent(payload.get("prompt", ""))
    return {"response": str(result)}

if __name__ == "__main__":
    app.run()

Path B — Nova Act for reasoning-driven tasks

Use when the task needs an LLM to decide each click/type step.

from bedrock_agentcore.tools.browser_client import browser_session
from nova_act import NovaAct

def run_browser_task(prompt: str, starting_page: str, nova_act_key: str, region: str = "us-west-2"):
    with browser_session(region) as client:
        ws_url, headers = client.generate_ws_headers()
        with NovaAct(
            cdp_endpoint_url=ws_url,
            cdp_headers=headers,
            nova_act_api_key=nova_act_key,
            starting_page=starting_page,
        ) as nova:
            return nova.act(prompt)

Install: pip install bedrock-agentcore nova-act boto3

The browser_session context manager handles start/stop. Do not leak sessions — always use the context manager or wrap raw BrowserClient calls in try/finally.

Credential handling: the Nova Act API key is a secret. If this is running inside an AgentCore Runtime agent, register it as a credential (agentcore add credential --name NovaAct --api-key ...) and retrieve it with @requires_api_key(provider_name="NovaAct"). Do not put it in runtime env vars. See agents-connect Path D.

Path C — Playwright for scripted automation

Use when the steps are fixed and you want deterministic behavior (logins, scrapes, automated tests).

import asyncio
from bedrock_agentcore.tools.browser_client import browser_session
from playwright.async_api import async_playwright

async def scrape_title(url: str, region: str = "us-west-2") -> str:
    async with async_playwright() as pw:
        with browser_session(region) as client:
            ws_url, headers = client.generate_ws_headers()
            browser = await pw.chromium.connect_over_cdp(ws_url, headers=headers)
            context = browser.contexts[0]
            page = context.pages[0]
            try:
                await page.goto(url)
                return await page.title()
            finally:
                await page.close()
                await browser.close()

print(asyncio.run(scrape_title("https://example.com")))

Install: pip install bedrock-agentcore playwright

Sync variant (sync_playwright) is also supported — pick based on whether your agent code is async.

Observability

Browser is observable by default:

• Live view — watch a running session in real time from the AWS console (Built-in tools → Browser → your session → "View live session"). You can take over control from the automation interactively.
• CloudWatch logs — /aws/bedrock-agentcore/browser/*
• Metrics — in AWS/BedrockAgentCore namespace

Session recording (DOM, clicks, console logs, network) is opt-in per browser. To enable:

1. Create a custom browser (not aws.browser.v1) with recording configured
2. Give its execution role s3:PutObject on your recording bucket
3. Recordings land in your S3 bucket and replay in the AWS console

The managed aws.browser.v1 resource does not record. Use custom browsers when you need audit trails.

Session lifecycle — always close

# Right — context manager
with browser_session(region) as client:
    ws_url, headers = client.generate_ws_headers()
    ...

# Also right — explicit try/finally
client = BrowserClient(region=region)
client.start()
try:
    ...
finally:
    client.stop()

# Wrong — leaked session
client = BrowserClient(region=region)
client.start()
...  # if this raises, the session sits idle until its 15-minute timeout

Sessions hold a microVM. Leaked sessions cost money until they time out. The context manager is non-negotiable for production.

VPC mode

If your agent runs in VPC mode, the Browser tool can also run in VPC. See vpc.md for the subnet + security group pattern (the same service-linked role covers Browser ENIs). Browser in VPC requires a NAT gateway for public-internet sites — public subnets don't give Browser internet access.

Common failures

"Access denied" starting a session: IAM is missing StartBrowserSession on the browser resource ARN. Check aws sts get-caller-identity matches the identity you attached the policy to.

"Model access denied" from a Strands agent: The browser tool itself is fine, but the agent's model isn't enabled. Go to Bedrock console → Model access → enable your model in the region.

Nova Act errors about API key: The key is US-amazon.com-accounts only at launch. If you're outside the US or using a work account, you can't use Nova Act yet — fall back to Playwright or Strands.

Browser session times out mid-task: Default is 15 minutes of idle time. Pass sessionTimeoutSeconds to StartBrowserSession (max 28800 = 8 hours). Don't use this to cover up agents that are slow — fix the agent or chunk the work.

Live view doesn't show your session: Live view requires ConnectBrowserLiveViewStream IAM permission. The session also has to be Ready, not Starting or Stopping.

Output

• Which framework fits (Strands vs Nova Act vs Playwright)
• Working code with session lifecycle handled
• IAM policy scoped to the browser resource
• Observability setup if needed (live view, recording)

Quality criteria

• Browser sessions are always wrapped in a context manager or try/finally — never leaked
• IAM is scoped to browser/* in the account, not Resource: "*"
• Nova Act API keys and other secrets use agentcore add credential + @requires_api_key, not env vars
• The code handles the case where the agent runs outside AgentCore Runtime (no .env.local, no credential provider) — typically by reading a local secret for development and the credential provider for production