Automação de UI móvel do AgentBay SDK - toque, deslize, entrada de texto, capturas de tela - AgentBay: Central de Documentação do Alibaba Cloud

Visão geral

O SDK disponibiliza os seguintes recursos de automação de UI:

Operações de toque: gestos de toque e deslize para interação com o cloud phone.
Entrada de texto: insira texto e envie eventos de pressionamento de teclas de hardware.
Detecção de elementos de UI: localize e interaja com elementos da interface.
Operações de tela: capture screenshots para verificação visual.

Criar uma sessão

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session
# The session is created. You can now automate the cloud phone.

Operações de toque

Gestos de toque

Toque na tela em coordenadas específicas:

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# Tap at the specified coordinates.
result = session.mobile.tap(x=500, y=300)
if result.success:
    print("Tap successful")  # Output: Tap successful
else:
    print(f"Tap failed: {result.error_message}")

agent_bay.delete(session)

Gestos de deslize

Deslize de um ponto a outro:

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# Swipe up (from bottom to top).
result = session.mobile.swipe(
    start_x=100,
    start_y=500,
    end_x=100,
    end_y=200,
    duration_ms=300
)
if result.success:
    print("Swipe up successful")  # Output: Swipe up successful

# Swipe left (from right to left).
result = session.mobile.swipe(
    start_x=500,
    start_y=300,
    end_x=100,
    end_y=300,
    duration_ms=300
)
if result.success:
    print("Swipe left successful")  # Output: Swipe left successful

agent_bay.delete(session)

Parâmetros:

start_x, start_y: coordenadas iniciais.
end_x, end_y: coordenadas finais.
duration_ms: duração do deslize em milissegundos. Padrão: 300.

Entrada de texto

Inserir texto

Insira texto no campo de entrada ativo:

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

result = session.mobile.input_text("Hello AgentBay!")
if result.success:
    print("Text input successful")  # Output: Text input successful

agent_bay.delete(session)

Enviar eventos de tecla

Envie eventos de tecla do Android usando as constantes KeyCode:

from agentbay.mobile.mobile import KeyCode

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# Press the HOME key.
result = session.mobile.send_key(KeyCode.HOME)
if result.success:
    print("HOME key pressed")  # Output: HOME key pressed

# KeyCode values: HOME=3, BACK=4, VOLUME_UP=24, VOLUME_DOWN=25, POWER=26, MENU=82
print(f"HOME keycode value: {KeyCode.HOME}")  # Output: HOME keycode value: 3

agent_bay.delete(session)

Constantes KeyCode disponíveis:

KeyCode	Valor	Descrição
`KeyCode.HOME`	3	Botão Home
`KeyCode.BACK`	4	Botão Voltar
`KeyCode.VOLUME_UP`	24	Botão de aumentar volume
`KeyCode.VOLUME_DOWN`	25	Botão de diminuir volume
`KeyCode.POWER`	26	Botão Liga/Desliga
`KeyCode.MENU`	82	Botão Menu

Nota: todos os eventos de tecla são enviados diretamente ao sistema Android.

Detecção de elementos de UI

Recuperar todos os elementos de UI

Recupere todos os elementos de UI na hierarquia da tela atual:

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

result = session.mobile.get_all_ui_elements(timeout_ms=2000)
if result.success:
    print(f"Found {len(result.elements)} UI elements")  # Output: Found 2172 UI elements
    for element in result.elements:
        # The element structure varies. Check the element data.
        print(f"Element: {element}")
        # Example output: Element data contains UI hierarchy information
else:
    print(f"Failed: {result.error_message}")

agent_bay.delete(session)

Parâmetro:

timeout_ms: tempo limite em milissegundos para recuperação dos elementos de UI. Padrão: 2000.

Operações de tela

Capturar screenshot

Capture a tela atual do cloud phone:

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

result = session.mobile.screenshot()
if result.success:
    screenshot_url = result.data
    print(f"Screenshot URL: {screenshot_url}")
    # Output: Screenshot URL: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***
else:
    print(f"Screenshot failed: {result.error_message}")

agent_bay.delete(session)

Melhores práticas

Usar uma imagem de cloud phone

A automação de UI em cloud phones exige uma imagem de sistema operacional móvel, como mobile_latest:

# Correct - Use a cloud phone OS image.
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# Incorrect - Cannot be used for cloud phone operations.
session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

Tratar URLs de screenshot

O método de captura de tela retorna uma URL do OSS, e não os dados da imagem:

result = session.mobile.screenshot()
if result.success:
    screenshot_url = result.data
    print(f"Screenshot available at: {screenshot_url}")
    # Output: Screenshot available at: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***
    # Use the URL to download or display the screenshot.
