Input
diff --git a/frontend/src/components/chat/types.ts b/frontend/src/components/chat/types.ts
index 2bc5228c..5d44cc60 100644
--- a/frontend/src/components/chat/types.ts
+++ b/frontend/src/components/chat/types.ts
@@ -9,6 +9,8 @@ export interface ToolCall {
input: string
result?: string
status: ToolCallStatus
+ liveViewUrl?: string
+ streamEvents?: unknown[]
}
export type MessageSegment =
diff --git a/frontend/src/hooks/useToolRenderer.ts b/frontend/src/hooks/useToolRenderer.ts
index 51f74e68..5a1e6db9 100644
--- a/frontend/src/hooks/useToolRenderer.ts
+++ b/frontend/src/hooks/useToolRenderer.ts
@@ -6,6 +6,8 @@ export interface ToolRenderProps {
args: string
status: ToolCallStatus
result?: string
+ liveViewUrl?: string
+ streamEvents?: unknown[]
}
export type ToolRenderFn = (props: ToolRenderProps) => ReactNode
diff --git a/frontend/src/lib/agentcore-client/parsers/strands.ts b/frontend/src/lib/agentcore-client/parsers/strands.ts
index d2f0bb14..597e23af 100644
--- a/frontend/src/lib/agentcore-client/parsers/strands.ts
+++ b/frontend/src/lib/agentcore-client/parsers/strands.ts
@@ -16,6 +16,20 @@ export const parseStrandsChunk: ChunkParser = (line, callback) => {
try {
const json = JSON.parse(data)
+ // Tool stream events MUST be checked before text streaming,
+ // because strands wraps tool_stream_event with a top-level
+ // "data" string field that would otherwise match as text.
+ if (json.tool_stream_event) {
+ const ts = json.tool_stream_event
+ const toolUseId = ts.tool_use_id ?? ts.toolUseId ?? ts.tool_use?.toolUseId ?? ""
+ callback({
+ type: "tool_stream",
+ toolUseId,
+ data: ts.data,
+ })
+ return
+ }
+
// Text streaming
if (typeof json.data === "string") {
callback({ type: "text", content: json.data })
diff --git a/frontend/src/lib/agentcore-client/types.ts b/frontend/src/lib/agentcore-client/types.ts
index 68381abe..14e3999d 100644
--- a/frontend/src/lib/agentcore-client/types.ts
+++ b/frontend/src/lib/agentcore-client/types.ts
@@ -21,6 +21,7 @@ export type StreamEvent =
| { type: "tool_use_start"; toolUseId: string; name: string }
| { type: "tool_use_delta"; toolUseId: string; input: string }
| { type: "tool_result"; toolUseId: string; result: string }
+ | { type: "tool_stream"; toolUseId: string; data: unknown }
| { type: "message"; role: string; content: unknown[] }
| { type: "result"; stopReason: string }
| { type: "lifecycle"; event: string }
diff --git a/frontend/src/lib/agentcore-client/utils/sse.ts b/frontend/src/lib/agentcore-client/utils/sse.ts
index 74724cfc..ea9fe1e2 100644
--- a/frontend/src/lib/agentcore-client/utils/sse.ts
+++ b/frontend/src/lib/agentcore-client/utils/sse.ts
@@ -33,6 +33,11 @@ export async function readSSEStream(
parser(line, callback)
}
}
+
+ // Yield to the browser so React can flush state updates between chunks.
+ // Without this, multiple SSE events in one network chunk get batched
+ // into a single React render, making streaming appear instant.
+ await new Promise(resolve => setTimeout(resolve, 0))
}
// Process any remaining data in the buffer
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index f6690086..e1140cc2 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -4,15 +4,44 @@
import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import path from "path"
+import { viteStaticCopy } from "vite-plugin-static-copy"
+
+// Path to the vendored DCV SDK inside bedrock-agentcore
+const dcvSdkDir = path.resolve(
+ __dirname,
+ "node_modules/bedrock-agentcore/dist/src/tools/browser/live-view/nice-dcv-web-client-sdk"
+)
// https://vitejs.dev/config/
export default defineConfig({
- plugins: [react()],
+ plugins: [
+ react(),
+ viteStaticCopy({
+ targets: [
+ { src: path.resolve(dcvSdkDir, "dcvjs-esm"), dest: "nice-dcv-web-client-sdk" },
+ { src: path.resolve(dcvSdkDir, "dcv-ui"), dest: "nice-dcv-web-client-sdk" },
+ ],
+ }),
+ ],
resolve: {
alias: {
"@": path.resolve(__dirname, "./src"),
+ // DCV SDK bare specifier aliases — required for BrowserLiveView
+ dcv: path.resolve(dcvSdkDir, "dcvjs-esm/dcv.js"),
+ "dcv-ui": path.resolve(dcvSdkDir, "dcv-ui/dcv-ui.js"),
},
+ // Force shared deps to resolve from this project's node_modules,
+ // not from the vendored SDK path
+ dedupe: [
+ "react",
+ "react-dom",
+ "prop-types",
+ "@cloudscape-design/components",
+ "@cloudscape-design/global-styles",
+ "@cloudscape-design/design-tokens",
+ "@babel/runtime",
+ ],
},
build: {
diff --git a/infra-cdk/lib/backend-stack.ts b/infra-cdk/lib/backend-stack.ts
index 504bc15f..eb166f04 100644
--- a/infra-cdk/lib/backend-stack.ts
+++ b/infra-cdk/lib/backend-stack.ts
@@ -309,6 +309,29 @@ export class BackendStack extends cdk.NestedStack {
})
)
+ // Add Browser Tool permissions (for AgentCore Browser + OS-level actions)
+ agentRole.addToPolicy(
+ new iam.PolicyStatement({
+ sid: "BrowserToolAccess",
+ effect: iam.Effect.ALLOW,
+ actions: [
+ "bedrock-agentcore:StartBrowserSession",
+ "bedrock-agentcore:StopBrowserSession",
+ "bedrock-agentcore:GetBrowserSession",
+ "bedrock-agentcore:ListBrowserSessions",
+ "bedrock-agentcore:UpdateBrowserStream",
+ "bedrock-agentcore:ConnectBrowserAutomationStream",
+ "bedrock-agentcore:ConnectBrowserLiveViewStream",
+ "bedrock-agentcore:InvokeBrowser",
+ ],
+ resources: [
+ `arn:aws:bedrock-agentcore:${this.region}:aws:browser/*`,
+ `arn:aws:bedrock-agentcore:${this.region}:${this.account}:browser/*`,
+ `arn:aws:bedrock-agentcore:${this.region}:${this.account}:browser-custom/*`,
+ ],
+ })
+ )
+
// Add OAuth2 Credential Provider access for AgentCore Runtime
// The @requires_access_token decorator performs a two-stage process:
// 1. GetOauth2CredentialProvider - Looks up provider metadata (ARN, vendor config, grant types)
diff --git a/patterns/strands-browseruse-multiagent/Dockerfile b/patterns/strands-browseruse-multiagent/Dockerfile
new file mode 100644
index 00000000..92859c85
--- /dev/null
+++ b/patterns/strands-browseruse-multiagent/Dockerfile
@@ -0,0 +1,45 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim
+
+WORKDIR /app
+
+# Configure UV for container environment
+ENV UV_SYSTEM_PYTHON=1 \
+ UV_COMPILE_BYTECODE=1 \
+ DOCKER_CONTAINER=1 \
+ OTEL_PYTHON_LOG_CORRELATION=true \
+ PYTHONUNBUFFERED=1
+
+# Copy pyproject.toml and shared packages for installation
+COPY pyproject.toml .
+COPY gateway/ gateway/
+COPY tools/ agentcore_tools/
+
+# Copy and install agent-specific requirements first
+COPY patterns/strands-browseruse-multiagent/requirements.txt requirements.txt
+RUN uv pip install --no-cache -r requirements.txt && \
+ uv pip install --no-cache aws-opentelemetry-distro==0.16.0
+
+# Install FAST package with only core dependencies (no dev/agent optional deps)
+RUN uv pip install --no-cache -e . --no-deps && \
+ uv pip install --no-cache requests>=2.31.0
+
+# Create non-root user
+RUN useradd -m -u 1000 bedrock_agentcore
+USER bedrock_agentcore
+
+EXPOSE 8080
+
+# Copy agent code and tools
+COPY patterns/strands-browseruse-multiagent/agent.py .
+COPY patterns/strands-browseruse-multiagent/tools/ tools/
+COPY patterns/utils/ utils/
+
+# Healthcheck
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+ CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/ping', timeout=2)" || exit 1
+
+# Start agent with OpenTelemetry instrumentation
+CMD ["opentelemetry-instrument", "python", "-m", "agent"]
diff --git a/patterns/strands-browseruse-multiagent/README.md b/patterns/strands-browseruse-multiagent/README.md
new file mode 100644
index 00000000..fa8270f3
--- /dev/null
+++ b/patterns/strands-browseruse-multiagent/README.md
@@ -0,0 +1,114 @@
+# Strands Single Agent Pattern
+
+This pattern uses the [Strands Agents](https://github.com/strands-agents/strands-agents) framework to build a single agent with Gateway tool access, Code Interpreter, and AgentCore Memory for conversation history.
+
+## Features
+
+- **Token-Level Streaming**: True token-by-token streaming via `agent.stream_async()`
+- **AgentCore Memory**: Conversation history persisted across requests via `AgentCoreMemorySessionManager`, with optional long-term memory for cross-session fact recall
+- **Code Interpreter**: Secure Python execution via `StrandsCodeInterpreterTools`
+- **Gateway Integration**: Access Lambda-based tools through AgentCore Gateway (MCP protocol with OAuth2 auth)
+- **Secure Identity**: User identity extracted from validated JWT token (`RequestContext`), not from payload
+
+## Architecture
+
+```
+User Request
+ |
+BedrockAgentCoreApp (basic_agent.py)
+ |
+Strands Agent (Sonnet model via BedrockModel)
+ |
+ +-- AgentCore Memory (conversation history)
+ | AgentCoreMemorySessionManager
+ |
+ +-- Code Interpreter
+ | StrandsCodeInterpreterTools (execute_python_securely)
+ |
+ +-- Gateway MCP Client (streamable HTTP)
+ Lambda-based tools via AgentCore Gateway
+```
+
+## File Structure
+
+```
+patterns/strands-single-agent/
+├── basic_agent.py # Main entrypoint (BedrockAgentCoreApp)
+├── strands_code_interpreter.py # Strands @tool wrapper for Code Interpreter
+├── tools/
+│ └── strands_execute_python.py # Strands-specific tool implementation
+├── requirements.txt # Pinned dependencies
+└── Dockerfile # Container build (Python 3.13)
+```
+
+## Available Tools
+
+| Tool | Source | Description |
+|------|--------|-------------|
+| `execute_python_securely` | Code Interpreter | Execute Python code in a secure sandbox |
+| Gateway tools | AgentCore Gateway | Lambda-based tools discovered via MCP |
+
+## Model
+
+- **Agent**: `us.anthropic.claude-sonnet-4-5-20250929-v1:0` (Sonnet via Bedrock)
+
+## Streaming Events
+
+The agent yields SSE `data: {json}` lines via `agent.stream_async()`. The frontend parser at `frontend/src/lib/agentcore-client/parsers/strands.ts` handles these event types:
+
+| Event | Format | Description |
+|-------|--------|-------------|
+| Text | `{"data": "text"}` | Token-level text content |
+| Tool use start | `{"current_tool_use": {...}, "delta": {"toolUse": {"input": ""}}}` | Tool invocation begins |
+| Tool use delta | `{"current_tool_use": {...}, "delta": {"toolUse": {"input": "..."}}}` | Streaming tool input |
+| Tool result | `{"message": {"role": "user", "content": [{"toolResult": {...}}]}}` | Tool execution result |
+| Result | `{"result": {"stop_reason": "end_turn"}}` | Agent finished |
+| Lifecycle | `{"init_event_loop": true}` / `{"start_event_loop": true}` | Agent lifecycle events |
+
+## Memory Integration
+
+This pattern uses **AgentCore Memory** for conversation persistence and optional long-term recall:
+
+**Short-term memory** (always active):
+1. `MEMORY_ID` environment variable provides the memory resource ID
+2. `AgentCoreMemoryConfig` is initialized with `memory_id`, `session_id`, and `actor_id` (user ID)
+3. `AgentCoreMemorySessionManager` handles storing/retrieving conversation history
+4. Memory is tied to the `runtimeSessionId` from the client
+
+**Long-term memory** (opt-in via `use_long_term_memory: true` in `config.yaml`):
+1. The CDK stack passes `USE_LONG_TERM_MEMORY=true` to the agent runtime
+2. The agent configures a `RetrievalConfig` for the `/facts/{actorId}` namespace
+3. AgentCore extracts facts from conversations asynchronously and stores them per user (keyed by Cognito `userId`)
+4. On each turn, relevant facts are retrieved and injected into the agent context, enabling cross-session personalization
+5. Additional costs apply: $0.75/1,000 records stored + $0.50/1,000 retrieval calls
+
+See [Memory Integration Guide](../../docs/MEMORY_INTEGRATION.md) for full details.
+
+## Security
+
+- **User identity**: Extracted from the validated JWT token via `RequestContext`, not from the payload body
+- **STACK_NAME validation**: Validated for alphanumeric format before use in SSM parameter paths
+- **Payload validation**: Required fields (`prompt`, `runtimeSessionId`) validated before processing
+- **Gateway auth**: OAuth2 client credentials flow via Cognito for machine-to-machine authentication
+
+## Deployment
+
+```bash
+cd infra-cdk
+# Set pattern in config.yaml:
+# backend:
+# pattern: strands-single-agent
+# deployment_type: docker # or zip
+cdk deploy
+```
+
+Both Docker and ZIP deployment types are supported.
+
+## Dependencies
+
+```
+strands-agents==1.24.0
+mcp==1.26.0
+bedrock-agentcore[strands-agents]==1.2.0
+PyJWT[crypto]>=2.10.1
+```
diff --git a/patterns/strands-browseruse-multiagent/agent.py b/patterns/strands-browseruse-multiagent/agent.py
new file mode 100644
index 00000000..0f8f60d3
--- /dev/null
+++ b/patterns/strands-browseruse-multiagent/agent.py
@@ -0,0 +1,145 @@
+"""Strands agent with Gateway MCP tools, Memory, Code Interpreter, and Browser."""
+
+import json
+import logging
+import os
+
+from bedrock_agentcore.memory.integrations.strands.config import (
+ AgentCoreMemoryConfig,
+ RetrievalConfig,
+)
+from bedrock_agentcore.memory.integrations.strands.session_manager import (
+ AgentCoreMemorySessionManager,
+)
+from bedrock_agentcore.runtime import BedrockAgentCoreApp, RequestContext
+from strands import Agent
+from strands.models import BedrockModel
+from tools.gateway import create_gateway_mcp_client
+from utils.auth import extract_user_id_from_context
+
+from tools.browser import StrandsBrowserTools
+from tools.code_interpreter import StrandsCodeInterpreterTools
+
+logger = logging.getLogger(__name__)
+
+app = BedrockAgentCoreApp()
+
+SYSTEM_PROMPT = (
+ "You are a helpful assistant with access to tools via the Gateway, "
+ "Code Interpreter, and Browser. "
+ "When asked about your tools, list them and explain what they do."
+)
+
+
+def _create_session_manager(
+ user_id: str, session_id: str
+) -> AgentCoreMemorySessionManager:
+ """Create an AgentCore memory session manager, optionally with long-term semantic retrieval.
+
+ When the USE_LONG_TERM_MEMORY environment variable is "true", configures retrieval
+ from the /facts/{actorId} namespace so the agent recalls facts across sessions.
+ When false (default), only short-term memory (conversation history) is active,
+ avoiding the additional storage and retrieval costs of long-term memory.
+
+ Args:
+ user_id: Unique identifier for the user (actor), extracted from the JWT sub claim.
+ session_id: Unique identifier for the current conversation session.
+
+ Returns:
+ An AgentCoreMemorySessionManager bound to the user and session.
+ """
+ memory_id = os.environ.get("MEMORY_ID")
+ if not memory_id:
+ raise ValueError("MEMORY_ID environment variable is required")
+
+ use_ltm = os.environ.get("USE_LONG_TERM_MEMORY", "false").lower() == "true"
+
+ top_k = int(os.environ.get("LTM_TOP_K", "10"))
+ relevance_score = float(os.environ.get("LTM_RELEVANCE_SCORE", "0.3"))
+
+ # Only pass retrieval_config when LTM is explicitly enabled.
+ # Omitting it means the session manager uses short-term memory only,
+ # which avoids the $0.50/1,000 retrieval and $0.75/1,000 storage costs.
+ retrieval_config = (
+ {
+ "/facts/{actorId}": RetrievalConfig(
+ top_k=top_k,
+ relevance_score=relevance_score,
+ )
+ }
+ if use_ltm
+ else None
+ )
+
+ config = AgentCoreMemoryConfig(
+ memory_id=memory_id,
+ session_id=session_id,
+ actor_id=user_id,
+ retrieval_config=retrieval_config,
+ )
+ return AgentCoreMemorySessionManager(
+ agentcore_memory_config=config,
+ region_name=os.environ.get("AWS_DEFAULT_REGION", "us-east-1"),
+ )
+
+
+def create_strands_agent(user_id: str, session_id: str) -> Agent:
+ """Create a Strands agent with Gateway tools, memory, Code Interpreter, and Browser."""
+
+ bedrock_model = BedrockModel(
+ model_id="us.anthropic.claude-sonnet-4-5-20250929-v1:0", temperature=0.1
+ )
+
+ session_manager = _create_session_manager(user_id, session_id)
+
+ region = os.environ.get("AWS_DEFAULT_REGION", "us-east-1")
+ code_tools = StrandsCodeInterpreterTools(region)
+ browser_tools = StrandsBrowserTools(region)
+
+ gateway_client = create_gateway_mcp_client()
+
+ return Agent(
+ name="strands_agent",
+ system_prompt=SYSTEM_PROMPT,
+ tools=[
+ gateway_client,
+ code_tools.execute_python_securely,
+ browser_tools.browser,
+ ],
+ model=bedrock_model,
+ session_manager=session_manager,
+ trace_attributes={"user.id": user_id, "session.id": session_id},
+ )
+
+
+@app.entrypoint
+async def invocations(payload, context: RequestContext):
+ """Main entrypoint — called by AgentCore Runtime on each request.
+
+ Extracts user ID from the validated JWT token (not the payload body)
+ to prevent impersonation via prompt injection.
+ """
+ user_query = payload.get("prompt")
+ session_id = payload.get("runtimeSessionId")
+
+ if not all([user_query, session_id]):
+ yield {
+ "status": "error",
+ "error": "Missing required fields: prompt or runtimeSessionId",
+ }
+ return
+
+ try:
+ user_id = extract_user_id_from_context(context)
+ agent = create_strands_agent(user_id, session_id)
+
+ async for event in agent.stream_async(user_query):
+ yield json.loads(json.dumps(dict(event), default=str))
+
+ except Exception as e:
+ logger.exception("Agent run failed")
+ yield {"status": "error", "error": str(e)}
+
+
+if __name__ == "__main__":
+ app.run()
diff --git a/patterns/strands-browseruse-multiagent/requirements.txt b/patterns/strands-browseruse-multiagent/requirements.txt
new file mode 100644
index 00000000..c96e43f5
--- /dev/null
+++ b/patterns/strands-browseruse-multiagent/requirements.txt
@@ -0,0 +1,9 @@
+# Strands agent with browser-use for browser automation
+strands-agents==1.35.0
+strands-agents-tools==0.4.1
+bedrock-agentcore==1.4.7
+mcp==1.26.0
+PyJWT[crypto]==2.12.1
+# browser-use + Claude for browser automation
+browser-use>=0.12.0
+nest-asyncio>=1.5.0
diff --git a/patterns/strands-browseruse-multiagent/tools/__init__.py b/patterns/strands-browseruse-multiagent/tools/__init__.py
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/patterns/strands-browseruse-multiagent/tools/__init__.py
@@ -0,0 +1 @@
+
diff --git a/patterns/strands-browseruse-multiagent/tools/browser.py b/patterns/strands-browseruse-multiagent/tools/browser.py
new file mode 100644
index 00000000..9da31ab1
--- /dev/null
+++ b/patterns/strands-browseruse-multiagent/tools/browser.py
@@ -0,0 +1,262 @@
+"""Strands browser tool — browser-use + Claude + AgentCore Browser.
+
+Streams the live view URL as a tool_stream_event so the frontend can show
+a 'Watch live' link while the browser is running.
+
+Session is reused across tool calls (same pattern as Code Interpreter).
+Delegates session management to the shared BrowserTools core.
+
+The browser-use Browser instance is kept alive across calls so that
+browser-use preserves its internal state (agent memory, page context,
+action history) between tasks — following the browser-use recommended
+pattern for chained/follow-up tasks.
+"""
+
+import logging
+import os
+from typing import Any, AsyncGenerator, Dict, Optional
+
+from agentcore_tools.browser.browser_tools import BrowserTools
+from strands import tool
+
+logger = logging.getLogger(__name__)
+
+REGION = os.environ.get("AWS_DEFAULT_REGION", "us-east-1")
+MODEL = os.environ.get(
+ "BROWSER_USE_MODEL", "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
+)
+
+
+class StrandsBrowserTools:
+ """Strands wrapper for AgentCore Browser using browser-use + Claude.
+
+ Uses the shared BrowserTools core for session lifecycle, same way
+ StrandsCodeInterpreterTools delegates to CodeInterpreterTools.
+
+ The browser-use Browser instance is kept alive across tool calls
+ so that agent memory, page context, and action history persist
+ between tasks (browser-use recommended pattern).
+ """
+
+ def __init__(self, region: str = REGION):
+ self.core_tools = BrowserTools(region)
+ self._browser_session: Optional[Any] = None
+ self._agent: Optional[Any] = None
+ self._llm: Optional[Any] = None
+
+ async def _get_browser_session(self):
+ """Get or create the browser-use Browser instance (kept alive across calls)."""
+ if self._browser_session is None:
+ from browser_use import Browser, BrowserProfile
+
+ ws_url, headers = self.core_tools.start_session()
+ browser_profile = BrowserProfile(
+ headers=headers, window_size={"width": 1380, "height": 720}
+ )
+ self._browser_session = Browser(
+ cdp_url=ws_url, browser_profile=browser_profile
+ )
+ await self._browser_session.start()
+ logger.info("Started browser-use session (kept alive for reuse)")
+ return self._browser_session
+
+ def _get_llm(self):
+ """Get or create the LLM instance (reused across calls)."""
+ if self._llm is None:
+ from browser_use.llm import ChatAnthropicBedrock
+
+ self._llm = ChatAnthropicBedrock(
+ model=MODEL, aws_region=self.core_tools.region
+ )
+ return self._llm
+
+ async def cleanup(self):
+ """Stop browser-use session and AgentCore browser session."""
+ if self._browser_session:
+ try:
+ await self._browser_session.kill()
+ logger.info("browser-use session killed")
+ except Exception:
+ pass
+ self._browser_session = None
+ self._agent = None
+ self._llm = None
+ self.core_tools.cleanup()
+
+ @property
+ def browser(self):
+ tool_self = self
+
+ @tool
+ async def browser(
+ task: str, starting_url: str
+ ) -> AsyncGenerator[Dict[str, Any], None]:
+ """
+ Delegate a browser automation task to a browser-use sub-agent that
+ autonomously controls a real browser (clicks, types, scrolls, navigates).
+
+ IMPORTANT — how to write a good task:
+ - Send the COMPLETE task with ALL steps in a single call. The sub-agent
+ handles multi-step workflows on its own.
+ - Be specific: state the goal, what to extract, and the desired output format.
+ - Include context: URLs, search terms, criteria, credentials context.
+ - Add fallbacks: what to do if the primary approach fails.
+ - Set constraints: max results, date ranges, scope limits.
+
+ Good task example:
+ task: "Search for 'wireless headphones under $50', extract the name,
+ price, and star rating of the top 3 results. If fewer than 3
+ results match, include the closest alternatives."
+ starting_url: "https://www.amazon.com"
+
+ Bad task example:
+ task: "Search for headphones" (too vague — no output format, no criteria)
+
+ DO NOT:
+ - Give low-level UI instructions like "click the search button" or
+ "type in the text field". The sub-agent figures out UI interactions.
+ - Split a single workflow into multiple calls unless you need to process
+ intermediate results yourself before the next step.
+
+ The browser session persists across calls — cookies, login state, and open
+ tabs carry over. Use multiple calls when you need to reason about
+ intermediate results between steps.
+
+ Args:
+ task: Complete, detailed description of what to accomplish, including
+ all steps, expected output format, and fallback instructions.
+ starting_url: URL to navigate to before starting the task.
+
+ Yields:
+ Intermediate events (e.g. live_view_url) while the task runs.
+
+ Returns:
+ Final dict with status, response, and live_view_url.
+ """
+ from browser_use import Agent as BrowserAgent
+
+ try:
+ browser_session = await tool_self._get_browser_session()
+ live_view_url = tool_self.core_tools.get_live_view_url()
+
+ # Yield the live view URL so the frontend can show a link
+ yield {"type": "browser_live_view", "live_view_url": live_view_url}
+
+ llm = tool_self._get_llm()
+ full_task = f"Start at {starting_url}. {task}"
+
+ if tool_self._agent is None:
+ # First call — create the agent
+ tool_self._agent = BrowserAgent(
+ task=full_task,
+ llm=llm,
+ browser_session=browser_session,
+ )
+ else:
+ # Subsequent calls — chain task, preserving agent memory
+ tool_self._agent.add_new_task(full_task)
+
+ # Use asyncio.Queue for immediate streaming — hooks put
+ # each step into the queue, and the generator yields from
+ # the queue without polling delay.
+ import asyncio
+
+ step_queue: asyncio.Queue = asyncio.Queue()
+ step_count_tracker = {"count": 0}
+
+ async def on_step_start_hook(agent):
+ """Called BEFORE each step — yields a 'thinking' event."""
+ step_num = step_count_tracker["count"] + 1
+
+ # Get current URL if available
+ current_url = ""
+ if hasattr(agent, "history") and agent.history:
+ urls = agent.history.urls()
+ if urls:
+ current_url = urls[-1] or ""
+
+ await step_queue.put(
+ {
+ "type": "browser_action",
+ "extracted_content": f"Step {step_num}: Thinking..."
+ + (f" (on {current_url})" if current_url else ""),
+ "step": step_num,
+ "phase": "start",
+ }
+ )
+
+ async def on_step_end_hook(agent):
+ """Called AFTER each step — yields the completed action."""
+ if not hasattr(agent, "history") or not agent.history:
+ return
+
+ new_count = agent.history.number_of_steps()
+ old_count = step_count_tracker["count"]
+ if new_count <= old_count:
+ return
+
+ action_names = agent.history.action_names()
+ extracted = agent.history.extracted_content()
+ urls = agent.history.urls()
+
+ for i in range(old_count, new_count):
+ parts = []
+ if i < len(action_names):
+ parts.append(action_names[i])
+ if i < len(urls) and urls[i]:
+ parts.append(f"@ {urls[i]}")
+ if i < len(extracted) and extracted[i]:
+ parts.append(f"→ {extracted[i]}")
+
+ summary = (
+ " ".join(parts) if parts else f"Step {i + 1} completed"
+ )
+ await step_queue.put(
+ {
+ "type": "browser_action",
+ "extracted_content": summary,
+ "step": i + 1,
+ "phase": "end",
+ }
+ )
+
+ step_count_tracker["count"] = new_count
+
+ # Run the agent with both hooks in a background task
+ agent_task = asyncio.create_task(
+ tool_self._agent.run(
+ on_step_start=on_step_start_hook,
+ on_step_end=on_step_end_hook,
+ )
+ )
+
+ # Yield steps from the queue as they arrive
+ while not agent_task.done():
+ try:
+ step = await asyncio.wait_for(step_queue.get(), timeout=0.5)
+ yield step
+ except asyncio.TimeoutError:
+ continue
+
+ # Get the final result (may raise if agent failed)
+ result = await agent_task
+
+ # Drain any remaining steps from the queue
+ while not step_queue.empty():
+ yield step_queue.get_nowait()
+
+ yield {
+ "status": "success",
+ "response": str(result),
+ "live_view_url": live_view_url,
+ }
+
+ except Exception as e:
+ logger.exception("Browser task failed")
+ yield {
+ "status": "error",
+ "error": str(e),
+ "live_view_url": tool_self.core_tools.get_live_view_url(),
+ }
+
+ return browser
diff --git a/patterns/strands-browseruse-multiagent/tools/code_interpreter.py b/patterns/strands-browseruse-multiagent/tools/code_interpreter.py
new file mode 100644
index 00000000..35c2dbe5
--- /dev/null
+++ b/patterns/strands-browseruse-multiagent/tools/code_interpreter.py
@@ -0,0 +1,39 @@
+"""Strands-specific wrapper for Code Interpreter - import shim."""
+
+from agentcore_tools.code_interpreter.code_interpreter_tools import CodeInterpreterTools
+from strands import tool
+
+
+class StrandsCodeInterpreterTools:
+ """Strands wrapper for Code Interpreter tools."""
+
+ def __init__(self, region: str):
+ """
+ Initialize Strands Code Interpreter tools.
+
+ Args:
+ region: AWS region for code interpreter
+ """
+ self.core_tools = CodeInterpreterTools(region)
+
+ def cleanup(self):
+ """
+ Clean up code interpreter session.
+
+ Note: AgentCore automatically cleans up inactive sessions after timeout,
+ so manual cleanup is optional but recommended for immediate resource release.
+ """
+ self.core_tools.cleanup()
+
+ @tool
+ def execute_python_securely(self, code: str) -> str:
+ """
+ Execute Python code in a secure AgentCore CodeInterpreter sandbox.
+
+ Args:
+ code: Python code to execute
+
+ Returns:
+ JSON string with execution result
+ """
+ return self.core_tools.execute_python_securely(code)
diff --git a/patterns/strands-browseruse-multiagent/tools/gateway.py b/patterns/strands-browseruse-multiagent/tools/gateway.py
new file mode 100644
index 00000000..9a559f1b
--- /dev/null
+++ b/patterns/strands-browseruse-multiagent/tools/gateway.py
@@ -0,0 +1,67 @@
+"""AgentCore Gateway MCP client with OAuth2 authentication."""
+
+import logging
+import os
+
+from bedrock_agentcore.identity.auth import requires_access_token
+from mcp.client.streamable_http import streamablehttp_client
+from strands.tools.mcp import MCPClient
+from utils.ssm import get_ssm_parameter
+
+logger = logging.getLogger(__name__)
+
+
+# OAuth2 Credential Provider decorator from AgentCore Identity SDK.
+# Automatically retrieves OAuth2 access tokens from the Token Vault (with caching)
+# or fetches fresh tokens from the configured OAuth2 provider when expired.
+# The provider_name references an OAuth2 Credential Provider registered in AgentCore Identity.
+@requires_access_token(
+ provider_name=os.environ["GATEWAY_CREDENTIAL_PROVIDER_NAME"],
+ auth_flow="M2M",
+ scopes=[],
+)
+def _fetch_gateway_token(access_token: str) -> str:
+ """Fetch OAuth2 token for Gateway authentication.
+
+ The @requires_access_token decorator handles token retrieval and refresh:
+ 1. Token Retrieval: Calls GetResourceOauth2Token API to fetch token from Token Vault
+ 2. Automatic Refresh: Uses refresh tokens to renew expired access tokens
+ 3. Error Orchestration: Handles missing tokens and OAuth flow management
+
+ For M2M (Machine-to-Machine) flows, the decorator uses Client Credentials grant type.
+ The provider_name must match the Name field in the CDK OAuth2CredentialProvider resource.
+
+ Must be synchronous — called inside the MCPClient lambda factory.
+ If it were async, the lambda would receive a coroutine object instead of a string,
+ breaking authentication.
+ """
+ return access_token
+
+
+def create_gateway_mcp_client() -> MCPClient:
+ """Create MCP client for AgentCore Gateway with OAuth2 authentication.
+
+ MCP (Model Context Protocol) is how agents communicate with tool providers.
+ This creates a client that can talk to the AgentCore Gateway using OAuth2
+ authentication. The Gateway then provides access to Lambda-based tools.
+
+ Avoids the "closure trap" by calling _fetch_gateway_token() inside the lambda
+ factory. This ensures a fresh token is fetched on every MCP reconnection,
+ preventing stale token errors.
+ """
+ stack_name = os.environ.get("STACK_NAME")
+ if not stack_name:
+ raise ValueError("STACK_NAME environment variable is required")
+ if not stack_name.replace("-", "").replace("_", "").isalnum():
+ raise ValueError("Invalid STACK_NAME format")
+
+ gateway_url = get_ssm_parameter(f"/{stack_name}/gateway_url")
+ logger.info("[GATEWAY] URL: %s", gateway_url)
+
+ return MCPClient(
+ lambda: streamablehttp_client(
+ url=gateway_url,
+ headers={"Authorization": f"Bearer {_fetch_gateway_token()}"},
+ ),
+ prefix="gateway",
+ )
diff --git a/tools/browser/__init__.py b/tools/browser/__init__.py
new file mode 100644
index 00000000..43e62efa
--- /dev/null
+++ b/tools/browser/__init__.py
@@ -0,0 +1 @@
+from .browser_tools import BrowserTools as BrowserTools
diff --git a/tools/browser/browser_tools.py b/tools/browser/browser_tools.py
new file mode 100644
index 00000000..1a5b2407
--- /dev/null
+++ b/tools/browser/browser_tools.py
@@ -0,0 +1,184 @@
+"""Core Browser tools for AgentCore — generic session management and capabilities.
+
+Framework-agnostic. No Strands, no browser-use, no Nova Act.
+Pattern-specific wrappers (e.g. patterns/strands-browseruse-multiagent/tools/browser.py)
+use this class for session lifecycle and layer their automation library on top.
+
+Follows the same lazy-init + reuse pattern as CodeInterpreterTools.
+"""
+
+import base64
+import logging
+from typing import Any, Dict, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+class BrowserTools:
+ """
+ AgentCore Browser session manager.
+
+ Responsibilities:
+ - Start / stop a single browser session (reused across calls)
+ - Expose CDP connection details (ws_url, headers) for any automation library
+ - Generate presigned live view URL for DCV streaming
+ - Human take-over / release
+ - OS-level actions (screenshot, mouse, keyboard) via InvokeBrowser API
+ """
+
+ def __init__(self, region: str):
+ self.region = region
+ self._client = None
+ self._runtime_client = None
+
+ # ── Session Lifecycle ────────────────────────────────────────────────────
+
+ def _get_client(
+ self,
+ browser_id: Optional[str] = None,
+ session_timeout_seconds: int = 3600,
+ viewport: Optional[Dict[str, int]] = None,
+ ):
+ """Lazy-create the BrowserClient. Reused on subsequent calls."""
+ if self._client is None:
+ from bedrock_agentcore.tools.browser_client import BrowserClient
+
+ self._client = BrowserClient(region=self.region)
+ kwargs: Dict[str, Any] = {
+ "session_timeout_seconds": session_timeout_seconds,
+ "viewport": viewport,
+ }
+ if browser_id:
+ kwargs["identifier"] = browser_id
+ self._client.start(**{k: v for k, v in kwargs.items() if v is not None})
+ logger.info(f"Started browser session in {self.region}")
+ return self._client
+
+ def start_session(
+ self,
+ browser_id: Optional[str] = None,
+ session_timeout_seconds: int = 3600,
+ viewport: Optional[Dict[str, int]] = None,
+ ) -> Tuple[str, Dict[str, str]]:
+ """Start (or reuse) a session and return CDP (ws_url, headers)."""
+ client = self._get_client(browser_id, session_timeout_seconds, viewport)
+ return client.generate_ws_headers()
+
+ def cleanup(self):
+ """Stop the browser session. AgentCore also auto-cleans after timeout."""
+ if self._client:
+ try:
+ self._client.stop()
+ logger.info("Browser session stopped")
+ except Exception as e:
+ logger.warning(f"Error stopping browser session: {e}")
+ finally:
+ self._client = None
+
+ @property
+ def browser_id(self) -> Optional[str]:
+ return self._client.identifier if self._client else None
+
+ @property
+ def session_id(self) -> Optional[str]:
+ return self._client.session_id if self._client else None
+
+ # ── Live View ────────────────────────────────────────────────────────────
+
+ def get_live_view_url(self, expires: int = 300) -> Optional[str]:
+ """Presigned DCV live view URL, or None if no active session."""
+ if not self._client:
+ return None
+ return self._client.generate_live_view_url(expires=expires)
+
+ # ── Human Take-Over ──────────────────────────────────────────────────────
+
+ def take_control(self):
+ """Pause agent automation so a human can take over via live view."""
+ if self._client:
+ self._client.take_control()
+ logger.info("Human took control of browser")
+
+ def release_control(self):
+ """Resume agent automation after human take-over."""
+ if self._client:
+ self._client.release_control()
+ logger.info("Agent resumed control of browser")
+
+ # ── OS-Level Actions ─────────────────────────────────────────────────────
+
+ def _get_runtime_client(self):
+ if not self._runtime_client:
+ import boto3
+
+ self._runtime_client = boto3.client(
+ "bedrock-agentcore", region_name=self.region
+ )
+ return self._runtime_client
+
+ def _invoke(self, action: Dict[str, Any]) -> Dict[str, Any]:
+ if not self._client:
+ raise RuntimeError("No active browser session. Call start_session() first.")
+ client = self._get_runtime_client()
+ response = client.invoke_browser(
+ browserIdentifier=self._client.identifier,
+ sessionId=self._client.session_id,
+ action=action,
+ )
+ return response.get("result", {})
+
+ def screenshot(self, format: str = "PNG") -> bytes:
+ """Take a screenshot. Returns raw bytes."""
+ result = self._invoke({"screenshot": {"format": format}})
+ img_data = result.get("screenshot", {}).get("data", b"")
+ if isinstance(img_data, str):
+ return base64.b64decode(img_data)
+ return img_data
+
+ def screenshot_base64(self, format: str = "PNG") -> str:
+ """Screenshot as base64 string (for sending to LLMs)."""
+ return base64.b64encode(self.screenshot(format=format)).decode()
+
+ def mouse_click(self, x: int, y: int, button: str = "LEFT", click_count: int = 1):
+ self._invoke(
+ {
+ "mouseClick": {
+ "x": x,
+ "y": y,
+ "button": button,
+ "clickCount": click_count,
+ }
+ }
+ )
+
+ def mouse_move(self, x: int, y: int):
+ self._invoke({"mouseMove": {"x": x, "y": y}})
+
+ def mouse_drag(
+ self, start_x: int, start_y: int, end_x: int, end_y: int, button: str = "LEFT"
+ ):
+ self._invoke(
+ {
+ "mouseDrag": {
+ "startX": start_x,
+ "startY": start_y,
+ "endX": end_x,
+ "endY": end_y,
+ "button": button,
+ }
+ }
+ )
+
+ def scroll(self, x: int, y: int, delta_x: int = 0, delta_y: int = -300):
+ self._invoke(
+ {"mouseScroll": {"x": x, "y": y, "deltaX": delta_x, "deltaY": delta_y}}
+ )
+
+ def type_text(self, text: str):
+ self._invoke({"keyType": {"text": text}})
+
+ def key_press(self, key: str, presses: int = 1):
+ self._invoke({"keyPress": {"key": key, "presses": presses}})
+
+ def key_shortcut(self, *keys: str):
+ self._invoke({"keyShortcut": {"keys": list(keys)}})