Skip to content

session-params.md

Latest commit

 

History

History
312 lines (237 loc) · 11 KB

session-params.md

File metadata and controls

312 lines (237 loc) · 11 KB

SessionParams API Reference

BrowserSyncMode

class BrowserSyncMode(Enum)

Browser data synchronization mode.

Attributes:

MINIMAL: Synchronize only essential files (Cookies, Local State).

Smallest footprint. Sufficient for basic cookie-based auth. STANDARD: Synchronize login state and anti-risk-control data. Includes Cookies, localStorage, IndexedDB, saved passwords, preferences, HSTS, GPU cache, etc. Recommended for most scenarios.

MINIMAL

MINIMAL = "minimal"

Only Cookies + Local State

STANDARD

STANDARD = "standard"

Login state + anti-risk-control (recommended)

BrowserContext

class BrowserContext()

Browser context configuration for session.

This class provides browser context configuration for cloud sessions, supports browser fingerprint context persistence, supports automatic extension synchronization when ExtensionOption is provided.

Key Features:

  • Browser context binding for sessions
  • Automatic browser data upload on session end
  • Optional browser fingerprint integration with automatic context sync generation
  • Optional extension integration with automatic context sync generation
  • Clean API with ExtensionOption encapsulation

Attributes:

  • context_id str - ID of the browser context to bind to the session

  • auto_upload bool - Whether to automatically upload browser data when session ends

  • sync_mode BrowserSyncMode - Browser data synchronization mode

    • MINIMAL: Only sync essential files (Cookies, Local State) - fastest
    • STANDARD: Sync login state + anti-risk-control data - recommended fingerprint_context (Optional[BrowserFingerprintContext]): Browser fingerprint context configuration object containing fingerprint_context_id.

  • extension_option Optional[ExtensionOption] - Extension configuration object containing context_id and extension_ids.

  • extension_context_id Optional[str] - ID of the extension context for browser extensions. Set automatically from extension_option.

  • extension_ids Optional[List[str]] - List of extension IDs to synchronize. Set automatically from extension_option.

  • extension_context_syncs Optional[List[ContextSync]] - Auto-generated context syncs for extensions. None if no extension configuration provided, or List[ContextSync] if extensions are configured.

    Extension Configuration:

    • ExtensionOption: Pass an ExtensionOption object with context_id and extension_ids
    • No Extensions: Don't provide extension_option parameter (extension_context_syncs will be None)

    Usage Examples:

    # With extensions using ExtensionOption
from agentbay.extension import ExtensionOption

ext_option = ExtensionOption(
    context_id="my_extensions",
    extension_ids=["ext1", "ext2"]
)

browser_context = BrowserContext(
    context_id="browser_session",
    auto_upload=True,
    extension_option=ext_option
)

# Without extensions (minimal configuration)
browser_context = BrowserContext(
    context_id="browser_session",
    auto_upload=True
)
# extension_context_syncs will be None

init

def __init__(self, 
        context_id: str,
        auto_upload: bool = True,
        sync_mode: "BrowserSyncMode" = None,
        extension_option: Optional["ExtensionOption"] = None,
        fingerprint_context: Optional["BrowserFingerprintContext"] = None)

Initialize BrowserContext with optional extension support.

Arguments:

  • context_id str - ID of the browser context to bind to the session. This identifies the browser instance for the session.

  • auto_upload bool, optional - Whether to automatically upload browser data when the session ends. Defaults to True.

  • sync_mode BrowserSyncMode, optional - Browser data synchronization mode.

    • MINIMAL: Only sync essential files (Cookies, Local State) - fastest
    • STANDARD: Sync login state + anti-risk-control data (Cookies, localStorage, IndexedDB, passwords, preferences, HSTS, GPUCache, etc.) - recommended Defaults to MINIMAL.

    fingerprint_context (Optional[BrowserFingerprintContext], optional): Browser fingerprint context configuration object containing fingerprint_context_id. Defaults to None.

  • extension_option Optional[ExtensionOption], optional - Extension configuration object containing context_id and extension_ids. This encapsulates all extension-related configuration. Defaults to None. Fingerprint Configuration:

    • BrowserFingerprintContext: Use fingerprint_context parameter with a BrowserFingerprintContext object
    • No Fingerprint: Don't provide fingerprint_context parameter (fingerprint_context_sync will be None)

    Fingerprint Auto-generation:

    • fingerprint_context_sync is automatically generated when fingerprint_context is provided
    • fingerprint_context_sync will be None if no fingerprint_context is provided
    • fingerprint_context_sync will be a ContextSync if fingerprint_context is valid

    Extension Configuration:

    • ExtensionOption: Use extension_option parameter with an ExtensionOption object
    • No Extensions: Don't provide extension_option parameter

    Auto-generation:

    • extension_context_syncs is automatically generated when extension_option is provided
    • extension_context_syncs will be None if no extension_option is provided
    • extension_context_syncs will be a List[ContextSync] if extension_option is valid

