AgentBay:Application Management

Overview

The Mobile Use module provides application management features for Android mobile devices, including the following:

1. Application discovery: Query installed applications on the device.

2. Application lifecycle management: Start and stop mobile applications using package names.

3. Activity management: Start specific Android Activities.

4. Process monitoring: Track running applications and their processes.

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("The AGENTBAY_API_KEY environment variable is required")

agent_bay = AgentBay(api_key=api_key)

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

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

# Actual output:
# Session created: session-04bdw8o39c9uiwet4

Get installed applications

You can query the list of installed applications on a mobile device.

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

if result.success:
    apps = result.data
    print(f"Found {len(apps)} 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"Working directory: {app.work_directory if app.work_directory else 'N/A'}")
        print("---")
else:
    print(f"Error: {result.error_message}")

# Actual output (using the current mobile_latest image):
# Found 0 installed applications

Parameters:

• start_menu (bool): Specifies whether to include Start menu applications.

• 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

You can start a mobile application using the "monkey -p" command format with the package name.

# Start an Android application using the "monkey -p" format
start_cmd = "monkey -p com.android.settings"

result = session.mobile.start_app(start_cmd)

if result.success:
    processes = result.data
    print(f"Application started with {len(processes)} processes")

    for process in processes:
        print(f"Process: {process.pname} (PID: {process.pid})")
else:
    print(f"Failed to start application: {result.error_message}")

# Actual output:
# Application started with 1 process
# Process: com.android.settings (PID: 2805)

start_cmd = "monkey -p com.android.settings"
activity = ".Settings"

result = session.mobile.start_app(
    start_cmd=start_cmd,
    activity=activity
)

if result.success:
    processes = result.data
    print(f"Application started with Activity {activity}")
    print(f"Found {len(processes)} processes")
    
    for process in processes:
        print(f"Process: {process.pname} (PID: {process.pid})")
else:
    print(f"Failed to start application: {result.error_message}")

# Actual output:
# Application started with Activity .Settings
# Found 1 process
# Process: com.android.settings (PID: 2921)

Stop an application

# Start an application
start_result = session.mobile.start_app("monkey -p com.android.settings")

if start_result.success:
    print("Application started successfully")
    for process in start_result.data:
        print(f"  Process: {process.pname} (PID: {process.pid})")

    # Stop the application using the package name
    result = session.mobile.stop_app_by_cmd("com.android.settings")

    if result.success:
        print("Application stopped successfully")
    else:
        print(f"Failed to stop application: {result.error_message}")

# Actual output:
# Application started successfully
#   Process: com.android.settings (PID: 3042)
# Application stopped successfully

Complete 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("The AGENTBAY_API_KEY environment variable is required")

agent_bay = AgentBay(api_key=api_key)

# Create a mobile session
params = CreateSessionParams(image_id="mobile_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}")

# Step 1: Start the application
print("Step 1: Starting the Settings application...")
start_result = session.mobile.start_app("monkey -p com.android.settings")

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

print(f"Application started with {len(start_result.data)} processes")
for process in start_result.data:
    print(f"  - {process.pname} (PID: {process.pid})")

# Step 2: Wait for the application to load
print("Step 2: Waiting for the application to load...")
time.sleep(3)

# Step 3: Stop the application
print("Step 3: Stopping the application...")
stop_result = session.mobile.stop_app_by_cmd("com.android.settings")
if stop_result.success:
    print("Application stopped successfully")
else:
    print(f"Failed to stop application: {stop_result.error_message}")

# Clean up
print("Cleaning up the session...")
agent_bay.delete(session)
print("Workflow complete!")

# Actual output:
# Session created: session-04bdwfj7tnhfnzibx
# Step 1: Starting the Settings application...
# Application started with 1 process
#   - com.android.settings (PID: 3268)
# Step 2: Waiting for the application to load...
# Step 3: Stopping the application...
# Application stopped successfully
# Cleaning up the session...
# Workflow complete!

API reference

session.mobile.start_app("monkey -p com.android.settings")

session.mobile.stop_app_by_cmd("com.android.settings")

session.mobile.start_app(
    start_cmd="monkey -p com.android.settings",
    activity=".Settings"
)