Gerenciamento do ciclo de vida de aplicativos de desktop - AgentBay: Central de Documentação do Alibaba Cloud

Visão geral

O módulo Computer Use oferece recursos de gerenciamento de aplicativos para o ambiente de desktop, incluindo:

Descoberta de aplicativos: localize aplicativos instalados no sistema.
Gerenciamento do ciclo de vida de aplicativos: inicie e interrompa aplicativos de desktop.
Monitoramento de processos: acompanhe aplicativos em execução e seus respectivos processos.
Automação de desktop: automatize fluxos de trabalho complexos no ambiente de desktop.

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("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)

Obtenha os aplicativos instalados

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}")

Parâmetros

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

Valor de retorno

Um objeto InstalledAppListResult que contém uma lista de objetos InstalledApp.

Inicie um aplicativo

Início por comando

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}")

Início com um diretório de trabalho especificado

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}")

Início a partir da lista de aplicativos instalados

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")

Interrompa um aplicativo

Interrupção por 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}")

Interrupção por nome do processo

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}")

Interrupção por comando

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}")

Liste os aplicativos em execução

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}")

Atributos do objeto de processo

pname (str): nome do processo.
pid (int): ID do processo.
cmdline (str): linha de comando completa usada para iniciar o processo.

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("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

Referência da API

Métodos de gerenciamento de aplicativos do computador na nuvem

Acesse todos os métodos de gerenciamento de aplicativos por meio de session.computer.*.

Método	Parâmetros	Valor de retorno	Descrição
`get_installed_apps()`	`start_menu: bool = True`<br/>`desktop: bool = False`<br/>`ignore_system_apps: bool = True`	`InstalledAppListResult`	Obtém a lista de aplicativos instalados.
`start_app()`	`start_cmd: str`<br/>`work_directory: str = ""`<br/>`activity: str = ""`	`ProcessListResult`	Inicia um aplicativo.
`stop_app_by_pid()`	`pid: int`	`AppOperationResult`	Interrompe um aplicativo pelo ID do processo.
`stop_app_by_pname()`	`pname: str`	`AppOperationResult`	Interrompe um aplicativo pelo nome do processo.
`stop_app_by_cmd()`	`stop_cmd: str`	`AppOperationResult`	Interrompe um aplicativo via comando.
`list_visible_apps()`	Nenhum	`ProcessListResult`	Lista os aplicativos visíveis no momento.

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 retornada em caso de falha.
request_id (str): identificador único da solicitação.

InstalledApp

name (str): nome do aplicativo.
start_cmd (str): comando para iniciar o aplicativo.
stop_cmd (Optional[str]): comando para interromper 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 retornada em caso de falha.
request_id (str): identificador ú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 retornada em caso de falha.
request_id (str): identificador único da solicitação.