Examples:

```python
# With extensions using ExtensionOption
from agentbay.extension import ExtensionOption

ext_option = ExtensionOption(
    context_id="my_extensions",
    extension_ids=["ext1", "ext2"]
)

browser_context = BrowserContext(
    context_id="browser_session",
    auto_upload=True,
    extension_option=ext_option
)

# Without extensions (minimal configuration)
browser_context = BrowserContext(
    context_id="browser_session",
    auto_upload=True
)
# extension_context_syncs will be None
```

get_extension_context_syncs

def get_extension_context_syncs() -> List[ContextSync]

Get context syncs for extensions.

Returns:

List[ContextSync]: Context sync configurations for extensions.

Returns empty list if no extensions configured.

get_fingerprint_context_sync

def get_fingerprint_context_sync() -> ContextSync

Get context sync for fingerprint.

Returns:

ContextSync: Context sync configurations for fingerprint.

Returns None if fingerprint configuration is invalid.

CreateSessionParams

class CreateSessionParams()

Parameters for creating a new session in the AgentBay cloud environment.

Attributes:

  • labels Optional[Dict[str, str]] - Custom labels for the Session. These can be used for organizing and filtering sessions.
  • idle_release_timeout Optional[int] - SDK-side idle release timeout in seconds. This parameter takes effect together with console-side MCP/user interaction idle timeouts. The cloud environment is automatically released only when all idle timeouts are reached (or when the single-run maximum duration is reached).
  • context_syncs Optional[List[ContextSync]] - List of context synchronization configurations that define how contexts should be synchronized and mounted.
  • browser_context Optional[BrowserContext] - Optional configuration for browser data synchronization.
  • policy_id Optional[str] - Policy id to apply when creating the session.
  • enable_browser_replay Optional[bool] - Whether to enable browser recording for the session. It is enabled by default, so if enable_browser_replay is False, set enable_record to False
  • extra_configs Optional[ExtraConfigs] - Advanced configuration parameters for mobile environments.
  • framework Optional[str] - Framework name for tracking (e.g., "langchain"). Defaults to empty string (direct call).
  • beta_network_id Optional[str] - Beta network ID to bind this session to.
  • load_skills Optional[bool] - Whether to load skills into the sandbox.
  • skill_names Optional[List[str]] - Skill names to load. Loads all visible skills when load_skills=True and this is not specified.

init

def __init__(self, labels: Optional[Dict[str, str]] = None,
             image_id: Optional[str] = None,
             idle_release_timeout: Optional[int] = None,
             context_syncs: Optional[List[ContextSync]] = None,
             browser_context: Optional[BrowserContext] = None,
             policy_id: Optional[str] = None,
             beta_network_id: Optional[str] = None,
             enable_browser_replay: Optional[bool] = None,
             extra_configs: Optional[ExtraConfigs] = None,
             framework: Optional[str] = None,
             load_skills: Optional[bool] = None,
             skill_names: Optional[List[str]] = None)

Initialize CreateSessionParams.

Arguments:

  • labels Optional[Dict[str, str]], optional - Custom labels for the Session. Defaults to None.
  • image_id Optional[str], optional - ID of the image to use for the session. Defaults to None.
  • idle_release_timeout Optional[int], optional - SDK-side idle release timeout in seconds. Defaults to 300.
  • context_syncs Optional[List[ContextSync]], optional - List of context synchronization configurations. Defaults to None.
  • browser_context Optional[BrowserContext], optional - Browser context configuration. If extension_ids are provided in BrowserContext, extension syncs will be automatically added. Defaults to None.
  • policy_id Optional[str], optional - Policy id to apply when creating the session. Defaults to None.
  • beta_network_id Optional[str], optional - Beta network ID to bind this session to. Defaults to None.
  • enable_browser_replay Optional[bool], optional - Whether to enable browser recording for the session. Defaults to False.
  • extra_configs Optional[ExtraConfigs], optional - Advanced configuration parameters for mobile environments. Defaults to None.
  • framework Optional[str], optional - Framework name for tracking (e.g., "langchain"). Defaults to None (empty string in tracking, indicating direct call).

ListSessionParams

class ListSessionParams()

Parameters for listing sessions with pagination support.

Attributes:

  • max_results int - Number of results per page.
  • next_token str - Token for the next page.
  • labels Dict[str, str] - Labels to filter by.

init

def __init__(self, max_results: int = 10,
             next_token: str = "",
             labels: Optional[Dict[str, str]] = None)

Initialize ListSessionParams with default values.

Arguments:

  • max_results int, optional - Number of results per page. Defaults to 10.
  • next_token str, optional - Token for the next page. Defaults to "".
  • labels Optional[Dict[str, str]], optional - Labels to filter by. Defaults to None.

See Also

Documentation generated automatically from source code using pydoc-markdown.