feat(agentcore): enhance Browser & Code Interpreter toolkits with full session config, new tools, and telemetry

[kevin-orellana]

Summary

Enhances the AWS Bedrock AgentCore Browser and Code Interpreter toolkits to expose the full SDK feature surface — session configuration with typed dataclass support, new tool capabilities, and telemetry tracking.

Telemetry

• Add integration_source="crewai" to BrowserClient and CodeInterpreter constructors for customer acquisition tracking via User-Agent header

Session Configuration Passthrough (with SDK Typed Dataclass Support)

Expose all start() parameters so users can configure sessions at toolkit creation time. Previously only identifier was supported — all other SDK options were silently ignored.

All config parameters accept both SDK typed dataclasses and plain dicts, matching the SDK's own BrowserClient.start() signature. Typed dataclasses give users IDE autocomplete, validation at construction time, and convenience factory methods.

Browser — 5 new params on BrowserToolkit / create_browser_toolkit():

• session_timeout_seconds — session timeout in seconds (1–28800, default 3600)
• viewport — ViewportConfiguration or dict. Factory methods: .desktop_hd(), .laptop(), .mobile(), etc.
• proxy_configuration — ProxyConfiguration or dict. Proxy routing with optional auth via Secrets Manager
• extensions — list[BrowserExtension | dict]. S3-hosted browser extensions
• profile_configuration — ProfileConfiguration or dict. Persist cookies/local storage across sessions

Code Interpreter — 1 new param on CodeInterpreterToolkit / create_code_interpreter_toolkit():

• session_timeout_seconds — session timeout in seconds (default 900)

All params default to None (SDK defaults apply). No validation on our side — the SDK handles it.

Custom Sandbox Identifier

• Add optional identifier parameter to BrowserToolkit, CodeInterpreterToolkit, and BrowserSessionManager for custom browser/interpreter resources (VPC, recording, Web Bot Auth)
• Passed through to .start(identifier=...) on the underlying SDK clients

New Browser Tools (3)

• GenerateLiveViewUrlTool — generate a presigned URL for live browser viewing
• TakeControlTool — take manual control of the browser (disables automation)
• ReleaseControlTool — release manual control (re-enables automation, reconnects Playwright)

New Code Interpreter Tools (6)

• UploadFileTool / UploadFilesTool — upload files with optional semantic descriptions
• DownloadFileTool / DownloadFilesTool — download files from the sandbox
• InstallPackagesTool — install pip packages with optional --upgrade flag
• ClearContextTool — reset the Python execution context

Browser Session Manager

• Add reconnect_sync_browser() / reconnect_async_browser() for CDP reconnection after release_control()
• Add get_browser_client() / get_async_browser_client() accessors for the underlying BrowserClient
• Thread-safe session creation with per-key events to serialize without blocking unrelated callers

Usage Examples

# Browser with typed SDK dataclasses (recommended)
from bedrock_agentcore.tools import (
    ViewportConfiguration, ProxyConfiguration, ExternalProxy,
    ProfileConfiguration,
)

toolkit, tools = create_browser_toolkit(
    region="us-west-2",
    viewport=ViewportConfiguration.desktop_hd(),  # 1920x1080
    proxy_configuration=ProxyConfiguration(
        proxies=[ExternalProxy(server="proxy.corp.com", port=8080)],
        bypass_patterns=[".amazonaws.com"],
    ),
    profile_configuration=ProfileConfiguration(profile_identifier="my-profile"),
    session_timeout_seconds=7200,
)

# Browser with plain dicts (also works)
toolkit, tools = create_browser_toolkit(
    region="us-west-2",
    viewport={"width": 1920, "height": 1080},
    proxy_configuration={
        "proxies": [{"externalProxy": {"server": "proxy.corp.com", "port": 8080}}],
        "bypass": {"domainPatterns": [".amazonaws.com"]},
    },
    session_timeout_seconds=7200,
)

# Code interpreter with longer timeout
toolkit, tools = create_code_interpreter_toolkit(
    region="us-west-2",
    session_timeout_seconds=1800,
)

Test Plan

• 68 unit tests (all pass) covering telemetry, identifier passthrough, session config passthrough with both dicts and typed dataclasses (sync + async), all new tools, edge cases
• Live integration tests against real AgentCore sessions verifying:
  • Browser viewport 1920x1080 returned in session API response
  • Browser timeout 600s applied correctly
  • Code interpreter timeout 1800s applied correctly
  • Default timeouts (3600s browser, 900s CI) when no config specified

---

Note

Medium Risk
Medium risk because it changes how remote browser/interpreter sessions are created and managed (new start() kwargs, Playwright lifecycle tracking, CDP reconnection), which can affect runtime session stability and cleanup behavior.

Overview
Browser toolkit: Adds passthrough of full BrowserClient.start() session configuration (e.g. identifier, timeouts, viewport, proxy, extensions, profile) and tags sessions with integration_source="crewai". Introduces generate_live_view_url, take_control, and release_control tools; release_control now triggers a Playwright CDP reconnection via new BrowserSessionManager.reconnect_* helpers, and the manager now tracks/stops per-thread Playwright instances.

Code interpreter toolkit: Tags CodeInterpreter with integration_source="crewai", supports identifier/session_timeout_seconds passthrough to start(), and adds tools for uploading/downloading files, installing pip packages, and clearing interpreter context.

Adds comprehensive unit tests covering the new configuration forwarding, telemetry tagging, reconnection/control tools, and new code-interpreter utilities.

^{Written by Cursor Bugbot for commit e23da7d. This will update automatically on new commits. Configure here.}

[kevin-orellana]

Fixed in e23da7d — changed if self.identifier: to if self.identifier is not None: in both browser_session_manager.py (sync + async paths) and code_interpreter_toolkit.py. Now consistent with all other params.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Reconnect failure leaves session in corrupt state

Medium Severity

In reconnect_sync_browser (and reconnect_async_browser), old_browser.close() is called before attempting pw.chromium.connect_over_cdp. If reconnection fails, the exception propagates but _sync_sessions[thread_id] still references the now-closed old_browser. The session is left in a corrupt state — every subsequent browser tool call for that thread_id will operate on a dead browser object and fail, with no way to recover.

Additional Locations (1)

• lib/crewai-tools/src/crewai_tools/aws/bedrock/browser/browser_session_manager.py#L346-L378

 

[cursor]

Duplicated start_kwargs construction across sync and async

Low Severity

The 13-line start_kwargs construction block is identically duplicated between _create_async_browser_session and _create_sync_browser_session. If a new session config parameter is added, both copies must be updated in lockstep — a likely source of future inconsistency bugs. This logic could be extracted into a small helper method like _build_start_kwargs.

Additional Locations (1)

• lib/crewai-tools/src/crewai_tools/aws/bedrock/browser/browser_session_manager.py#L228-L242