agentic-android

# 代理安卓 通过ADB控制安卓手机或模拟器与大型语言模型（LLM）交互。代理读取屏幕，选择操作（点击、滑动、输入、启动应用），通过`adb`执行，检查结果，并重复直到任务完成。无需root，无需在设备上安装任何软件。 它与Claude（通过`claude`命令行工具或Anthropic API）、OpenAI或任何OpenAI兼容的端点以及通过Ollama或LM Studio的本地模型配合使用。 <p align="center"> <img src="assets/demo-wallpaper.gif" alt="Agentic Android installing a wallpaper app from the Play Store and setting a new wallpaper, with the agent's console beside it" width="700"> <br> <em>手机在左侧，代理控制台在右侧。任务：从Play商店安装壁纸应用并设置新壁纸。它安装了Zedge，纠正了一个错误的包名<code>list_apps</code>（<code>com.zedge.android</code>→<code>net.zedge.android</code>），当Zedge的预览返回空白截图时，它切换到使用<code>dump_ui</code>读取UI树以完成任务。脑部是免费的<code>claude-cli</code>，无需API密钥。</em> <br><br> <a href="assets/demo-wallpaper.mp4">MP4</a> (2.2 MB) · <a href="assets/demo-wallpaper.gif">GIF</a> </p> ## 你可以要求它做的事 你像给朋友发短信一样给它一个任务，它会通过应用来完成： - “给女朋友发一条甜蜜的晚安短信” - “回复妈妈的最新WhatsApp消息，告诉她我明天会打电话给她” - “安装Spotify并播放一些轻松的音乐” - “设置6:30的闹钟并启用勿扰模式直到那时” - “从星巴克应用中订购我的常用饮品” - “预订一辆Uber回家” - “浏览我的通知，告诉我哪些需要回复” - “找到一个奶油鸡肉食谱并读出配料” - “下载壁纸应用并设置新壁纸”（上面的演示） 它只会在你要求时发送、发布、购买或登录。对于它无法撤销的操作（购买、2FA代码、密码），它会停止并询问，即使在高持久性下也是如此。参见[持久性级别](#持久性级别-05和成本)以调整它在检查之前自己会做多少工作。 ## 提供商 在`agentic-android.toml`中设置`provider`。 | `provider` | 后端 | 需要 | |--------------|---------|-------| | `claude-cli` | 你登录的**Claude Code**命令行工具，作为实时聊天运行 | `claude`命令行工具，无需API密钥 | | `anthropic` | Anthropic API | `ANTHROPIC_API_KEY` | | `openai` | OpenAI，或任何OpenAI兼容的端点（OpenRouter，Azure，本地服务器） | `OPENAI_API_KEY` | | `ollama` | 通过Ollama的本地模型 | 无，需在设备上运行 | | `lmstudio` | 通过LM Studio的本地模型 | 无，需在设备上运行 | 代理通过两种方式之一读取屏幕：作为截图（视觉模式），或作为从UI树解析的屏幕元素文本列表（文本模式）。文本模式更便宜、更快，适用于无法看到图像的纯文本模型。两者都在`agentic-android.toml`中配置。 ## 要求 1. 设备：开启USB调试的手机或模拟器。网络模拟器也支持（例如MuMu或`192.168.1.79:5555`处的模拟器VM）。 2. adb：`adbutils`依赖项附带了一个捆绑的二进制文件，因此您无需自己安装adb。如果存在系统`adb`，则使用它。可以通过`python -m agentic_android --list-devices`进行检查。 3. 脑。选择一个并在`agentic-android.toml`中设置： - `claude-cli`：安装并登录的`claude`命令行工具（运行`claude`一次）。无需API密钥。这是默认设置。 - `anthropic`：Anthropic API密钥。 - `openai`：OpenAI密钥或任何OpenAI兼容的端点，通过自定义基准URL。 - `ollama`：本地模型，无需密钥。从`http://localhost:11434/v1`自动检测加载的模型。模型需要工具调用（例如`qwen3`、`llama3.1`/`3.2`、`mistral-nemo`）；视觉模型如`qwen3-vl`或`llava`可以设置`vision = true`。使用Ollama的原生API，因此可以设置可用的上下文窗口，因为默认的4096太小。 - `lmstudio`：通过LM Studio的本地模型，无需密钥。启动服务器（开发者选项卡），加载工具调用模型（Gemma 4，Qwen，Llama 3.x），它会自动从`http://localhost:1234/v1`检测。设置模型加载时的宽容长度。 ## 安装 使用启动器。它在第一次运行时创建自己的虚拟环境，因此它永远不会触及系统Python： ```bash ./run.sh --list-devices # Linux/macOS run.bat --list-devices # Windows（或双击run.bat） ``` `run.sh`和`run.bat`是`python -m agentic_android`的包装器，因此本README中的任何参数在它们之后都有效（例如`./run.sh --provider openai "…""`）。 如果要手动安装： ```bash cd /mnt/windows/Work/Ai/projects/agentic-android python3 -m venv .venv .venv/bin/pip install -e . # 或：pip install -r requirements.txt .venv/bin/python -m agentic_android --list-devices ``` 使用虚拟环境的Python，而不是系统Python。运行`python -m agentic_android`与`/usr/bin/python`会因“没有名为agentic_android的模块”而失败。使用`./run.sh`，激活虚拟环境（`source .venv/bin/activate`），或直接调用`.venv/bin/python`。 Pillow是可选的。它只会缩略大截图以降低token成本。没有它（例如在Python 3.14中，可能缺少轮子），代理会发送全分辨率截图并且仍然有效。 ## 配置 复制模板以创建您自己的配置文件（它包含您的API密钥和设备序列号，因此它是git-ignored并且永远不会被提交）： ```bash cp agentic-android.toml.example agentic-android.toml ``` 您需要调整的所有设置都位于`agentic-android.toml`中，该文件有注释。最重要的三个设置： ```toml provider = "claude-cli" # claude-cli | anthropic | openai | ollama | lmstudio [device] serial = "192.168.1.79:5555" # 您的手机/模拟器（参见 --list-devices） [agent] effort = 3 # 0 = 尽早询问且廉价 … 5 = 尝试一切 ``` 然后填写您所选提供者的部分。对于OpenAI兼容的服务器，请将`[openai].base_url`指向它： ```toml [openai] api_key = "" # 或设置环境变量OPENAI_API_KEY base_url = "https://api.openai.com/v1" # OpenRouter，http://localhost:11434/v1等 model = "gpt-4o" # 必须支持视觉以支持视觉模式 ``` 运行没有任何参数，它会使用配置文件： ```bash python -m agentic_android ``` ## 可靠性和诊断 除了演示之外，几个功能可以保持运行。它们默认启用，可以在`[agent]`中调整： - 空白屏幕故障转移。一些应用界面无法截屏，返回黑色。代理检测到这一点（死截图是一个小PNG），并改为从UI元素列表读取屏幕，因此它继续运行而不是停滞。 - 等待空闲。在每个操作之后，它等待屏幕停止更改（最多`settle_timeout`），而不是固定延迟，因此它不会在屏幕加载一半时操作。 - 重试和超时。暂时的`adb`故障（例如网络设备断开）会重试并进行退避，LLM调用会超时，以防连接阻塞运行。 - 确认门控（可选）。设置`confirm_destructive = true`（或传递`--confirm-destructive`），代理在高风险操作前会停止并提示`y/N`：卸载、购买/支付、删除、恢复出厂设置、注销。 随时运行预检： ```bash python -m agentic_android --doctor ``` ``` Agentic Android — 预检医生 provider=ollama · device=192.168.1.79:5555 [PASS] adb 捆绑的adbutils二进制文件 [PASS] device 192.168.1.79:5555 已连接 [PASS] screenshot 1080x2400 PNG，非空白 [FAIL] ollama server 没有来自http://localhost:11434/v1的响应 → 启动`ollama serve`。 ``` 相同的检查会在每次任务之前自动运行（跳过`--no-preflight`），因此设置问题会以清晰的消息显示，而不是神秘的错误。如果恰好连接了一个设备，它会自动被选中，因此`--serial`是可选的。 ## 用法 ### 通过`claude`命令行工具进行实时聊天（无需API密钥） 这是默认设置。它使用您登录的Claude Code订阅（无需`ANTHROPIC_API_KEY`）启动一个无头Claude代理，通过MCP连接设备工具，并将您的终端中继到代理和从代理。您输入，它操作，您可以继续输入以在操作过程中引导它。 ```bash python -m agentic_android --chat -s 192.168.1.79:5555 ``` ``` you> 在我的手机上安装WhatsApp · 截图 {} agent> 打开Play商店并搜索WhatsApp。 · launch_app {"package":"com.android.vending"} · tap {"x":360,"y":140} · type_text {"text":"WhatsApp"} ... agent> WhatsApp正在安装。我会告诉你什么时候完成。 you> 也顺便安装Telegram # 在任务中途引导 ``` 聊天需要安装并登录的`claude`命令行工具（运行`claude`一次）。选项：`--model sonnet|haiku|opus`（默认`sonnet`），`--budget 2`用于美元上限（传递给`claude --max-budget-usd`）。代理在该项目目录下运行，因此其Claude Code会话历史记录与项目隔离。 ### 它是如何工作的：MCP设备服务器 `claude-cli`路径中有趣的部分是代理只是Claude Code，通过MCP（模型上下文协议）将您的手机作为工具提供给它。您重用Claude Code的整个代理循环——规划、工具使用、恢复——指向手机，在您的现有Claude订阅上运行，因此无需`ANTHROPIC_API_KEY`和每token计费。 当您运行`--chat`时，`chat.py`会执行三件事： 1. 编写一个临时的MCP配置文件，指向`python -m agentic_android.mcp_server`，一个通过stdio进行通信的小型[FastMCP](https://modelcontextprotocol.io)服务器。设备序列号、adb路径和可靠性设置作为环境变量传递给它。 2. 使用该服务器启动无头代理： ``` claude -p --input-format stream-json --output-format stream-json \ --permission-mode bypassPermissions \ --allowedTools ToolSearch,mcp__agentic_android \ --mcp-config <tmp.json> --strict-mcp-config \ --append-system-prompt "<device rules>" --model sonnet ``` 3. 双方转发。打印代理的stream-json事件（其文本和每个工具调用）并在它们到达时，将您输入的任何内容作为用户消息反馈回去——这样您可以在任务中途引导它而无需停止。 服务器（`agentic_android/mcp_server.py`）将设备暴露为MCP工具：`screenshot`、`tap`、`tap_element`、`swipe`、`type_text`、`press_key`、`launch_app`、`list_apps`和`dump_ui`。每个更改屏幕的工具都返回一个新的截图作为其结果，以便代理看到每个操作的后果（计算机使用循环）。如果捕获返回空白/黑色，则返回UI元素列表，以免受保护的界面使其失明。 为什么这样很好： - 无需API密钥和token计费 - 它依赖于您登录的Claude Code。 - 您免费获得整个代理。Claude Code已经知道如何规划、重试和链接工具，因此设备代码保持很小：它只需要公开adb。 - MCP是可移植的。`agentic_android`是一个标准的MCP服务器，因此任何MCP客户端（Claude Desktop，另一个代理）都可以附加它并驱动手机 - 没有任何内容绑定到此命令行工具。 - 它真正是多模态的。工具返回真实的截图，而不是只是文本。 - 它是隔离和自主的。它在该项目目录下运行（其自己的Claude Code会话历史记录），在`bypassPermissions`下，因此它不会在每次点击时提示，而是使用`--strict-mcp-config`，因此只有您的设备服务器被加载。 ### 持久性级别（0-5）和成本 当代理卡住或遇到模糊的选择时，它会用选项问你，而不是猜测。它在询问之前自己尝试恢复的程度是持久性级别，从0到5，在`agentic-android.toml`或使用`--effort N`设置： | 级别 | 行为 | |------:|-----------| | 0 | 在第一次模糊或失败时询问；几乎没有自我恢复 | | 1 | 快速重试一次，然后询问 | | 2 | 几次恢复尝试，然后询问 | | 3 | 默认。几种策略（重新截图、`dump_ui`、滚动、替代路径）后询问 | | 4 | 耗尽视觉和UI树方法；仅在真正阻塞时询问 | | 5 | 尝试一切；仅在无法解决时询问（密码、2FA、购买确认） | 较高的级别会使更多的截图、工具调用和模型回合在代理暂停之前进行，因此成本更高。较低的级别会更早地检查并花费更少。 ```bash python -m agentic_android --chat -s 192.168.1.79:5555 --effort 4 # 在询问之前尝试得很努力 python -m agentic_android --chat -s 192.168.1.79:5555 --effort 0 # 尽早询问，花费很少 ``` 当它在聊天中询问时，输入您的答案（一个数字或自由文本），它会继续。API代理路径使用一个`ask_user`工具，在终端中提示。 ### API代理（`anthropic`或`openai`） 在配置文件或使用`--provider`中将`provider`设置为`anthropic`或`openai`。循环是提供者无关的：它保持一个持续的对话，为每个消息发送一个新的截图，并执行操作。`ask_user`允许它在卡住时询问一个问题并提供选项。 ```bash # OpenAI，或任何OpenAI兼容的端点（注意自定义 --base-url） python -m agentic_android --provider openai "打开设置并启用飞行模式" python -m agentic_android --provider openai # 交互式聊天 # 本地模型，无需密钥（自动检测加载的模型） ./run.sh --provider ollama "打开Chrome浏览器应用" ./run.sh --provider lmstudio "打开Chrome浏览器应用" # Anthropic python -m agentic_android --provider anthropic --model claude-opus-4-8 ``` 密钥来自配置文件或环境变量（`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`）。示例任务：“打开时钟应用并设置7:30的闹钟”，“在设置中，找到安卓版本”。 ### 文本模式（适用于无法查看截图的模型） 许多模型，包括大多数本地和纯文本模型，无法读取图像。设置`vision = false`（或传递`--no-vision`），代理将停止发送截图。相反，它将屏幕描述为屏幕上解析的UI树中的带编号的列表，每个列表项都有一个点击点： ``` 屏幕 720x1280px — 45个元素。按@(x,y)点点击。 #1 [ImageView] "返回" @(48,57) [点击] #4 [ImageView] "打开通知设置" @(560,57) [点击] #9 [View] "1,380 posts" id=profile_header_post_count @(298,236) [点击] #20 [EditText] "搜索" id=search_input @(360,140) [点击，输入] ``` 模型点击它想要的元素的`@(x,y)`（坐标是实际设备像素）。在提供者中启用它： ```toml [openai] model = "llama3.2-vision" # 或任何文本模型 vision = false ``` ```bash python -m agentic_android --provider openai --base-url http://localhost:11434/v1 --no-vision ``` 视觉能力仍然更好，当模型支持时。文本模式是一种备用方案，使非视觉模型可用。 ### 技能：一次学习，随处运行 记录任务一次（LLM会执行），步骤将保存为确定性的、自我修复的技能。重放它驱动设备，无需LLM调用；如果UI更改，它会修复受影响的步骤并更新技能。 ```bash # 记录（需要API提供者——可控循环） python -m agentic_android --provider openai --record "打开时钟应用并启动计时器" --as timer python -m agentic_android --run-skill timer # 重放，几乎为零LLM成本 python -m agentic_android --skills # 列出已保存的技能 ``` 技能存储在`data/skills/<name>.json`（git-ignored）。在重放时，代理首先尝试挖掘一个`am start`快捷方式来跳过导航，然后运行每个步骤，根据它期望的屏幕进行验证；如果步骤不再匹配，则用一次LLM调用修复它，并将修复写入回去，因此每次更改的成本仅需支付一次。您还可以将`--chat`会话的调试日志转换为技能，使用`--import-trace debug/session-*.jsonl`。输入到密码/OTP字段的机密信息永远不会被存储——这些步骤被标记为实时重放。 ### 保障和自我验证的任务 给予任务必须遵守的规则和验证成功条件。确定性规则在每次步骤后从UI树中检查（免费）；自然语言成功/禁止检查在结束时由模型判断（并且可选地在每个N步骤后使用`--judge-frequency`）。 ```bash python -m agentic_android --provider openai "打开购物车并检查总额" \ --stay-in-app com.amazon.mShop.android.shopping \ --forbid "立即购买" --forbid "下单" \ --assert "购物车总额显示且未下单" \ --on-violation rewind ``` 在违规时，它停止（默认），回滚到上一个良好屏幕并尝试另一条路径（`--on-violation rewind`），或询问您（`ask`）。在结束时，它打印一个判决（哪些规则成立，是否验证成功）和退出状态码（如果防护失败，则代码3）。规则也可以存储在文件中：`--guardrails task.toml`。在`claude-cli`路径上，规则作为设备级阻止在禁止点击上执行，加上代理提示中的指令；API提供者在线路中强制执行它们。 ### 更友好的CLI（样式化输出 + 内联截图） 安装`rich`后（`pip install rich`或`ui`/`full`额外功能），聊天获得状态栏、面板和彩色工具调用。在支持内联图像的终端（kitty、iTerm2）中，它还会绘制每个操作后的手机屏幕；在其他终端中，它会退回到文本。在通过管道或重定向输出时，它始终是纯文本，因此记录和日志保持干净。 使用 `--ui auto|rich|plain` 和 `--inline-screen auto|on|off` 控制它（或 `[ui]` 部分）。 ## 调试 添加 `--debug`（或 `[agent] debug = true`）以保存运行的每个 API 请求和响应到 `debug/session-<timestamp>.jsonl`，每行一个 JSON 对象： ```bash ./run.sh --provider openai --no-vision --debug "打开时钟应用" ``` - 对于 `anthropic` 和 `openai`：每个请求（模型、消息、工具）及其响应，包括令牌 `usage`。Base64 截图被编辑为大小标记，以便文件保持可读；文本元素列表保持原样。 - 对于 `claude-cli`：代理的完整原始流式 JSON（每个工具调用、结果和消息）。 `debug/` 被 git 忽略。使用 `--debug-dir <path>` 更改写入位置。 ## 布局 | 文件 | 角色 | |------|------| | `agentic_android/adb.py` | 薄 adb 包装：截图、输入点击/滑动/文本/按键、uiautomator 转储、应用启动。 | | `agentic_android/device.py` | 截图捕获，可选缩放；将图像坐标映射回真实设备像素。 | | `agentic_android/mcp_server.py` | MCP stdio 服务器，暴露设备工具（由 `claude-cli` 提供程序使用）。 | | `agentic_android/chat.py` | 启动带有 MCP 服务器附加的 `claude` CLI 代理，并中继终端聊天。 | | `agentic_android/brains.py` | 提供程序后端（`AnthropicBrain`、`OpenAIBrain`、`OllamaBrain`）在单个接口后面。 | | `agentic_android/agent.py` | 提供程序无关的代理循环；一次性 `run()` 和交互式 `chat()`。 | | `agentic_android/tools.py` | 工具模式（由 `brains.py` 转换为 OpenAI 函数格式）。 | | `agentic_android/config.py` | 加载 `agentic-android.toml` 和持久性级别文本。 | | `agentic_android/doctor.py` | 预检检查（ `--doctor`）、设备自动检测、提供程序可达性。 | | `agentic_android/skills.py` | 记录 / 重放 / 自我修复技能（学习一次，运行免费）。 | | `agentic_android/guardrails.py` | 禁止状态 + 成功断言检查、判决、重放。 | | `agentic_android/ui.py` | 样式化 CLI 输出 + 内联截图（可选 `rich`）。 | | `agentic_android/__main__.py` | CLI：提供程序、设备和调度。 | API 代理默认为 `claude-opus-4-8`。坐标返回值在显示的图像的像素空间中；`Device.scale` 将它们转换为物理像素，以便点击落在正确的位置，即使截图被缩减。 ## 注释和限制 - `type_text` 通过 `adb shell input text`。它会转义常见字符，但最适合纯 ASCII。对于不常见的 Unicode，请使用屏幕键盘或每个应用程序的文本方法。 - 这会自动执行您指向的任何设备。在运行破坏性任务之前，请查看任务并启用 `confirm_destructive` 以在高风险操作（卸载、购买、删除、恢复出厂设置、退出）之前提示。 - 每个步骤使用一组操作，以保持循环可读。提高 `--max-steps` 以适应更长的流程。 ## 可能的添加 - 基于 `dump_ui` 的 `scroll_to_text` / `tap_text` 助手，用于更稳定的定位。 - 用于快速跨应用路由的持久导航图；多设备扇出。 - 触发/监视模式（当通知或屏幕条件触发时执行操作）。 ## 许可证 MIT。参见 [LICENSE](LICENSE)。版权所有 (c) 2026 Bhavik Patel。