AndroidWorld 环境实战指南在 MobileAgent 仓库中运行 Android GUI Agent 基准评测【免费下载链接】MobileAgentMobile-Agent: The Powerful GUI Agent Family项目地址: https://gitcode.com/GitHub_Trending/mo/MobileAgentAndroidWorld 是一套运行在真实 Android 模拟器上的自主 GUI Agent 构建与评测环境本指南以 Mobile-Agent-v3/android_world_v3/README.md 为骨架结合该目录下的minimal_task_runner.py、run_ma3.py、Agent 基类与 Docker 支持等源码完整讲解从模拟器搭建、环境安装、快速上手、Docker 化部署、全量 Benchmark 评测到自定义 Agent 与新增评测任务的全过程。读完本文你将能够在本地搭建一套可复现的 Android GUI Agent 评测流水线并理解其任务注册、动作空间与验证机制的工作原理。AndroidWorld 是什么一套可复现的 Android GUI Agent 评测环境AndroidWorld 是一个用于构建与评测自主计算机控制 Agent 的环境它运行在真实的 Android 模拟器之上而不是静态截图或合成页面。其核心设计目标是通过动态任务实例化与持久化奖励信号来解决传统 GUI 基准如 MiniWoB中存在的过拟合与不可复现问题。依据 READMEAndroidWorld 的关键特性包括116 个多样化的手工任务覆盖 20 个真实应用如时钟、相机、日历、短信等动态任务实例化每个任务模板通过随机生成参数电话号码、消息内容、联系人姓名、日期时间等产生数百万种互不重复的任务变体持久的奖励信号durable reward signals任务的成败通过检查底层数据如 SQLite 数据库、文件系统、系统设置来判定而非仅看截图从而保证评测可靠性实验性 Docker 支持截至 2025-06-02 的 README 说明在容器内运行 Android 模拟器与 FastAPI 服务器简化环境搭建并保证一致性开放的运行环境Agent 可以访问数以百万计的 Android 应用与网站轻量级资源占用约 2 GB 内存、8 GB 磁盘可扩展设计方便新增任务与新的 Benchmark内置 MiniWoB 集成支持运行 [Liu et al.] 提出的经典网页基准任务。此外仓库内还提供了 task_metadata.json 作为全部任务元数据的汇总共 919 行每条记录包含任务名、任务模板、难度等级、标签如data_entry、complex_ui_understanding、parameterized、multi_app与最优步数。例如AudioRecorderRecordAudio标记为 easy、BrowserMultiply标记为 hard这类元数据既可用于评测前的任务筛选也可作为后续分析的统计依据。安装与环境准备1. 搭建 Android 模拟器AVDAndroidWorld 与模拟器之间通过 gRPC 通信因此必须从命令行启动模拟器而非 Android Studio 的图形界面。安装步骤如下下载安装 Android Studio按照官方指引创建 Android Virtual DeviceAVD硬件选择Pixel 6System Image 选择TiramisuAPI Level 33AVD 名称命名为AndroidWorldAvd。2. 从命令行启动模拟器启动时必须携带-grpc 8554标志该端口用于与辅助功能转发应用accessibility forwarding app通信# 通常位于 ~/Android/Sdk/emulator/emulator 或 ~/Library/Android/sdk/emulator/emulator EMULATOR_NAMEAndroidWorldAvd # 上一步创建的 AVD 名称 ~/Library/Android/sdk/emulator/emulator -avd $EMULATOR_NAME -no-snapshot -grpc 8554-no-snapshot用于保证每次启动时环境状态干净一致-grpc 8554是后续代码访问设备状态的前提。注意 run_ma3.py 中也定义了--grpc_port默认 8554用于建立连接二者必须一致。3. 创建 Python 环境并安装 AndroidWorld推荐使用conda创建独立环境Python 3.11 及以上版本是硬性要求conda create -n android_world python3.11.8 conda activate android_world仓库目录同时提供了 pyproject.toml、setup.py 与 requirements.txt 三套依赖声明上游 README 推荐的安装命令为git clone https://github.com/google-research/android_world.git cd ./android_world pip install -r requirements.txt python setup.py install4. 配置模型供应商 API 密钥评测需要调用外部多模态大模型需将密钥写入环境变量例如写入~/.bashrcexport OPENAI_API_KEYyour-key export GCP_API_KEYyour-key这两个变量分别对应 infer.py 中的两类模型封装Gpt4Wrapperinfer.py#L244-L340在构造时会读取OPENAI_API_KEY并在此处直接抛错GeminiGcpWrapperinfer.py#L104-L241依赖GCP_API_KEY。两者都实现了内置的指数退避重试默认max_retry3、上限 5 次可缓解大模型接口的偶发超时与限流。5. 安装 ffmpegAgent 在评测中会录制轨迹视频需要ffmpeg# Linux (Ubuntu/Debian) sudo apt update sudo apt install ffmpeg # macOS brew install ffmpeg快速开始minimal_task_runner.py 单任务运行安装完成后可直接运行 minimal_task_runner.py 观察 AndroidWorld 各组件的协作机制。该脚本是run.py的精简版初始化环境、设定任务、并用默认 Agent M3A 执行该任务python minimal_task_runner.py --taskContactsAddContact如果不指定--task脚本会从任务注册表中随机选取一个任务见 minimal_task_runner.py#L100-L103。完整可用的 Flag 还包括Flag默认值说明--taskNone指定要运行的具体任务名不指定则随机选择--perform_emulator_setupFalse是否执行一次性模拟器环境初始化安装开源应用、设置权限仅在首次运行时置为 True--console_port5554Android 设备控制台端口可从adb devices输出判断第一个设备通常为 5554第二个为 5556依此类推--adb_path自动探测adb可执行文件路径脚本会优先在~/Library/Android/sdk/platform-tools/adb与~/Android/Sdk/platform-tools/adb中查找minimal_task_runner.py#L42-L55从源码看脚本的执行主流程为minimal_task_runner.py#L86-L121通过env_launcher.load_and_setup_env加载并设置环境env.reset(go_homeTrue)回到桌面从registry.TaskRegistry获取android_world任务族注册表并取出目标任务类型调用task_type.generate_random_params()生成随机参数并实例化任务task.initialize_task(env)将任务写入模拟器使用t3a.T3A配合gpt-4-turbo-2024-04-09在complexity * 10步数预算内循环执行agent.step(goal)最终以task.is_successful(env) 1判定成败并打印结果。提示如需尝试不在 Android 系统内置中的开源应用如 Simple Calendar Pro、Markor 等必须在上述命令中追加--perform_emulator_setup该过程会根据网络速度耗时数分钟属于一次性初始化。Docker 支持实验性AndroidWorld 提供了实验性的 Docker 支持可把 Android 模拟器与 FastAPI 服务端整体放入容器简化环境搭建、保证环境一致性。注意该功能仍处于实验阶段未经大规模测试。构建并运行镜像在仓库根目录执行docker build -t android_world:latest . docker run --privileged -p 5000:5000 -it android_world:latest第二条命令会在容器内同时启动 Android 模拟器与 FastAPI 服务器服务端暴露在http://localhost:5000。从 Dockerfile 可以看到镜像的完整构建逻辑基于openjdk:18-jdk-slim安装 Android SDK 命令行工具与system-images;android-33;google_apis;x86_64系统镜像通过avdmanager预建名为Pixel_6_API_33的 AVD并从源码编译 Python 3.11最后以 docker_setup/entrypoint.sh 作为容器入口。使用 HTTP 客户端与环境交互scripts/run_suite_on_docker.py 给出了一个完整的示例客户端展示了如何通过 HTTP 与容器内的环境服务器交互其核心方法包括reset(go_home)重置环境POST /resetget_screenshot()获取当前截图GET /screenshotexecute_action(action)执行 JSON 动作POST /execute_action如JSONAction(action_typeclick, x100, y200)get_suite_task_list/get_suite_task_length读取任务族列表与每种任务的数量reinitialize_suite(n_task_combinations, seed, task_family)按参数组合数重新初始化任务套件initialize_task/tear_down_task/get_task_score/get_task_goal/get_task_template单任务的初始化、回收与评分查询close()/health()关闭环境与健康检查。该脚本的__main__部分演示了完整评测循环等待服务器就绪 → 重置环境 → 截屏 → 执行示例点击 → 遍历任务列表对每个任务初始化、读取 goal 与模板、完成用你自己的 Agent 逻辑、获取得分并回收。同时脚本也标注了已知的异常任务如RetroPlayingQueue的 sqlite 表缺失、SimpleSmsReplyMostRecent的列表越界在实际跑分时需做容错处理。Apple SiliconM 系列芯片用户的注意事项在 ARM 芯片上安装emulator包存在已知问题。若需在本地构建镜像应显式指定 AMD64/x86_64 指令集docker buildx build --platform linux/amd64 -t android-emulator:latest .需要说明的是在 Apple Silicon 上以这种方式运行时实际上是在 Linux 模拟器中再运行一个 Android 模拟器模拟器嵌套速度会明显慢于原生运行方式。运行 Benchmark 评测套件评测入口与核心参数上游 README 给出的全量评测命令以run.py为入口在本仓库中run.py并未随目录提供对应入口是适配后的 run_ma3.py另外还提供了 shell 包装脚本 run_ma3.sh 与 run_guiowl.sh。上游命令形式如下python run.py \ --suite_familyandroid_world \ --agent_namet3a_gpt4 \ --perform_emulator_setup \ --tasksContactsAddContact,ClockStopWatchRunning # 可选只跑子集在本仓库的 run_ma3.py 中Flag 体系得到进一步扩展关键参数如下Flag默认值说明--suite_familyandroid_world任务族可选android_world、miniwob论文子集、miniwob全量、android、information_retrievalrun_ma3.py#L90-L103--agent_namem3a_gpt4vAgent 名称本仓库的_get_agent实际支持gui_owl与mobile_agent_v3两种run_ma3.py#L165-L193--tasksNone指定要运行的具体任务逗号分隔为空则运行该任务族的全部任务--n_task_combinations1每个任务模板的参数排列数例如 SMS 任务会对应每次运行不同的电话号码/消息组合--fixed_task_seedFalse多个任务组合n_task_combinations 1时是否复用同一随机种子--task_random_seed30任务随机性种子--checkpoint_dir空断点目录若目录中存在已有检查点则从最新断点恢复评测--output_path~/android_world/runs非断点模式下结果的保存目录--traj_output_path空轨迹输出目录--model/--api_key/--base_url空模型名、API Key 与服务端地址供gui_owl/mobile_agent_v3的推理封装使用--adb_path/--perform_emulator_setup/--console_port/--grpc_port自动探测 /False/5554/8554与单任务脚本一致的设备与环境参数首次运行必须完成模拟器初始化首次运行必须携带--perform_emulator_setup用于安装评测所需的应用如 Simple Calendar Pro、Markor 等开源应用并设置相应权限这是一次性操作可能因网速花费数分钟初始化完成后后续运行都应去掉该标志。任务步数上限与断点续跑README 特别说明自 2024-11-18 起AndroidWorld 中每个任务的max_steps/step_budget已调整为约等于人类平均完成时长的 2 倍既保证 Agent 有充足时间完成任务也降低整个 Benchmark 的运行开销。评测可能中途失败或被打断此时只需用--checkpoint_dir指向原运行输出目录重新执行即可从最新断点续跑避免从头再来。运行 MiniWoB 网页任务AndroidWorld 还支持经典网页基准 MiniWoB。只需将--suite_family切换为miniwob并保持--perform_emulator_setuppython run_ma3.py --suite_familyminiwob --perform_emulator_setup ...运行 MiniWoB 任务的一个关键优势在于常见的输入组件如时间选择器、日期选择器会被渲染为原生 Android UI 控件而非 HTML 元素因此 Agent 必须学会操作通用的原生控件从 run_ma3.py#L156-L163 可以看到针对 MiniWoB 任务还有两处专门的适配一是将transition_pause缩短为0.2秒MiniWoB 页面切换快无需等待屏幕稳定二是注入额外提示词指导要求 Agent必须停留在 mock 应用内、禁止使用navigate_home动作避免 Agent 离开任务页面。创建你自己的 AgentAndroidWorld 的 Agent 体系采用抽象基类 具体实现的分层设计仓库内的 android_world/agents/README.md 对其做了系统介绍官方实现包括M3A多模态 Agent同时使用截图与 UI 元素的文本描述基于 Set-of-Mark 动作空间、T3A纯文本版仅依赖 UI 元素的文本表示、以及SeeAct基于视觉定位的两阶段推理 Agent。按照 README自定义 Agent 只需三步继承基类并实现step方法创建继承自EnvironmentInteractingAgent的 Agent 类。该基类定义在 base_agent.py#L40-L127核心是抽象方法step(goal)与数据类AgentInteractionResult含done与data两个字段。基类还通过transition_pause默认 1.0 秒控制动作执行后抓取屏幕状态的等待时间若传入None则进入自动模式依据环境反馈动态调整等待时长见 base_agent.py#L48-L116。典型的一次step流程是通过env实例获取当前截图与 UI 元素列表 → 选择支持的动作 → 通过env.execute_action执行 → 返回AgentInteractionResult并在任务完成时将done置为True。AndroidWorld 的动作空间是一组 JSON 格式动作以 T3A 为例t3a.py#L26-L71包括{action_type: click, index: 目标元素索引}{action_type: long_press, index: 索引}{action_type: input_text, text: 文本, index: 索引}含点击输入框、输入文本、按回车{action_type: keyboard_enter}、{action_type: navigate_home}、{action_type: navigate_back}、{action_type: wait}{action_type: scroll, direction: up/down/left/right, index: 可选}{action_type: open_app, app_name: 应用名}{action_type: answer, text: 回答}与{action_type: status, goal_status: complete | infeasible}T3A 的完整step实现还体现了动作选择 步骤摘要的双阶段 LLM 调用设计t3a.py#L301-L485先基于目标、历史摘要与当前 UI 元素描述让模型输出Reason: ...Action: {...}解析出动作后执行再基于动作前后两帧 UI 描述生成一段单行摘要加入历史作为后续动作选择的记忆。注册 Agent在run.py本仓库对应 run_ma3.py中导入你的 Agent 类并加入_get_agent方法run_ma3.py#L165-L193该方法根据agent_name返回对应的 Agent 实例。运行评测用上述评测命令将--agent_name改为你的 Agent 名称即可。新增评测任务关于如何向 AndroidWorld 添加新任务仓库提供了完整的分步指南 docs/tasks_guide.md。其核心思想是评测任务的可复现性取决于对应用底层数据的读写与验证。指南聚焦 Android 应用最常见的两种数据存储方式SQLite 数据库与文件系统。第一步判断应用的数据存储方式通过 ADB 访问应用数据目录# 列出应用数据目录 adb shell ls data/data/package_name/ # 检查是否存在 databases 目录存在 .db 文件说明使用 SQLite adb shell ls data/data/com.simplemobiletools.calendar.pro/databases/ # 检查是否存在 files 目录存在 .txt/.json 等文件说明使用文件系统 adb shell ls data/data/package_name/files/第二步探查数据库结构与文件内容# 查看 SQLite 表结构 adb shell sqlite3 data/data/com.simplemobiletools.calendar.pro/databases/events.db .schema Events # 查询表数据 adb shell sqlite3 data/data/com.simplemobiletools.calendar.pro/databases/events.db SELECT * FROM events; # 查看文件内容或拉取到本地分析 adb shell cat data/data/package_name/files/file_name.txt adb pull data/data/package_name/files/file_name.txt /local/directory/第三步以 SQLite 为例新增任务AndroidWorld 通过抽象类如sqlite_validators.AddMultipleRows、sqlite_validators.validate_rows_addition_integrity封装了与 SQLite 交互及校验新增行的核心逻辑开发者只需专注任务定义。以 Simple Calendar Pro 的新增日历事件任务为例编写步骤为定义与表结构对应的数据类dataclasses.dataclass(frozenTrue) class CalendarEvent: start_ts: int end_ts: int title: str location: str description: str repeat_interval: int 0 repeat_rule: int 0创建基类声明数据库路径、表名与行类型class _SimpleCalendar(sqlite_validators.SQLiteApp): Base class for calendar tasks and evaluation logic. app_name_with_db simple calendar pro app_names (simple calendar pro,) db_key id db_path data/data/com.simplemobiletools.calendar.pro/databases/events.db table_name events row_type CalendarEvent实现任务类定义template任务模板{...}为随机参数占位符、complexity决定步数预算、_get_random_target_row随机参数生成与校验逻辑class SimpleCalendarAddOneEvent(sqlite_validators.AddMultipleRows, _SimpleCalendar): Task for creating a calendar event in Simple Calendar Pro. complexity 2 template ( In Simple Calendar Pro, create a calendar event on {year}-{month}-{day} at {hour}h with the title {event_title} and the description {event_description}. The event should last for {duration_mins} mins. ) classmethod def _get_random_target_row(cls) - CalendarEvent: Generates a random calendar event. return events_generator.generate_event( datetime_utils.create_random_october_2023_unix_ts() ) def validate_addition_integrity(self, before, after): # 校验新行是否被正确写入数据库并返回成功率 ...验证器将任务是否成功落实为可编程断言——这正是 AndroidWorld 奖励信号持久化的关键所在无论 Agent 采取何种 UI 操作路径最终都要落到数据库中的真实数据变化。文件系统存储型应用以 Markor 为例的扩展思路与之相同仅将验证对象从数据库表替换为文件内容。结语AndroidWorld 为 GUI Agent 提供了一套高复现性、强可扩展的评测环境真实模拟器 动态任务实例化 持久化数据级奖励信号。在本仓库的 Mobile-Agent-v3/android_world_v3 目录下你既可以借助minimal_task_runner.py快速跑通单任务流程、通过run_ma3.py执行全量 Benchmark也可以参考docker_setup/与scripts/run_suite_on_docker.py实现容器化部署还能基于base_agent.py与docs/tasks_guide.md扩展自己的 Agent 与评测任务。若在研究中使用了本环境或数据请按照上游 README 引用 AndroidWorld 论文Rawles et al., 2024, arXiv:2405.14573。需要注意的是本项目并非 Google 官方支持产品。【免费下载链接】MobileAgentMobile-Agent: The Powerful GUI Agent Family项目地址: https://gitcode.com/GitHub_Trending/mo/MobileAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
