UI 自动化-无影 Agent 开发套件 AgentBay(AgentBay)-阿里云帮助中心

本文介绍无影 AgentBay SDK 在桌面环境中的云电脑 UI 自动化功能，包括鼠标操作、键盘操作和屏幕操作。

概述

Computer Use模块提供强大的云电脑 UI 自动化功能，包括：

鼠标操作 - 精确控制点击、移动、拖拽和滚动。
键盘操作 - 输入文本和发送按键组合。
屏幕操作 - 截取屏幕快照并获取屏幕信息。

创建会话

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
# 使用 windows_latest 或 linux_latest
session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

鼠标操作

点击操作

click_mouse() 方法支持多种点击类型。可以使用 MouseButton 枚举确保类型安全。支持以下按钮类型：

MouseButton.LEFT
MouseButton.RIGHT
MouseButton.MIDDLE
MouseButton.DOUBLE_LEFT

from agentbay.computer import MouseButton

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

# 左键点击
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.LEFT)
if result.success:
    print("左键点击成功")
# 输出: 左键点击成功

# 右键点击
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.RIGHT)
if result.success:
    print("右键点击成功")
# 输出: 右键点击成功

# 中键点击
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.MIDDLE)
if result.success:
    print("中键点击成功")
# 输出: 中键点击成功

# 左键双击
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.DOUBLE_LEFT)
if result.success:
    print("左键双击成功")
# 输出: 左键双击成功

agent_bay.delete(session)

移动鼠标

将鼠标光标移动至指定坐标。

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

result = session.computer.move_mouse(x=600, y=400)
if result.success:
    print("鼠标移动成功")
# 输出: 鼠标移动成功

agent_bay.delete(session)

鼠标拖拽

使用 MouseButton 枚举，将鼠标从一个点拖拽至另一个点，支持以下按钮类型：

MouseButton.LEFT
MouseButton.RIGHT
MouseButton.MIDDLE

from agentbay.computer import MouseButton

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

# 左键拖拽
result = session.computer.drag_mouse(
    from_x=100, 
    from_y=100, 
    to_x=200, 
    to_y=200, 
    button=MouseButton.LEFT
)
if result.success:
    print("拖拽操作成功")
# 输出: 拖拽操作成功

agent_bay.delete(session)

滚轮滚动

使用 ScrollDirection 枚举，在特定坐标处滚动鼠标滚轮。支持以下方向：

ScrollDirection.UP
ScrollDirection.DOWN
ScrollDirection.LEFT
ScrollDirection.RIGHT

from agentbay.computer import ScrollDirection

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

# 向上滚动
result = session.computer.scroll(x=500, y=500, direction=ScrollDirection.UP, amount=3)
if result.success:
    print("向上滚动成功")
# 输出: 向上滚动成功

# 向下滚动
result = session.computer.scroll(x=500, y=500, direction=ScrollDirection.DOWN, amount=5)
if result.success:
    print("向下滚动成功")
# 输出: 向下滚动成功

agent_bay.delete(session)

获取光标位置

import json

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

result = session.computer.get_cursor_position()
if result.success:
    cursor_data = json.loads(result.data)
    print(f"光标位于 x={cursor_data['x']}, y={cursor_data['y']}")
# 输出: 光标位于 x=512, y=384

agent_bay.delete(session)

键盘操作

文本输入

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

result = session.computer.input_text("Hello AgentBay!")
if result.success:
    print("文本输入成功")
# 输出: 文本输入成功

agent_bay.delete(session)

按键操作

组合键输入，支持修饰键。

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

# 按下 Ctrl+A 全选
result = session.computer.press_keys(keys=["Ctrl", "a"])
if result.success:
    print("按键操作成功")
# 输出: 按键操作成功

# 按下 Ctrl+C 复制
result = session.computer.press_keys(keys=["Ctrl", "c"])
if result.success:
    print("复制命令已发送")
# 输出: 复制命令已发送

agent_bay.delete(session)

释放按键

当按键hold=True时，云电脑将持续按住该键位，相关操作完成后需要释放按键，避免与其它按键操作冲突。

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

# 按住 Ctrl 键
session.computer.press_keys(keys=["Ctrl"], hold=True)

# ... 执行其他操作 ...

# 释放 Ctrl 键
result = session.computer.release_keys(keys=["Ctrl"])
if result.success:
    print("按键释放成功")
# 输出: 按键释放成功

agent_bay.delete(session)

屏幕操作

截图

截取当前屏幕快照。截图保存到云存储中并返回下载URL。

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

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

agent_bay.delete(session)

获取屏幕尺寸

import json

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

result = session.computer.get_screen_size()
if result.success:
    screen_data = json.loads(result.data)
    print(f"屏幕宽度: {screen_data['width']}")
    print(f"屏幕高度: {screen_data['height']}")
    print(f"DPI缩放因子: {screen_data['dpiScalingFactor']}")
# 输出：屏幕宽度：1024
# 输出：屏幕高度：768
# 输出：DPI缩放因子：1.0

agent_bay.delete(session)

故障排除

常见问题

"Tool not found"错误。
- 确保使用的是云电脑镜像 (windows_latest 或 linux_latest)。
如何处理截图生成后返回的下载链接（URL）。
- 截图将自动保存至云存储中 (OSS)。
- result.data 包含下载URL，而不是图像数据。
- 可使用该URL下载截图。