Skip to content

Session API Reference ​

Overview ​

The Session module provides methods for creating, managing, and terminating sessions in the AGB cloud environment. Sessions are the foundation for all operations.

Session ​

python
class Session()

Session represents a session in the AGB cloud environment.

python
def get_link_url() -> str

get_token ​

python
def get_token() -> str

set_labels ​

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

Sets the labels for this session.

Arguments:

  • labels Dict[str, str] - The labels to set for the session.

Returns:

OperationResult: Result indicating success or failure with request ID.

Raises:

SessionError: If the operation fails.

get_labels ​

python
def get_labels() -> OperationResult

Gets the labels for this session.

Returns:

OperationResult: Result containing the labels as data and request ID.

Raises:

SessionError: If the operation fails.

info ​

python
def info() -> OperationResult

Get session information including resource details.

Returns:

OperationResult: Result containing the session information as data and

request ID.

  • success (bool): True if the operation succeeded
  • data (dict): Session information dictionary containing:
  • session_id (str): The session ID
  • resource_url (str): Resource URL for the session
  • app_id (str, optional): Application ID (if desktop session)
  • auth_code (str, optional): Authentication code (if desktop session)
  • connection_properties (dict, optional): Connection properties
  • resource_id (str, optional): Resource ID
  • resource_type (str, optional): Resource type
  • ticket (str, optional): Ticket for connection
  • error_message (str): Error details if the operation failed
  • request_id (str): Unique identifier for this API request
python
def get_link(protocol_type: Optional[str] = None,
             port: Optional[int] = None) -> OperationResult

Get a link associated with the current session.

Arguments:

  • protocol_type Optional[str], optional - The protocol type to use for the link. Defaults to None.
  • port Optional[int], optional - The port to use for the link. Defaults to None.

Returns:

OperationResult: Result containing the link URL as data and request ID.
  • success (bool): True if the operation succeeded
  • data (str): The link URL (when success is True)
  • error_message (str): Error details if the operation failed
  • request_id (str): Unique identifier for this API request

Raises:

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

delete ​

python
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

get_status ​

python
def get_status() -> "SessionStatusResult"

Get basic session status.

Returns:

SessionStatusResult: Result containing session status information.
  • success (bool): True if the operation succeeded
  • status (str): Current session status
  • http_status_code (int): HTTP status code from the API response
  • code (str): Response code
  • error_message (str): Error details if the operation failed
  • request_id (str): Unique identifier for this API request

keep_alive ​

python
def keep_alive() -> OperationResult

Refresh the backend session idle timer.

This method calls the RefreshSessionIdleTime API to reset the idle timeout counter, preventing the session from being automatically released due to inactivity.

Returns:

OperationResult: Result indicating success or failure with request ID.
  • success (bool): True if the operation succeeded
  • error_message (str): Error details if the operation failed
  • request_id (str): Unique identifier for this API request

call_mcp_tool ​

python
def call_mcp_tool(tool_name: str,
                  args: Dict[str, Any],
                  read_timeout: Optional[int] = None,
                  connect_timeout: Optional[int] = None) -> McpToolResult

Call the specified MCP tool.

This method intelligently routes the call to either:

  1. LinkUrl route (direct HTTP) - when link_url, token, and server_name are available
  2. Traditional API route - fallback method

Arguments:

  • tool_name str - Tool name (e.g., "tap", "get_ui_elements").
  • args Dict[str, Any] - Tool arguments dictionary.
  • read_timeout Optional[int], optional - Read timeout in milliseconds. Defaults to None.
  • connect_timeout Optional[int], optional - Connection timeout in milliseconds. Defaults to None.

Returns:

McpToolResult: Tool call result, data field contains tool return data in JSON string format.
  • success (bool): True if tool call succeeded
  • data (str): Tool return data in JSON string format (when success is True)
  • error_message (str): Error details if tool call failed
  • request_id (str): Unique identifier for this API request

Raises:

SessionError: If the tool call fails.

Example:

python
# Call mobile device tap tool
result = session.call_mcp_tool("tap", {"x": 100, "y": 200})

# Call get UI elements tool
result = session.call_mcp_tool("get_ui_elements", {})

list_mcp_tools ​

python
def list_mcp_tools(image_id: Optional[str] = None) -> McpToolsResult

List MCP tools available for the current session.

Arguments:

  • image_id Optional[str], optional - Image ID. Falls back to the session's image_id if not provided. Raises ValueError if neither is set.

Returns:

McpToolsResult: Result containing the list of available MCP tools.
  • success (bool): True if the operation succeeded
  • tools (List[McpTool]): List of MCP tool objects, each containing name, description, input_schema, server, and tool fields
  • error_message (str): Error details if the operation failed
  • request_id (str): Unique identifier for this API request

Raises:

ValueError: If image_id is not provided and session has no image_id.

Example:

python
# List available tools
result = session.list_mcp_tools()
if result.success:
  for tool in result.tools:
      print(f"{tool.name}: {tool.description}")

get_metrics ​

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

Get runtime metrics for this session.

Arguments:

  • read_timeout Optional[int] - Read timeout in milliseconds.
  • connect_timeout Optional[int] - Connect timeout in milliseconds.

Returns:

SessionMetricsResult: Result containing session metrics data.

Documentation generated automatically from source code using pydoc-markdown.