AgentDroid

AgentDroid 是一个基于 FastAPI 构建的开源服务器，旨在通过 自然语言指令 控制 Android 设备完成各类操作。它集成了视觉理解与语言模型能力，通过 ADB（Android Debug Bridge）实现对真实设备的底层控制，适用于自动化测试、电商操作、日常任务批量处理等场景。

项目采用 双引擎架构，兼顾轻量级快速响应与复杂任务的高可靠性执行，支持同步与异步调用，并提供了完整的 RESTful API 和 Docker 部署方案。

核心架构与特性

1. 双引擎设计：适配不同复杂度任务

• V1 引擎：单智能体模式，适用于指令明确、步骤简单的操作（如“打开微信”），执行速度快，资源占用低。
• V4 引擎：基于多智能体协作框架，引入任务规划器（Manager）、执行器（Executor）、反思器（Reflector）和记录器（Notetaker），能处理模糊、多跳、需容错的复杂任务（如“在淘宝搜索 iPhone 并加入购物车”），具备更高的成功率和错误恢复能力。

2. 真实设备控制能力

通过 ADB 与 Android 设备建立连接，支持点击、滑动、文本输入、应用启动等基础操作，并结合屏幕截图进行视觉感知，形成“观察–决策–执行”闭环。

3. 多模态 AI 支持

后端可对接 OpenAI GPT-4V、Claude 3、阿里通义千问（Qwen）或本地部署的 vLLM 服务，支持视觉+语言联合推理，使模型能“看懂”界面并作出合理操作。

4. 异步任务与回调机制

提供 /run-agent-v4-async 等异步接口，任务在后台运行，完成后可自动通知指定回调 URL，便于集成到工作流系统或 Web 应用中。

5. 标准化 API 与容器化部署

• 所有功能通过 RESTful API 暴露，参数结构清晰，便于脚本调用或前端集成。
• 提供 Dockerfile，支持一键构建与运行，适配 CI/CD 或私有服务器部署。

快速上手指南

环境依赖

• Python 3.8 或更高版本
• 一台已开启 USB 调试 的 Android 设备
• ADB 工具（可通过 Android SDK 或独立安装）
• OpenAI API 密钥，或本地运行的 vLLM 服务（兼容 OpenAI API 格式）

安装与启动

# 克隆项目
git clone https://github.com/sav7ng/AgentDroid.git
cd AgentDroid

# 安装依赖
pip install -r requirements.txt

# 确认设备连接
adb devices  # 需显示授权设备

# 启动服务
python main.py

服务默认运行在 http://localhost:9777。

Docker 部署（推荐用于生产环境）

# 构建镜像
docker build -t agentdroid .

# 运行容器（需挂载 USB 总线以访问设备）
docker run -p 9777:9777 -v /dev/bus/usb:/dev/bus/usb --privileged agentdroid

典型应用场景

项目大量借鉴了阿里巴巴 MobileAgent 的设计理念，并在其基础上扩展了 Web 服务、异步任务、回调机制和部署灵活性。代码遵循 MIT 开源协议，欢迎贡献与二次开发。