UI Automation - AgentBay: Central de Documentação do Alibaba Cloud

Visão geral

O módulo Computer Use oferece automação de UI para cloud computers em três categorias:

Operações de mouse: clique, movimento, arrasto e rolagem com precisão no nível de pixel.
Operações de teclado: digitação de texto e envio de combinações de teclas.
Operações de tela: captura de screenshots e consulta das dimensões da tela.

Resumo dos métodos

Categoria	Método	Descrição
Mouse	click_mouse	Clica nas coordenadas especificadas.
Mouse	move_mouse	Move o cursor sem clicar.
Mouse	drag_mouse	Arrasta de um ponto a outro.
Mouse	scroll	Rola a roda do mouse em uma localização específica.
Mouse	get_cursor_position	Obtém as coordenadas atuais do cursor.
Teclado	input_text	Digita uma string na posição do cursor.
Teclado	press_keys	Envia combinações de teclas ou atalhos.
Teclado	release_keys	Libera teclas pressionadas anteriormente.
Tela	screenshot	Captura a tela e obtém uma URL de download.
Tela	get_screen_size	Obtém as dimensões da tela e o fator de escala DPI.

Sistema de coordenadas

Todas as operações usam coordenadas de pixel com origem (0, 0) no canto superior esquerdo. O eixo X aumenta para a direita e o eixo Y aumenta para baixo. Use get_screen_size() para obter as dimensões da tela e get_cursor_position() para consultar a localização atual do cursor.

Objetos de resultado

Os métodos do módulo Computer Use retornam um de dois tipos de resultado:

BoolResult (retornado por cliques do mouse, movimento, rolagem, entrada de texto e operações de tecla):

Propriedade	Tipo	Descrição
`success`	`bool`	Indica se a operação foi concluída com êxito.
`data`	`bool` ou `None`	Resultado booleano da operação.
`error_message`	`str`	Detalhes do erro caso a operação falhe. String vazia em caso de êxito.

OperationResult (retornado por screenshot, get_cursor_position e get_screen_size):

Propriedade	Tipo	Descrição
`success`	`bool`	Indica se a operação foi concluída com êxito.
`data`	variável	Dados específicos da operação. Para `get_cursor_position` e `get_screen_size`, trata-se de uma string json que você deve analisar com `json.loads()`. Para `screenshot`, é uma string contendo a URL de download.
`error_message`	`str`	Detalhes do erro caso a operação falhe. String vazia em caso de êxito.

Pré-requisitos

Verifique os seguintes requisitos:

AgentBay SDK instalado (pip install wuying-agentbay-sdk) e configurado com credenciais válidas.
Imagem de cloud computer compatível disponível (windows_latest ou linux_latest).

Criar uma sessão

Crie uma sessão conectada a um cloud computer antes de executar a automação de UI.

from agentbay import AgentBay, CreateSessionParams

agent_bay = AgentBay()
# Use windows_latest or linux_latest
session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

Exclua a sessão ao terminar para liberar recursos:

agent_bay.delete(session)

Todos os exemplos abaixo pressupõem uma instância agent_bay existente e uma session ativa, conforme mostrado acima. O código de criação e exclusão de sessão foi omitido para maior brevidade.

Operações de mouse

click_mouse

Clica nas coordenadas de tela especificadas.

Assinatura

session.computer.click_mouse(x, y, button=MouseButton.LEFT)

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`x`	`int`	Sim	-	Posição horizontal em pixels.
`y`	`int`	Sim	-	Posição vertical em pixels.
`button`	`MouseButton`	Não	`MouseButton.LEFT`	Botão a ser usado.

Valores do enum MouseButton

Importação: from agentbay import MouseButton

Valor	Descrição
`MouseButton.LEFT`	Clique esquerdo padrão.
`MouseButton.RIGHT`	Clique direito (menu de contexto).
`MouseButton.MIDDLE`	Clique central (botão da roda de rolagem).
`MouseButton.DOUBLE_LEFT`	Clique duplo com o botão esquerdo.

Retorna: Um objeto BoolResult. Verifique result.success para confirmar se o clique foi registrado.

Exemplo

from agentbay import MouseButton

# Left-click (default button)
result = session.computer.click_mouse(x=500, y=300)
if result.success:
    print("Left-click successful")
# Output: Left-click successful

# Right-click
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.RIGHT)
if result.success:
    print("Right-click successful")