else:
    print(f"Screenshot failed: {result.error_message}")

Casos de uso comuns

Navegação em aplicativos

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # Tap the application icon.
    tap_result = session.mobile.tap(x=200, y=400)
    print(f"App tap result: {tap_result.success}")  # Output: App tap result: True
    
    # Wait for the application to load.
    import time
    time.sleep(2)
    
    # Swipe to navigate.
    swipe_result = session.mobile.swipe(
        start_x=400,
        start_y=600,
        end_x=100,
        end_y=600,
        duration_ms=300
    )
    print(f"Navigation swipe result: {swipe_result.success}")  # Output: Navigation swipe result: True
    
    # Tap the button.
    button_result = session.mobile.tap(x=300, y=800)
    print(f"Button tap result: {button_result.success}")  # Output: Button tap result: True
    
finally:
    agent_bay.delete(session)

Preenchimento de formulários

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # Tap the username field.
    username_tap = session.mobile.tap(x=300, y=400)
    print(f"Username field focused: {username_tap.success}")  # Output: Username field focused: True
    
    # Enter the username.
    username_input = session.mobile.input_text("john_doe")
    print(f"Username entered: {username_input.success}")  # Output: Username entered: True
    
    # Tap the password field.
    password_tap = session.mobile.tap(x=300, y=500)
    print(f"Password field focused: {password_tap.success}")  # Output: Password field focused: True
    
    # Enter the password.
    password_input = session.mobile.input_text("secure_password")
    print(f"Password entered: {password_input.success}")  # Output: Password entered: True
    
    # Tap the logon button.
    login_tap = session.mobile.tap(x=300, y=650)
    print(f"Login button pressed: {login_tap.success}")  # Output: Login button pressed: True
    
finally:
    agent_bay.delete(session)

Descoberta de elementos de UI

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # Get all clickable elements.
    result = session.mobile.get_clickable_ui_elements(timeout_ms=3000)
    
    if result.success:
        print(f"Found {len(result.elements)} clickable elements")  # Output: Found 3 clickable elements
        
        # Analyze the elements to find the target.
        for i, element in enumerate(result.elements):
            print(f"Element {i+1}: {element}")  
            # Example output:
            # Element 1: UI element with interaction capabilities
            # Element 2: UI element with interaction capabilities  
            # Element 3: UI element with interaction capabilities
    
    # Take a screenshot for verification.
    screenshot = session.mobile.screenshot()
    if screenshot.success:
        screenshot_url = screenshot.data
        print(f"Screenshot URL: {screenshot_url}")
        # Output: Screenshot URL: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***
    
finally:
    agent_bay.delete(session)

Rolagem de conteúdo

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # Scroll down multiple times.
    for i in range(3):
        scroll_result = session.mobile.swipe(
            start_x=300,
            start_y=800,
            end_x=300,
            end_y=200,
            duration_ms=400
        )
        print(f"Scroll down {i+1}: {scroll_result.success}")  # Output: Scroll down 1: True, etc.
        
        # Pause briefly between scrolls.
        import time
        time.sleep(1)
    
    # Scroll up.
    up_result = session.mobile.swipe(
        start_x=300,
        start_y=200,
        end_x=300,
        end_y=800,
        duration_ms=400
    )
    print(f"Scroll up result: {up_result.success}")  # Output: Scroll up result: True
    
finally:
    agent_bay.delete(session)

Solução de problemas

Perguntas frequentes

Erro "Tool not found"
- Use uma imagem de sistema operacional para cloud phone, como image_id="mobile_latest".
- Verifique se a sessão foi criada com sucesso.
- Confirme se a chave de API e o endpoint estão configurados corretamente.
Operações de pressionamento de teclas de hardware
- Os eventos de tecla são enviados diretamente ao sistema Android.
- Consulte result.success para confirmar o envio da tecla.
- Exemplo de tratamento de erros:
```
result = session.mobile.send_key(KeyCode.HOME)
if not result.success:
    print(f"Key press failed: {result.error_message}")
```
A detecção de elementos de UI retorna um resultado vazio
- Aumente o valor de timeout_ms.
- Capture uma screenshot para verificar o estado atual da UI.
- Aguarde o carregamento completo da tela de destino.
URLs de screenshot
- A captura de tela retorna uma URL do OSS, não os dados da imagem.
- result.data contém a URL para download.
- Use essa URL para baixar a screenshot quando necessário.
O gesto de deslize não funciona conforme o esperado
- Verifique se as coordenadas estão dentro dos limites da tela.
- Ajuste duration_ms para alterar a velocidade do gesto.
- Certifique-se de que as coordenadas inicial e final formem um trajeto de deslize válido.