Control Cloud Computer App Lifecycle via AgentBay SDK - AgentBay - Alibaba Cloud - AgentBay

Overview

The Computer Use module provides application management capabilities for the desktop environment, including:

Application discovery - Find applications installed on the system.
Application lifecycle management - Start and stop desktop applications.
Process monitoring - Track running applications and their processes.
Desktop automation - Automate complex desktop workflows.

Create a session

import os
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    raise ValueError("AGENTBAY_API_KEY environment variable is required")

agent_bay = AgentBay(api_key=api_key)

params = CreateSessionParams(image_id="linux_latest")
result = agent_bay.create(params)

if result.success:
    session = result.session
    print(f"Session created: {session.session_id}")
    # Output: Session created: session-xxxxxxxxxxxxxxxxx
else:
    print(f"Failed to create session: {result.error_message}")
    exit(1)

Get installed applications

result = session.computer.get_installed_apps(
    start_menu=True,
    desktop=False,
    ignore_system_apps=True
)

# Verification: The result type is InstalledAppListResult
# Verification: Success = True
# Verification: Found 76 installed applications on the test system

if result.success:
    apps = result.data
    print(f"Found {len(apps)} installed applications")
    # Output: Found 76 installed applications
    
    for app in apps[:5]:
        print(f"Name: {app.name}")
        print(f"Start Command: {app.start_cmd}")
        print(f"Stop Command: {app.stop_cmd if app.stop_cmd else 'N/A'}")
        print(f"Work Directory: {app.work_directory if app.work_directory else 'N/A'}")
        print("---")
    # Output example:
    # Name: AptURL
    # Start Command: apturl %u
    # Stop Command: N/A
    # Work Directory: N/A
    # ---
    # Name: Bluetooth Transfer
    # Start Command: bluetooth-sendto
    # Stop Command: N/A
    # Work Directory: N/A
    # ---
else:
    print(f"Error: {result.error_message}")

Parameters

start_menu (bool): Whether to include applications from the Start menu.
desktop (bool): Whether to include desktop applications.
ignore_system_apps (bool): Whether to filter out system applications.

Return value

An InstalledAppListResult object that contains a list of InstalledApp objects.

Start an application

Start by command

start_cmd = "/usr/bin/google-chrome-stable"

result = session.computer.start_app(start_cmd)

# Verification: The result type is ProcessListResult
# Verification: Success = True
# Verification: Started 6 processes (main chrome process + helper processes)

if result.success:
    processes = result.data
    print(f"Application started with {len(processes)} processes")
    # Output: Application started with 6 processes
    
    for process in processes:
        print(f"Process: {process.pname} (PID: {process.pid})")
    # Sample output:
    # Process: chrome (PID: 4443)
    # Process: cat (PID: 4448)
    # Process: cat (PID: 4449)
    # Process: chrome (PID: 4459)
    # Process: chrome (PID: 4460)
    # Process: chrome (PID: 4462)
else:
    print(f"Failed to start application: {result.error_message}")

Start with a specified working directory

start_cmd = "/usr/bin/google-chrome-stable"
work_directory = "/tmp"

result = session.computer.start_app(
    start_cmd=start_cmd,
    work_directory=work_directory
)

# Verification: The result type is ProcessListResult
# Verification: Success = True
# Verification: The application started in the specified working directory

if result.success:
    processes = result.data
    print(f"Application started with {len(processes)} processes")
    # Output: Application started with 6 processes
else:
    print(f"Failed to start application: {result.error_message}")

Start from the list of installed applications

result = session.computer.get_installed_apps(
    start_menu=True,
    desktop=False,
    ignore_system_apps=True
)

# Verification: Successfully retrieved the list of installed applications

if result.success:
    apps = result.data
    
    target_app = None
    for app in apps:
        if "chrome" in app.name.lower():
            target_app = app
            break
    
    # Verification: Found "Google Chrome" in the application list
    
    if target_app:
        print(f"Starting {target_app.name}...")
        # Output: Starting Google Chrome...
        
        start_result = session.computer.start_app(target_app.start_cmd)
        
        # Verification: Successfully started the application
        
        if start_result.success:
            print("Application started successfully!")
            # Output: Application started successfully!
        else:
            print(f"Failed to start: {start_result.error_message}")
    else:
        print("Target application not found")

