AsyncSession API Reference

March 23, 2026 · View on GitHub

💡 Sync Version: This documentation covers the asynchronous API. For synchronous operations, see Session.

⚡ Performance Advantage: Async API enables concurrent operations with 4-6x performance improvements for parallel tasks.

Session Management Guide - Detailed tutorial on session lifecycle and management

Overview

The Session class represents an active cloud environment instance in AgentBay. It provides access to all service modules (filesystem, command, browser, code, etc.) and manages the lifecycle of the cloud environment.

SessionStatusResult

class SessionStatusResult(ApiResponse)

Result of Session.get_status() (status only).

init

def __init__(self, request_id: str = "",
             http_status_code: int = 0,
             code: str = "",
             success: bool = False,
             status: str = "",
             error_message: str = "")

init

def __init__(self, session_id: str = "",
             resource_url: str = "",
             app_id: str = "",
             auth_code: str = "",
             connection_properties: str = "",
             resource_id: str = "",
             resource_type: str = "",
             ticket: str = "")

AsyncSession

class AsyncSession()

AsyncSession represents a session in the AgentBay cloud environment.

init

def __init__(self, agent_bay: "AsyncAgentBay", session_id: str)

fs

@property
def fs() -> AsyncFileSystem

Alias of file_system.

filesystem

@property
def filesystem() -> AsyncFileSystem

Alias of file_system.

files

@property
def files() -> AsyncFileSystem

Alias of file_system.

get_token

def get_token() -> str

.. deprecated

Internal SDK use only. Will be removed in a future version.

get_link_url

def get_link_url() -> str

.. deprecated

Internal SDK use only. Will be removed in a future version.

getToken

def getToken() -> str

.. deprecated

Internal SDK use only. Will be removed in a future version.

getLinkUrl

def getLinkUrl() -> str

.. deprecated

Internal SDK use only. Will be removed in a future version.

get_status

async def get_status() -> "SessionStatusResult"

Get basic session status asynchronously.

Returns:

SessionStatusResult: Result containing session status only.

keep_alive

async def keep_alive() -> OperationResult

Refresh the backend session idle timer.

This method calls the RefreshSessionIdleTime API.

delete

async def delete(sync_context: bool = False) -> DeleteResult

Delete this session and release all associated resources.

Arguments:

sync_context bool, optional - Whether to sync context data (trigger file uploads) before deleting the session. Defaults to False.

Returns:

DeleteResult: Result indicating success or failure with request ID.

success (bool): True if deletion succeeded
error_message (str): Error details if deletion failed
request_id (str): Unique identifier for this API request

Raises:

SessionError: If the deletion request fails or the response is invalid.

set_labels

async def set_labels(labels: Dict[str, str]) -> OperationResult

Sets the labels for this session asynchronously.

get_labels

async def get_labels() -> OperationResult

Gets the labels for this session asynchronously.

info

async def info() -> OperationResult

Get detailed information about this session asynchronously.

get_link

async def get_link(protocol_type: Optional[str] = None,
                   port: Optional[int] = None,
                   options: Optional[str] = None) -> OperationResult

Asynchronously get a link associated with the current session.

list_mcp_tools

async def list_mcp_tools(image_id: Optional[str] = None)

List MCP tools available for this session asynchronously.

call_mcp_tool

async def call_mcp_tool(tool_name: str,
                        args: Dict[str, Any],
                        read_timeout: Optional[int] = None,
                        connect_timeout: Optional[int] = None,
                        auto_gen_session: bool = False)

Call an MCP tool directly asynchronously.

get_metrics

async def get_metrics(
        read_timeout: Optional[int] = None,
        connect_timeout: Optional[int] = None) -> SessionMetricsResult

Get runtime metrics for this session.

The underlying service returns a JSON string. This method parses it and returns a structured result.

beta_pause

async def beta_pause(timeout: int = 600,
                     poll_interval: float = 2.0) -> SessionPauseResult

Pause the session and wait until it enters PAUSED state.

Notes:

This feature is currently in whitelist-only access. Contact agentbay_dev@alibabacloud.com to request access.

Arguments:

timeout: Timeout in seconds, default 600
poll_interval: Polling interval in seconds, default 2.0

Returns:

SessionPauseResult: Result containing request ID, success status, and session status

beta_resume

async def beta_resume(timeout: int = 600,
                      poll_interval: float = 2.0) -> SessionResumeResult

Resume the session and wait until it enters RUNNING state.

Arguments:

timeout: Timeout in seconds, default 600
poll_interval: Polling interval in seconds, default 2.0

Returns:

SessionResumeResult: Result containing request ID, success status, and session status