Mobile application lifecycle management - AgentBay: Central de Documentação do Alibaba Cloud

Visão geral

O módulo Mobile Use oferece recursos de gerenciamento de aplicativos para dispositivos móveis Android:

Descoberta de aplicativos: Consulte os aplicativos instalados no dispositivo.
Gerenciamento do ciclo de vida de aplicativos: Inicie e pare aplicativos móveis usando nomes de pacotes.
Gerenciamento de atividades: Inicie Activities específicas do Android.
Monitoramento de processos: Acompanhe aplicativos em execução e seus respectivos processos.

Crie uma sessão

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

Obter aplicativos instalados

Consulte a lista de aplicativos instalados em um dispositivo móvel.

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

Parâmetros:

start_menu (bool): Defina se os aplicativos do menu Iniciar devem ser incluídos.
desktop (bool): Defina se os aplicativos da área de trabalho devem ser incluídos.
ignore_system_apps (bool): Defina se os aplicativos do sistema devem ser filtrados.

Valor de retorno:

Um objeto InstalledAppListResult contendo uma lista de objetos InstalledApp.

Nota

Como a imagem mobile_latest atual não lista aplicativos pré-instalados, este método retorna uma lista vazia. No entanto, ainda é possível iniciar aplicativos usando seus nomes de pacotes.

Iniciar um aplicativo

Inicie um aplicativo móvel utilizando o comando "monkey -p" com o nome do pacote.

Iniciar por nome de pacote

# Start an Android application using the "monkey -p" command
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)

Nota

Sempre use o comando "monkey -p <package_name>" para iniciar aplicativos.
Nomes de pacotes Android comuns:
- Configurações: com.android.settings
- Navegador Chrome: com.android.chrome
- Calculadora: com.android.calculator2
- Contatos: com.android.contacts

Iniciar uma Activity específica (Android)

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)

Nota

O parâmetro activity inicia uma Activity específica dentro de um aplicativo. Formatos suportados:

Nome relativo: ".SettingsActivity"
Nome completo: "com.package/.Activity"

Exemplos comuns de Activities:

Configurações: com.android.settings com a Activity .Settings.
Navegador: com.android.chrome com a Activity com.google.android.apps.chrome.Main.
Calculadora: com.android.calculator2 com a Activity .Calculator.

Parar um aplicativo

Importante

Defina o parâmetro stop_cmd como o nome do pacote, por exemplo, "com.android.settings".

# 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

Exemplo de fluxo de trabalho completo

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!

Referência da API

Método	Parâmetros	Valor de retorno	Descrição
`get_installed_apps()`	`start_menu: booldesktop: boolignore_system_apps: bool`	`InstalledAppListResult`	Obtém a lista de aplicativos instalados.
`start_app()`	`start_cmd: strwork_directory: str = ""activity: str = ""`	`ProcessListResult`	Inicia um aplicativo móvel.
`stop_app_by_cmd()`	`stop_cmd: str`	`AppOperationResult`	Para um aplicativo pelo nome do pacote.

Tipos de retorno

InstalledAppListResult

success (bool): Indica se a operação foi bem-sucedida.
data (List[InstalledApp]): Lista de aplicativos instalados.
error_message (str): Mensagem de erro caso a operação falhe.
request_id (str): ID único da solicitação.

InstalledApp

name (str): Nome do aplicativo.
start_cmd (str): Comando ou nome do pacote para iniciar o aplicativo.
stop_cmd (Optional[str]): Comando para parar o aplicativo.
work_directory (Optional[str]): Diretório de trabalho do aplicativo.

ProcessListResult

success (bool): Indica se a operação foi bem-sucedida.
data (List[Process]): Lista de objetos de processo.
error_message (str): Mensagem de erro caso a operação falhe.
request_id (str): ID único da solicitação.

Process

pname (str): Nome do processo.
pid (int): ID do processo.
cmdline (Optional[str]): Linha de comando completa.

AppOperationResult

success (bool): Indica se a operação foi bem-sucedida.
error_message (str): Mensagem de erro caso a operação falhe.
request_id (str): ID único da solicitação.

Parâmetros específicos para dispositivos móveis

Formato do comando de inicialização

O parâmetro start_cmd deve usar o formato "monkey -p".

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

Formato do comando de parada

Defina o parâmetro stop_cmd como o nome do pacote.

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

Parâmetro de Activity (Android)

O parâmetro activity inicia uma Activity específica.

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

Especifique o nome da Activity de uma das seguintes formas:

Nome relativo: .SettingsActivity. O prefixo do pacote será adicionado automaticamente.
Nome completo: com.package/.Activity. Este é o identificador completo da Activity.