Session API Reference

April 2, 2026 · View on GitHub

💡 Async Version: This documentation covers the synchronous API. For async/await support, see AsyncSession which provides the same functionality with async methods.

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 = "")

Session

class Session()

SyncSession represents a session in the AgentBay cloud environment.

init

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

fs

@property
def fs() -> FileSystem

Alias of file_system.

filesystem

@property
def filesystem() -> FileSystem

Alias of file_system.

files

@property
def files() -> FileSystem

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

def get_status() -> "SessionStatusResult"

Get basic session status synchronously.

Returns:

SessionStatusResult: Result containing session status only.

keep_alive

def keep_alive() -> OperationResult

Refresh the backend session idle timer.

This method calls the RefreshSessionIdleTime API.

delete

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

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

Sets the labels for this session synchronously.

get_labels

def get_labels() -> OperationResult

Gets the labels for this session synchronously.

info

def info() -> OperationResult

Get detailed information about this session synchronously.

get_link

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

Synchronously get a link associated with the current session.

list_mcp_tools

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

List MCP tools available for this session synchronously.

call_mcp_tool

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 synchronously.

get_metrics

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

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

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