Mobile-Agent-v2 实战指南基于多智能体协作与增强视觉感知的移动设备操作助手【免费下载链接】MobileAgentMobile-Agent: The Powerful GUI Agent Family项目地址: https://gitcode.com/GitHub_Trending/mo/MobileAgent导读Mobile-Agent-v2 是 Mobile-Agent 系列的第二代移动设备操作助手针对长上下文图文交错输入下的导航Navigation难题提出了多智能体协作 增强视觉感知 GPT-4o 驱动的解决方案论文发表于 arXiv2406.01014并被 NeurIPS 2024 接收。本文基于仓库中 Mobile-Agent-v2/README.md 与 Mobile-Agent-v2/run.py、Mobile-Agent-v2/MobileAgent/prompt.py 等源码完整讲解从环境安装、ADB 连接、run.py参数配置到多智能体运行原理与调优的实战全流程。读完本文你将能够独立部署 Mobile-Agent-v2在 Android / HarmonyOS 设备上执行自然语言指令并理解 Action、Reflection、Planning、Memory 等智能体各自的职责与协作机制。Mobile-Agent-v2 解决的核心问题与三大特性Mobile-Agent-v2 的出发点非常明确在长上下文的图文交错输入场景中如何让模型知道当前在哪、接下来该去哪。单纯把整条操作轨迹历史截图、历史动作、文本信息一次性塞给大模型会带来严重的上下文膨胀与导航迷失问题。为此v2 提出了三大关键技术方案见 Mobile-Agent-v2/README.md多智能体架构将感知—反思—规划—记忆拆分为多个职责单一的智能体各自只处理自己负责的上下文从根源上缓解长上下文导航困难增强的视觉感知模块通过 OCR 文本定位 GroundingDINO 图标检测 图标语义描述的多级组合显著提升操作坐标的准确率GPT-4o 支持以 GPT-4o 作为决策大模型进一步提升操作的性能与速度。下图为仓库提供的 Mobile-Agent-v2 整体架构示意图直观展示了各智能体与视觉感知模块之间的协作关系图片来源Mobile-Agent-v2/assets/role.jpg说明Mobile-Agent-v2 已公开在线 Demo支持上传手机截图直接体验无需配置模型与设备并在 NeurIPS 2024 接收。仓库同时提供英文版 Mobile-Agent-v2/README.md 与中文版 Mobile-Agent-v2/README_zh.md 两份文档本文内容以英文版为主、中文版为辅。系统支持范围与适用前提在开始之前请先确认目标设备是否在支持范围内。根据 Mobile-Agent-v2/README.md 的明确说明支持Android OS 与 Harmony OS版本号 ≤ 4可以进行工具调试暂不支持iOS 等其他系统。此外Mobile-Agent-v2 的决策核心依赖 OpenAI 兼容的 GPT-4o API图标描述模型则可在本地部署或调用 Qwen-VL API 两种方式中二选一详见下文选择运行方式一节。这意味着你需要准备一台可连接电脑的 Android/HarmonyOS 设备、一条数据线、可用的 GPT-4 APIURL 与 Token以及可选的 Qwen-VL API Key 或高性能 GPU。安装依赖进入仓库的 Mobile-Agent-v2 目录后执行pip install -r requirements.txt依赖清单见 Mobile-Agent-v2/requirements.txt主要包括依赖说明torch/torchvision/transformers本地模型推理基础框架modelscope1.15.0下载 GroundingDINO、Qwen-VL 等模型并加载 OCR pipelineTensorFlow2.19.0/keras3.5.0/tf_keras/tf_slimGroundingDINO 依赖的深度学习运行环境dashscope调用 Qwen-VL 云端 APIqwen-vl-plus/qwen-vl-maxopencv-python/numpy1.26.4图像处理与坐标运算supervision0.21.0/pycocotools/timm/pyclipper/shapely目标检测后处理与标注CLIPgit 安装视觉语义能力支撑提示requirements.txt中锁定了modelscope1.15.0与numpy1.26.4等版本若你的环境中已有其他版本的包建议使用虚拟环境安装避免版本冲突导致 GroundingDINO pipeline 无法加载。准备 ADB 连接移动设备Mobile-Agent-v2 通过Android Debug BridgeADB完成截图、点击、滑动、输入、返回、回到桌面等全部设备操作。连接步骤如下见 Mobile-Agent-v2/README.md 的 Preparation for Connecting Mobile Device with ADB 一节下载 ADBplatform-tools获取 Android Debug Bridge 工具包Android 官方 platform-tools 发行版开启 ADB 调试在手机的开发者选项中打开USB 调试或ADB 调试。如果设备是HyperOS 系统还需要同时打开USB 调试安全设置否则后续模拟点击可能无权限连接设备用数据线将手机与电脑相连并在手机的连接选项中选择传输文件Transfer files模式验证连接执行以下命令若输出的设备列表不为空则连接成功/path/to/adb devices权限设置macOS / Linux先为 adb 可执行文件开启执行权限sudo chmod x /path/to/adbWindowsadb 路径形如xx/xx/adb.exe而 macOS / Linux 下形如xx/xx/adb。这一步得到的 adb 完整路径将直接填入run.py的adb_path配置项。在手机上安装 ADB 键盘由于 ADB 无法像真实键盘一样直接输入任意字符Mobile-Agent-v2 依赖开源的ADBKeyboard应用完成文本输入安装与切换步骤对应 README 的 Install the ADB Keyboard 一节下载 ADBKeyboard 的apk 安装包在移动设备上点击该 apk 完成安装在系统设置中将默认输入法切换为 ADB Keyboard。ADB 键盘的作用可以从源码中得到印证在 Mobile-Agent-v2/MobileAgent/controller.py 的type()函数中英文字母、数字与常用符号通过adb shell input text直接发送而中文等无法用input text表达的字符则通过adb shell am broadcast -a ADB_INPUT_TEXT --es msg 字符广播给 ADBKeyboard 应用输入。同时run.py主循环会检测截图中是否出现 ADB Keyboard 文字块以判断当前键盘是否激活详见后文键盘状态感知小节。选择适合你的运行方式run.py配置详解Mobile-Agent-v2 的所有运行配置都集中在 Mobile-Agent-v2/run.py 顶部注释区### Edit your Setting ###与### ###################### ###之间。打开run.py后从第 22 行起依次填写你的配置。配置参数总览配置项默认值必填/选填说明adb_path必填ADB 可执行文件的完整路径如/path/to/adbWindows 为xx/xx/adb.exeinstruction必填你希望移动设备完成的自然语言指令如打开设置并把字体调到最大API_url必填GPT-4o 的 API URLOpenAI 兼容的 chat/completions 接口地址token必填调用 GPT-4o API 的 Tokencaption_call_methodapi必填图标描述模型的调用方式可选api云端 Qwen API或local本地部署caption_modelqwen-vl-plus必填图标描述模型名称api 方式可选qwen-vl-plus/qwen-vl-maxlocal 方式可选qwen-vl-chat/qwen-vl-chat-int4qwen_api选填选择 api 方式时必填Qwen-VL 的 API Keyadd_info内置示例选填附加操作知识/提示帮助 Agent 更准确地完成指令reflection_switchTrue选填是否启用反思智能体reflection agentmemory_switchTrue选填是否启用内存单元memory unitrun.py中默认的add_info示例为add_info If you want to tap an icon of an app, use the action \Open app\. If you want to exit an app, use the action \Home\即提示 Agent 打开应用图标时优先使用Open app动作、退出应用时使用Home动作这能显著减少点击坐标的误差。方式一local本地部署图标描述模型如果你的设备配备高性能 GPU推荐使用local方法即把图标描述模型部署在本地caption_call_method local caption_model qwen-vl-chat # 或 qwen-vl-chat-int4 qwen_api # 本地方式下 qwen_api 可以留空从 Mobile-Agent-v2/run.py 的模型加载逻辑可以看到qwen-vl-chat通过modelscope的snapshot_download(qwen/Qwen-VL-Chat, revisionv1.1.0)下载 7B 量级模型并加载到 CUDA占用更多 GPU 显存但性能更好qwen-vl-chat-int4下载qwen/Qwen-VL-Chat-Int4revisionv1.0.04-bit 量化版本显存占用更低性能略逊于完整版。如果你的设备不足以运行 7B 量级的 LLM则应选择下面的 api 方式。方式二api调用 Qwen-VL 云端 APIcaption_call_method api caption_model qwen-vl-plus # 或 qwen-vl-max qwen_api sk-xxxx # 申请到的 Qwen-VL API-KEY两种云端模型的对比如下qwen-vl-plus成本较低速度较快qwen-vl-max费用更高但性能更好。使用 api 方式时你需要提前申请 Qwen-VL 的 API-KEY 并填入qwen_api。Mobile-Agent-v2/run.py 中的process_image()通过dashscope.MultiModalConversation.call(modelcaption_model, ...)发起调用且会在调用失败时兜底返回This is an icon.保证感知信息不中断。一个值得注意的实现细节是api 方式下所有裁剪出的图标会通过concurrent.futures.ThreadPoolExecutor线程池并行请求见 Mobile-Agent-v2/run.py 的generate_api()从而保证多图标场景下的整体效率而 local 方式则在同一进程内串行生成描述。操作知识注入add_infoadd_info本质上是注入到提示词中的Hint信息。查看 Mobile-Agent-v2/MobileAgent/prompt.py 可以看到get_action_prompt()会将其渲染进### Hint ###段落同时 Mobile-Agent-v2/MobileAgent/prompt.py 的get_process_prompt()规划 Agent也会使用同一份add_info。因此把完成指令所需的特定步骤写进add_info可以同时引导决策和规划两个环节大幅提升任务成功率。速度与成功率的取舍两个开关reflection_switch决定是否在流程中加入反思智能体reflection agent。开启True每步操作后反思智能体会对比操作前后的两张截图判断操作是否达到预期出错时可回退或重试成功率更高关闭False跳过反思环节显著提升运行速度但一旦某步操作失误将无法及时发现并纠正可能让操作陷入死循环。官方建议若关闭可通过add_info注入更充分的操作知识来规避风险。memory_switch决定是否在流程中加入内存单元memory unit。开启TrueAgent 会把截图中对后续操作有用的关键信息如某应用内的登录账号、特定页面元素位置记录下来在之后的决策中复用关闭False若你的指令不需要依赖之前屏幕中的信息即可逐步完成可以关闭以提升速度。多智能体协作架构与执行流程源码级解析Mobile-Agent-v2 的核心创新在于把传统单一大模型读全部历史的范式拆解为多个各司其职的智能体。整个决策循环位于 Mobile-Agent-v2/run.py 的while True主循环中。下面按执行顺序逐一说明各智能体的职责、提示词结构与触发时机。1. 感知层截图 OCR 图标检测每步循环的起点每个循环开始先由get_perception_infos()Mobile-Agent-v2/run.py完成感知get_screenshot(adb_path)通过 ADB 截取当前屏幕screencap -p后pull到本地并转为 JPEG见 Mobile-Agent-v2/MobileAgent/controller.pyocr()使用两个 ModelScope pipeline 完成文本检测与识别检测用damo/cv_resnet18_ocr-detection-line-level_damo识别用damo/cv_convnextTiny_ocr-recognition-document_damo见 Mobile-Agent-v2/MobileAgent/text_localization.py 与 Mobile-Agent-v2/run.pymerge_text_blocks()将坐标相近、行高一致的多行文本块合并成一条感知信息Mobile-Agent-v2/run.py避免一个大按钮被 OCR 拆成多条碎片文本det()使用 GroundingDINO 检测icon类目标并通过remove_boxes()过滤过大/重复的检测框Mobile-Agent-v2/MobileAgent/icon_localization.py模型由snapshot_download(AI-ModelScope/GroundingDINO)获取将每个图标区域crop出来交给图标描述模型local/api 二选一生成一句语义描述例如这是一个红色的分享箭头图标最终把文本内容 图标语义 中心点坐标打包成perception_infos供决策智能体使用。需要说明的是最终写入提示词的坐标是归一化坐标感知阶段先取检测框中心点[(x1x2)/2, (y1y2)/2]见 Mobile-Agent-v2/run.py随后在 Mobile-Agent-v2/run.py 中转换为整数最后在 Mobile-Agent-v2/MobileAgent/prompt.py 中明确告诉模型坐标格式为 [x, y]x 为从左到右的像素y 为从上到下的像素。2. Action Agent动作决策智能体gpt-4oAction Agent 是每步循环的核心决策者。它接收的输入包括当前截图、perception_infos文本图标坐标、屏幕宽高、键盘状态、历史操作摘要、add_info提示、已完成进度、内存信息与上一步错误标志。提示词由get_action_prompt()生成Mobile-Agent-v2/MobileAgent/prompt.py结构如下### Background ###屏幕尺寸与用户指令### Screenshot information ###感知层输出的所有可点击元素坐标与内容并提醒模型该信息不一定准确需结合截图理解### Keyboard status ###当前键盘是否激活决定能否 Type### Hint ###add_info注入的操作知识可选### History operations ###历史操作步骤Operation/Action### Progress ###规划智能体产出的已完成内容可选### Memory ###内存单元记录的关键信息可选### Last operation ###若上一步被判定出错error_flagTrue提示模型需要反思并修正### Response requirements ###只能从Open app (app name)、Tap (x, y)、Swipe (x1,y1), (x2,y2)、Type (text)、Home、Stop六种动作中选择一种执行键盘未激活时禁止 Type模型必须先点输入框唤起键盘### Output format ###要求输出三段结构——### Thought ###思考/### Action ###动作/### Operation ###自然语言操作描述。run.py主循环对输出做了解析thought取Thought段、summary取Operation段、action取Action段Mobile-Agent-v2/run.py随后进入动作执行分支详见后文动作执行。3. Memory Agent内存智能体gpt-4o若memory_switchTrue在执行动作前会先运行内存提取Mobile-Agent-v2/run.py提示词由get_memory_prompt(insight)生成Mobile-Agent-v2/MobileAgent/prompt.py让模型判断当前页面上是否有与用户指令或上一轮记忆的insight密切相关的内容若有则输出若无则输出None输出会按### Important content ###切分去重后累积到全局变量memory中累积的memory会在后续 Action Agent 的### Memory ###段落中持续注入实现跨步骤的信息记忆。4. 动作执行与 ADB 控制根据action内容主循环会分发到 Mobile-Agent-v2/MobileAgent/controller.py 中对应的函数动作Action对应函数底层 ADB 命令Open app (app_name)先 OCR 定位应用名再tapshell input tap x y点击位置在应用名上方Tap (x, y)tap()shell input tap x ySwipe (x1,y1), (x2,y2)slide()shell input swipe x1 y1 x2 y2 500500ms 时长Type (text)type()英数符号用shell input text其他字符走ADB_INPUT_TEXT广播Backback()shell input keyevent 4Homehome()am start -a android.intent.action.MAIN -c android.intent.category.HOMEStop—主循环break任务结束值得注意的是Open app的实现细节Mobile-Agent-v2/run.py它并不会直接调用am start拉起应用而是对当前桌面截图做 OCR 找到应用名对应的文本框然后点击该文本中心偏上方的位置y - 文本高度以此命中应用图标。这也是 README 默认add_info里提示打开应用请用 Open app 动作的原因。动作执行后主循环time.sleep(5)等待页面渲染完成并把当前截图重命名为last_screenshot.jpg保存Mobile-Agent-v2/run.py供反思智能体对比。5. Reflection Agent反思智能体gpt-4o若reflection_switchTrue每步操作后都会运行反思Mobile-Agent-v2/run.py输入操作前截图last_screenshot.jpg与操作后截图screenshot.jpg两张图片add_response_two_image会把两张截图都 base64 编码进多模态消息见 Mobile-Agent-v2/MobileAgent/chat.py提示词get_reflect_prompt()Mobile-Agent-v2/MobileAgent/prompt.py要求模型输出 A/B/C 三选一的判定A操作结果符合预期 → 记录本轮 thought/summary/action交由规划智能体更新进度并清除错误标志B操作导致跳到了错误的页面 → 设置error_flagTrue并执行back()返回上一页C操作未产生任何变化 → 设置error_flagTrue下一轮决策时会收到上一步失败的提醒### Last operation ###从而重新规划动作。这套操作—对比—纠错闭环正是多智能体架构在导航鲁棒性上的核心收益即使决策偶尔失误反思智能体也能及时把 Agent 拉回正确路径。6. Planning Agent规划智能体gpt-4-turbo反思确认无误或reflection_switchFalse时每步都会触发规划环节Mobile-Agent-v2/run.py提示词get_process_prompt()Mobile-Agent-v2/MobileAgent/prompt.py基于用户指令与历史操作序列让模型输出**### Completed contents ###**——即到目前为止已经实际完成了哪些子目标的更新摘要该摘要写入completed_requirements在下一轮 Action Agent 的### Progress ###段落中注入。注意到决策使用 gpt-4o、规划使用 gpt-4-turbo见 Mobile-Agent-v2/run.py 与 Mobile-Agent-v2/run.py这正是多智能体 不同模型分工的体现决策看重多模态感知与动作精度规划看重长程任务分解与摘要能力。一次完整循环的时间线截图 OCR 图标检测 → 生成perception_infosAction Agent 输出 Thought/Action/Operation可选Memory Agent 提取关键信息存入 memory执行动作Tap/Swipe/Type/…sleep 5 秒等待渲染可选Reflection Agent 对比前后截图输出 A/B/C若是 A 或关闭反思Planning Agent 更新已完成内容若 action 为Stop结束循环。运行 Mobile-Agent-v2完成全部配置后在 Mobile-Agent-v2 目录下执行python run.py程序启动时会依次完成以下初始化见 Mobile-Agent-v2/run.py根据caption_call_method加载图标描述模型local 方式会下载 Qwen-VL-Chat 系列模型到本地下载并加载 GroundingDINO 图标检测模型与 OCR 检测/识别 pipeline创建temp/存放裁剪图标与screenshot/存放截图两个工作目录若已存在会先清理重建。运行后观察控制台输出每个环节都以#分隔横幅打印DecisionAction Agent 的完整输出Thought / Action / OperationMemory内存单元提取的关键内容Reflection反思智能体的 A/B/C 判定Planning规划智能体更新的已完成内容。当 Action Agent 输出Stop时任务自动结束。常见问题与调优建议1. 设备连接失败 / 无权限确认adb devices输出中包含你的设备序列号HyperOS 用户务必开启USB 调试安全设置macOS/Linux 先执行sudo chmod x /path/to/adb赋予执行权限手机连接模式选择传输文件。2. 输入中文/特殊字符失败确认已安装 ADBKeyboard 且系统默认输入法已切换为 ADB Keyboard从 Mobile-Agent-v2/MobileAgent/controller.py 可见中文依赖am broadcast -a ADB_INPUT_TEXT广播通道若未切换到 ADB Keyboard该广播将被忽略。3. 本地模型显存不足将caption_model从qwen-vl-chat改为qwen-vl-chat-int4量化版显存更低若显存仍不足改用 api 方式caption_call_method api。4. 操作陷入死循环反思智能体理论上会在 B/C 场景纠错但仍可能出现反复README 建议把完成指令的具体步骤写进add_info从源头减少错误动作若对速度要求高、且指令简单明确可将reflection_switch与memory_switch设为False代价是成功率可能下降。5. 网络错误GPT-4o 调用封装在 Mobile-Agent-v2/MobileAgent/api.py 的inference_chat()中请求参数固定max_tokens2048、temperature0.0、seed1234保证输出确定性失败时进入while True无限重试并打印错误响应。请确保API_url与token正确且网络可达。结语Mobile-Agent-v2 通过感知增强 多智能体协作 GPT-4o 驱动的组合拳系统性地解决了移动端长上下文操作中的导航问题Action Agent 负责一步一动Reflection Agent 负责操作校验与纠错Planning Agent 负责进度归纳Memory Agent 负责关键信息跨步记忆。本文从环境准备、参数配置到源码级原理给出了完整讲解你可以直接基于仓库中的 Mobile-Agent-v2/run.py 与 Mobile-Agent-v2/MobileAgent 目录下的模块自行验证与二次开发。若该工作对你有帮助可参考仓库 README 末尾提供的 BibTeX 条目引用论文。【免费下载链接】MobileAgentMobile-Agent: The Powerful GUI Agent Family项目地址: https://gitcode.com/GitHub_Trending/mo/MobileAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考