# Output: Right-click successful

# Middle-click
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.MIDDLE)
if result.success:
    print("Middle-click successful")
# Output: Middle-click successful

# Double left-click
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.DOUBLE_LEFT)
if result.success:
    print("Double left-click successful")
# Output: Double left-click successful

move_mouse

Move o cursor para as coordenadas especificadas sem clicar.

Assinatura

session.computer.move_mouse(x, y)

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`x`	`int`	Sim	Posição horizontal em pixels.
`y`	`int`	Sim	Posição vertical em pixels.

Retorna: Um objeto BoolResult.

Exemplo

result = session.computer.move_mouse(x=600, y=400)
if result.success:
    print("Mouse move successful")
# Output: Mouse move successful

drag_mouse

Arrasta de um ponto a outro mantendo o botão especificado pressionado.

Assinatura

session.computer.drag_mouse(from_x, from_y, to_x, to_y, button=MouseButton.LEFT)

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`from_x`	`int`	Sim	-	Posição horizontal inicial em pixels.
`from_y`	`int`	Sim	-	Posição vertical inicial em pixels.
`to_x`	`int`	Sim	-	Posição horizontal final em pixels.
`to_y`	`int`	Sim	-	Posição vertical final em pixels.
`button`	`MouseButton`	Não	`MouseButton.LEFT`	Botão a ser mantido pressionado durante o arrasto.

Valores de botão compatíveis com arrasto: MouseButton.LEFT, MouseButton.RIGHT, MouseButton.MIDDLE.

MouseButton.DOUBLE_LEFT não é compatível com operações de arrasto.

Retorna: Um objeto BoolResult.

Exemplo

from agentbay import MouseButton

result = session.computer.drag_mouse(
    from_x=100,
    from_y=100,
    to_x=200,
    to_y=200,
    button=MouseButton.LEFT
)
if result.success:
    print("Drag operation successful")
# Output: Drag operation successful

scroll

Rola a roda do mouse em uma localização específica da tela.

Assinatura

session.computer.scroll(x, y, direction=ScrollDirection.UP, amount=1)

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`x`	`int`	Sim	-	Posição X para a rolagem, em pixels.
`y`	`int`	Sim	-	Posição Y para a rolagem, em pixels.
`direction`	`ScrollDirection`	Não	`ScrollDirection.UP`	Direção da rolagem.
`amount`	`int`	Não	`1`	Quantidade de incrementos de rolagem.

Valores do enum ScrollDirection

Importação: from agentbay import ScrollDirection

Valor	Descrição
`ScrollDirection.UP`	Rolar para cima.
`ScrollDirection.DOWN`	Rolar para baixo.
`ScrollDirection.LEFT`	Rolar para a esquerda.
`ScrollDirection.RIGHT`	Rolar para a direita.

Retorna: Um objeto BoolResult.

Exemplo

from agentbay import ScrollDirection

# Scroll up
result = session.computer.scroll(x=500, y=500, direction=ScrollDirection.UP, amount=3)
if result.success:
    print("Scroll up successful")
# Output: Scroll up successful

# Scroll down
result = session.computer.scroll(x=500, y=500, direction=ScrollDirection.DOWN, amount=5)
if result.success:
    print("Scroll down successful")
# Output: Scroll down successful

get_cursor_position

Retorna a posição atual do cursor.

Assinatura

session.computer.get_cursor_position()

Parâmetros: Nenhum.

Retorna: Um objeto OperationResult. Quando result.success for True, result.data contém uma string json com os campos x e y.

Exemplo

import json

result = session.computer.get_cursor_position()
if result.success:
    cursor_data = json.loads(result.data)
    print(f"Cursor position: x={cursor_data['x']}, y={cursor_data['y']}")
# Output: Cursor position: x=512, y=384

Operações de teclado

input_text

Digita texto na posição atual do cursor.

Assinatura

session.computer.input_text(text)

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`text`	`str`	Sim	Texto a ser digitado.

Retorna: Um objeto BoolResult.

Exemplo

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

press_keys

Envia uma ou mais teclas simultaneamente, incluindo teclas modificadoras. Use para atalhos como Ctrl+C ou Alt+Tab.

Assinatura

