Application management - AgentBay - Alibaba Cloud Documentation Center

This topic describes how to use the AgentBay software development kit (SDK) to manage applications on a cloud computer. You can use the SDK to discover, start, monitor, and control desktop applications in the cloud environment.

Overview

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

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): Specifies whether to include applications from the Start menu.
desktop (bool): Specifies whether to include desktop applications.
ignore_system_apps (bool): Specifies 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})")
    # Output example:
    # 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})")
        # Output example:
        # 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: Obtained 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 stop 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("---")
    # Output example:
    # 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 ===
# ✓ Session creation: 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
# ✓ Session cleanup: 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 its stop command.
`list_visible_apps()`	None	`ProcessListResult`	Lists currently visible applications.

Return types

InstalledAppListResult

success (bool): Indicates whether the operation was successful.
data (List[InstalledApp]): A list of installed applications.
error_message (str): The error message that is returned if the operation fails.
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 was successful.
data (List[Process]): A list of process objects.
error_message (str): The error message that is returned if the operation fails.
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 was successful.
error_message (str): The error message that is returned if the operation fails.
request_id (str): The unique request identifier.