Stop an application

Stop by PID

start_result = session.computer.start_app("/usr/bin/google-chrome-stable")

# Verification: The application started successfully with multiple processes

if start_result.success:
    target_pid = None
    for process in start_result.data:
        print(f"Process: {process.pname} (PID: {process.pid})")
        # Sample output:
        # Process: chrome (PID: 6378)
        # Process: cat (PID: 6383)
        # Process: cat (PID: 6384)
        
        if 'chrome' in process.pname.lower():
            target_pid = process.pid
            break
    
    if target_pid:
        result = session.computer.stop_app_by_pid(target_pid)
        
        # Verification: The result type is AppOperationResult
        # Verification: Success = True
        
        if result.success:
            print(f"Successfully stopped process {target_pid}")
            # Output: Successfully stopped process 6378
        else:
            print(f"Failed to stop process: {result.error_message}")

Stop by process name

start_result = session.computer.start_app("/usr/bin/google-chrome-stable")

# Verification: The application started successfully

if start_result.success:
    target_pname = None
    for process in start_result.data:
        print(f"Process: {process.pname} (PID: {process.pid})")
        target_pname = process.pname
        break
    
    # Verification: Got the process name "chrome"
    
    if target_pname:
        result = session.computer.stop_app_by_pname(target_pname)
        
        # Verification: The result type is AppOperationResult
        # Verification: Success = True
        
        if result.success:
            print(f"Successfully stopped process {target_pname}")
            # Output: Successfully stopped process chrome
        else:
            print(f"Failed to stop process: {result.error_message}")

Stop by command

result = session.computer.get_installed_apps(
    start_menu=True,
    desktop=False,
    ignore_system_apps=True
)

# Verification: Successfully retrieved the installed applications

if result.success:
    apps = result.data
    
    target_app = None
    for app in apps:
        if app.stop_cmd:
            target_app = app
            break
    
    # Note: Most desktop applications on Linux do not have a defined stop_cmd.
    # This is normal. Use stop_app_by_pid or stop_app_by_pname instead.
    
    if target_app:
        start_result = session.computer.start_app(target_app.start_cmd)
        
        if start_result.success:
            print("Application started successfully!")
            
            result = session.computer.stop_app_by_cmd(target_app.stop_cmd)
            
            # Verification: The result type is AppOperationResult
            
            if result.success:
                print("Successfully stopped application using command")
            else:
                print(f"Failed to stop application: {result.error_message}")

List running applications

result = session.computer.list_visible_apps()

# Verification: The result type is ProcessListResult
# Verification: Success = True
# Verification: Found 1 visible application (chrome with a visible window)

if result.success:
    visible_apps = result.data
    print(f"Found {len(visible_apps)} running applications")
    # Output: Found 1 running applications
    
    for app in visible_apps:
        print(f"Process: {app.pname}")
        print(f"PID: {app.pid}")
        print(f"Command: {app.cmdline}")
        print("---")
    # Sample output:
    # Process: chrome
    # PID: 6378
    # Command: /opt/google/chrome/chrome
    # ---
else:
    print(f"Error: {result.error_message}")

Process object attributes

pname (str): The process name.
pid (int): The process ID.
cmdline (str): The full command line used to start the process.

Full workflow example

import os
import time
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    raise ValueError("AGENTBAY_API_KEY environment variable is required")

agent_bay = AgentBay(api_key=api_key)

params = CreateSessionParams(image_id="linux_latest")
result = agent_bay.create(params)

if not result.success:
    print(f"Failed to create session: {result.error_message}")
    exit(1)

session = result.session
print(f"Session created: {session.session_id}")
# Output: Session created: session-xxxxxxxxxxxxxxxxx

print("Step 1: Finding installed applications...")
apps_result = session.computer.get_installed_apps(
    start_menu=True,
    desktop=False,
    ignore_system_apps=True
)