session.computer.press_keys(keys, hold=False)

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`keys`	`list[str]`	Sim	-	Lista de nomes de teclas a serem pressionadas simultaneamente.
`hold`	`bool`	Não	`False`	Se definido como `True`, as teclas permanecem pressionadas em vez de serem pressionadas e liberadas imediatamente. Chame `release_keys()` posteriormente.

Retorna: Um objeto BoolResult.

Exemplo

# Press Ctrl+A to select all
result = session.computer.press_keys(keys=["Ctrl", "a"])
if result.success:
    print("Key press successful")
# Output: Key press successful

# Press Ctrl+C to copy
result = session.computer.press_keys(keys=["Ctrl", "c"])
if result.success:
    print("Copy command sent")
# Output: Copy command sent

release_keys

Libera teclas previamente mantidas pressionadas com press_keys(hold=True). Sempre libere as teclas retidas para evitar interferências em operações subsequentes.

Assinatura

session.computer.release_keys(keys)

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`keys`	`list[str]`	Sim	Lista de nomes de teclas a serem liberadas.

Retorna: Um objeto BoolResult.

Exemplo

# Hold down the Ctrl key
session.computer.press_keys(keys=["Ctrl"], hold=True)

# ... Perform other operations ...

# Release the Ctrl key
result = session.computer.release_keys(keys=["Ctrl"])
if result.success:
    print("Key release successful")
# Output: Key release successful

Operações de tela

screenshot

Captura a tela e retorna uma URL de download. A imagem é salva no Object Storage Service (OSS).

Assinatura

session.computer.screenshot()

Parâmetros: Nenhum.

Retorna: Um objeto OperationResult. Quando result.success for True, result.data contém a URL de download da imagem do screenshot (não os dados brutos da imagem).

Exemplo

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

get_screen_size

Retorna as dimensões da tela e o fator de escala de exibição do cloud computer.

Assinatura

session.computer.get_screen_size()

Parâmetros: Nenhum.

Retorna: Um objeto OperationResult. Quando result.success for True, result.data contém uma string json com os seguintes campos:

Campo	Tipo	Descrição
`width`	`int`	Largura da tela em pixels.
`height`	`int`	Altura da tela em pixels.
`dpiScalingFactor`	`float`	Fator de escala de exibição (escala DPI). O valor `1.0` indica escala de 100% (96 DPI).

Exemplo

import json

result = session.computer.get_screen_size()
if result.success:
    screen_data = json.loads(result.data)
    print(f"Screen width: {screen_data['width']}")
    print(f"Screen height: {screen_data['height']}")
    print(f"DPI scaling factor: {screen_data['dpiScalingFactor']}")
# Output: Screen width: 1024
# Output: Screen height: 768
# Output: DPI scaling factor: 1.0

Solução de problemas

Erro "Tool not found"

Sintoma: Ocorre um erro "Tool not found" ao chamar um método do módulo Computer Use.

Causa: A sessão não está sendo executada em uma imagem de cloud computer compatível.

Solução: Defina image_id com um valor compatível (windows_latest ou linux_latest) ao criar uma sessão.

# Correct - use a supported image ID
session_params = CreateSessionParams(image_id="windows_latest")

Screenshot retorna uma URL em vez de dados de imagem

Sintoma: result.data retornado por screenshot() contém uma string de URL em vez de bytes brutos da imagem.

Causa: Comportamento esperado. O método screenshot() armazena imagens no OSS e retorna uma URL de download.

Solução: Baixe a imagem da URL retornada usando um cliente HTTP ou navegador.

Teclas pressionadas não foram liberadas

Sintoma: Operações de teclado subsequentes apresentam comportamento inesperado após o uso de press_keys(hold=True).

Causa: As teclas mantidas com press_keys(hold=True) permanecem ativas até serem explicitamente liberadas.

Solução: Associe cada chamada de press_keys(hold=True) a uma chamada correspondente de release_keys().

# Hold a key
session.computer.press_keys(keys=["Shift"], hold=True)

# Perform operations that need Shift held...

# Always release afterward
session.computer.release_keys(keys=["Shift"])

Coordenadas fora dos limites

Sintoma: Uma operação de mouse gera resultados inesperados ou nenhum efeito visível.

Causa: As coordenadas alvo podem exceder os limites da tela. O SDK não valida as coordenadas no lado do cliente — elas são enviadas diretamente ao cloud computer.

Solução: Chame get_screen_size() para determinar os limites válidos e garanta que x e y permaneçam dentro do intervalo de (0, 0) a (width, height).