# How to Add the Browser Tool to AWS Agent Core for Web Navigation

> Learn to add the AWS Agent Core Browser tool for automated web navigation, form filling, and data extraction with headless Chrome. Simplify AI agent web interactions.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: how-to-guide
- Published: 2026-07-01

---

**The AWS Agent Toolkit provides a managed Browser tool that lets AI agents drive headless Chrome instances through the AWS Agent Core runtime, enabling automated web navigation, form filling, and data extraction without self-hosted infrastructure.**

Adding web navigation capabilities to your AWS Agent Core deployment requires integrating the **Browser tool** from the `aws-agents` plugin. This capability, documented in [[`browser.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/browser.md)](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/skills/agents-build/references/browser.md), exposes a managed Chrome microVM service that agents interact with via the Chrome DevTools Protocol (CDP). The implementation abstracts away infrastructure management, allowing developers to focus on automation logic rather than browser provisioning.

## Architecture Overview

The Browser tool architecture spans four distinct layers, each handling specific responsibilities in the web navigation stack:

| Layer | Component | Role |
|:---|:---|:---|
| **Agent Core Runtime** | `BedrockAgentCoreApp` | Hosts the agent process, injects AWS credentials, and wires tools into the execution environment. |
| **Tool Wrapper** | `AgentCoreBrowser` (Strands) | Provides a high-level Python object (`browser_tool.browser`) that agents call directly. Hides low-level CDP plumbing. |
| **Managed Service** | `aws.browser.v1` | Regional AWS resource that spins up a Chrome microVM per session. Accessed via `bedrock-agentcore:*Browser*` IAM actions. |
| **Automation Frameworks** | Strands, Nova Act, Playwright | Strands provides reasoning-driven step selection; Nova Act uses an LLM-driven "act" loop; Playwright enables deterministic scripting. |

The **Browser** tool is a *managed* service, not a self-hosted container. Because AWS provisions resources on-demand, you need no CloudFormation or CDK templates—only properly scoped IAM permissions. Observability flows through CloudWatch logs under `/aws/bedrock-agentcore/browser/*`, with optional live-view streaming and S3 session recording for compliance and debugging.

## Session Lifecycle

Understanding the session lifecycle prevents resource leaks and unexpected costs. Each browser session follows this sequence:

1. **Start** – Call `browser_tool.browser` (Strands) or `browser_session(region)` (Nova Act/Playwright), which invokes `StartBrowserSession` via the AWS SDK.
2. **Connect** – Receive a WebSocket endpoint (`ws_url`) and connect via CDP.
3. **Drive** – Issue CDP commands through your chosen framework (navigate, click, type, evaluate JavaScript).
4. **Stop** – The context manager automatically calls `StopBrowserSession`. Leaked sessions incur charges until the 15-minute idle timeout (maximum 8-hour session limit).

The SDK enforces automatic cleanup when using context managers, but manual session handling risks leaving microVMs running.

## IAM & Security

The Browser tool requires explicit IAM permissions attached to the execution role of your Agent Core Runtime. The policy grants access to the `bedrock-agentcore` service for browser lifecycle operations:

```json
{
  "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/*"
  }]
}

```

Replace `<REGION>` and `<ACCOUNT_ID>` with your deployment values. The action list evolves with service updates; verify against the latest documentation in [`browser.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/browser.md).

## Implementation Paths

The Browser tool supports three distinct integration patterns. Choose based on your agent architecture and automation requirements.

### Path A: Strands Agent with Browser Tool

**Best for:** Standard AWS Agent Core deployments where the agent uses Strands for reasoning and tool selection.

The `AgentCoreBrowser` wrapper integrates seamlessly with the Strands framework, exposing a simple callable that the LLM invokes automatically:

```python
from strands import Agent
from strands_tools.browser import AgentCoreBrowser

# Initialize the Browser tool for a supported region

browser_tool = AgentCoreBrowser(region="us-west-2")

# Attach to agent; the LLM decides when to browse

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

# Execute task with automatic session management

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

```

*Key source:* [[`browser.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/browser.md)](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/skills/agents-build/references/browser.md) Path A section.

### Path B: Nova Act (LLM-Driven Automation)

**Best for:** Agents needing step-by-step reasoning without the full Strands framework.

Nova Act provides an "act" loop where the LLM decides each action iteratively:

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

def run_browser_task(prompt: str, start_url: str, api_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=api_key,
            starting_page=start_url,
        ) as nova:
            return nova.act(prompt)

# Execute complex multi-step task

print(run_browser_task(
    "Log in to example.com, navigate to the pricing page, and copy the price.",
    "https://example.com/login",
    "<YOUR_NOVA_ACT_KEY>"
))

```

*Key source:* [`browser.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/browser.md) Path B section.

### Path C: Playwright (Deterministic Scripting)

**Best for:** Fixed workflows, login flows, and scheduled scraping where LLM reasoning is unnecessary.

Connect Playwright directly to the managed Chrome instance for scriptable automation:

```python
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()

# Run synchronous scrape

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

```

*Key source:* [`browser.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/browser.md) Path C section.

## Best Practices

### Session Lifecycle Management

Always use context managers to ensure sessions terminate properly:

```python

# ✅ Correct – automatic cleanup via context manager

with browser_session(region) as client:
    ws_url, headers = client.generate_ws_headers()
    # ... automation logic ...

# ❌ Incorrect – leaked session on exception

client = BrowserClient(region=region)
client.start()

# ... if exception occurs, session remains billing until timeout ...

```

*Reference:* [`browser.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/browser.md) lines 84–101.

### Observability Configuration

Enable **live view** by including `ConnectBrowserLiveViewStream` in your IAM policy, then monitor sessions in the AWS Console. For **session recording**, create a custom browser configuration (not `aws.browser.v1`) with an S3 bucket destination. Recordings capture DOM state, click sequences, network traffic, and console logs for compliance auditing and debugging replay.

### VPC Deployment

When running Agent Core inside a VPC, configure the Browser service for VPC mode. Requirements include:
- Outbound internet access via NAT Gateway
- Service-linked role for the Browser resource
- Proper subnet and security group configuration

See [[`vpc.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/vpc.md)](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/skills/agents-build/references/vpc.md) for VPC-specific networking requirements.

## Summary

- The **Browser tool** in AWS Agent Core provides managed Chrome automation without infrastructure overhead
- Three integration paths exist: **Strands** (`AgentCoreBrowser`) for standard agents, **Nova Act** for LLM-driven stepwise reasoning, and **Playwright** for deterministic scripting
- Always use **context managers** (`with browser_session(...)`) to prevent costly session leaks
- Required IAM permissions cover `bedrock-agentcore:*Browser*` actions scoped to browser resources
- Observability options include CloudWatch logs, live-view streaming, and optional S3 session recordings

## Frequently Asked Questions

### What AWS regions support the Browser tool?

The Browser service is available in select AWS regions where Bedrock Agent Core operates. Check the latest regional availability in the [AWS documentation](https://docs.aws.amazon.com/bedrock/) or verify by attempting `StartBrowserSession` in your target region. The `us-west-2` region is commonly available for early access.

### How does the Browser tool differ from running Chrome in a Docker container?

The **Browser tool** is a fully managed AWS service (`aws.browser.v1`) that provisions ephemeral Chrome microVMs per session. Unlike self-hosted containers, you pay only for active session time with automatic scaling and no orchestration overhead. The service handles CDP endpoint management, security patching, and isolation between sessions.

### Can I use the Browser tool with existing Selenium scripts?

Direct Selenium support is not documented in the current [`browser.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/browser.md) reference. The supported frameworks are **Strands**, **Nova Act**, and **Playwright**. For Selenium compatibility, you would need to bridge the CDP WebSocket connection (`ws_url`) to Selenium's ChromeDriver, which is not officially supported.

### What happens if my agent crashes during a browser session?

Sessions without explicit `StopBrowserSession` calls remain active for **15 minutes** before automatic idle timeout (maximum session duration: **8 hours**). During this window, you incur charges for the running microVM. Using context managers (`with browser_session(...)`) ensures `StopBrowserSession` executes even during exceptions, minimizing orphaned resources.