# Verification: Successfully retrieved 76 applications

if not apps_result.success:
    print(f"Failed to get apps: {apps_result.error_message}")
    agent_bay.delete(session)
    exit(1)

target_app = None
for app in apps_result.data:
    if "chrome" in app.name.lower():
        target_app = app
        break

# Verification: Found the "Google Chrome" application

if not target_app:
    print("Google Chrome not found")
    agent_bay.delete(session)
    exit(1)

print(f"Found application: {target_app.name}")
# Output: Found application: Google Chrome

print("Step 2: Launching application...")
start_result = session.computer.start_app(target_app.start_cmd)

# Verification: Successfully started 6 processes

if not start_result.success:
    print(f"Failed to start app: {start_result.error_message}")
    agent_bay.delete(session)
    exit(1)

print(f"Application started with {len(start_result.data)} processes")
# Output: Application started with 6 processes

for process in start_result.data:
    print(f"  - {process.pname} (PID: {process.pid})")
# Output example:
#   - chrome (PID: 6420)
#   - cat (PID: 6425)
#   - cat (PID: 6426)
#   - chrome (PID: 6436)
#   - chrome (PID: 6437)
#   - chrome (PID: 6439)

print("Step 3: Waiting for application to load...")
time.sleep(5)

print("Step 4: Checking running applications...")
visible_result = session.computer.list_visible_apps()

# Verification: Found 1 visible application

if visible_result.success:
    print(f"Found {len(visible_result.data)} visible applications")
    # Output: Found 1 visible applications

print("Step 5: Stopping application...")
if start_result.data:
    stop_result = session.computer.stop_app_by_pid(start_result.data[0].pid)
    
    # Verification: Successfully stopped the application
    
    if stop_result.success:
        print("Application stopped successfully")
        # Output: Application stopped successfully
    else:
        print(f"Failed to stop application: {stop_result.error_message}")

print("Cleaning up session...")
agent_bay.delete(session)
print("Workflow completed!")
# Output: Workflow completed!

# === Full Workflow Verification Results ===
# ✓ Create session: Success
# ✓ Get installed applications: Found 76 applications
# ✓ Find target application: Found Google Chrome
# ✓ Start application: Started 6 processes
# ✓ List visible applications: 1 visible application
# ✓ Stop application: Success
# ✓ Clean up session: Success

API reference

Cloud computer application management methods

All application management methods are accessed through session.computer.*.

Method	Parameters	Return value	Description
`get_installed_apps()`	`start_menu: bool = True`<br/>`desktop: bool = False`<br/>`ignore_system_apps: bool = True`	`InstalledAppListResult`	Gets the list of installed applications.
`start_app()`	`start_cmd: str`<br/>`work_directory: str = ""`<br/>`activity: str = ""`	`ProcessListResult`	Starts an application.
`stop_app_by_pid()`	`pid: int`	`AppOperationResult`	Stops an application by its process ID.
`stop_app_by_pname()`	`pname: str`	`AppOperationResult`	Stops an application by its process name.
`stop_app_by_cmd()`	`stop_cmd: str`	`AppOperationResult`	Stops an application by command.
`list_visible_apps()`	None	`ProcessListResult`	Lists currently visible applications.

Return types

InstalledAppListResult

success (bool): Indicates whether the operation succeeded.
data (List[InstalledApp]): A list of installed applications.
error_message (str): The error message returned on failure.
request_id (str): The unique request identifier.

InstalledApp

name (str): The application name.
start_cmd (str): The command to start the application.
stop_cmd (Optional[str]): The command to stop the application.
work_directory (Optional[str]): The working directory of the application.

ProcessListResult

success (bool): Indicates whether the operation succeeded.
data (List[Process]): A list of process objects.
error_message (str): The error message returned on failure.
request_id (str): The unique request identifier.

Process

pname (str): The process name.
pid (int): The process ID.
cmdline (Optional[str]): The full command line.

AppOperationResult

success (bool): Indicates whether the operation succeeded.
error_message (str): The error message returned on failure.
request_id (str): The unique request identifier.