agent-android 1.4.0
Android ADB automation CLI tool - Designed for AI Agents
License: Apache-2.0
Requires Python: >=3.7
Keywords: android, automation, adb, testing, rpa, ai, agent, cli, mobile, screenshot, uiautomator

# agent-android

> Android ADB automation CLI tool - Designed for AI Agents

[![PyPI version](https://badge.fury.io/py/agent-android.svg)](https://badge.fury.io/py/agent-android)
[![Python](https://img.shields.io/badge/python-3.7+-brightgreen.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)](https://developer.android.com/studio/command-line/adb)
[![PyPI downloads](https://img.shields.io/pypi/dm/agent-android.svg)](https://pypi.org/project/agent-android/)

**agent-android** is an ADB-based Android device automation CLI tool that fully mirrors the design philosophy of [agent-browser](https://github.com/vercel-labs/agent-browser), providing powerful and simple Android automation capabilities for AI Agents.

## ✨ Features

- 🤖 **AI Friendly** - Snapshot + Ref mode, designed specifically for AI
- 🎯 **Simple & Intuitive** - Natural language descriptions, no programming knowledge needed
- ⚡ **Fast & Efficient** - Pure Python implementation, lightweight dependencies
- 🔧 **Flexible & Powerful** - Dual interface: CLI + Python API
- 🌍 **Multi-language** - Full Chinese natural language processing
- 📦 **Easy Integration** - Simple API, easy to integrate into AI workflows
- 🚀 **Multi-device Support** - Parallel operations on multiple Android devices
- ⏱️ **Smart Wait** - Automatic element waiting, no manual sleep needed

## 🚀 Quick Start

### Installation

#### Method 1: Install via PyPI (Recommended)

```bash
# Install from PyPI
pip install agent-android

# Verify installation
agent-android --version
```

#### Method 2: Install from Source

```bash
# Clone repository
git clone https://github.com/Fast2x/agent-android.git
cd agent-android

# Install dependencies
pip install -r requirements.txt

# Ensure ADB is available
adb devices
```

### Requirements

- Python 3.7+
- ADB (Android Debug Bridge)
- Android device or emulator

### Verify Installation

```bash
# Check package info
pip show agent-android

# Test Python API (IMPORTANT: test outside project directory)
cd /tmp
python3 -c "from core.android import create_android_device; print('✅ Installation successful!')"
```

**Note**: The package installs the `core` Python module. Use `from core.android import ...` not `import agent_android`.

### Basic Usage

**Linux / macOS**:
```bash
# Connect to device
./agent-android connect

# Start app
./agent-android start_app com.example.app

# Get UI snapshot (with element refs)
./agent-android snapshot -i

# Operate on elements using refs
./agent-android tap @e1

# Take screenshot
./agent-android screenshot screen.png

# Disconnect
./agent-android disconnect
```

**Windows**:
```cmd
REM Use batch wrapper
agent-android.bat connect
agent-android.bat start_app com.example.app
agent-android.bat snapshot -i
agent-android.bat tap @e1

REM Or use Python directly
python agent-android connect
```

### More Operations

```bash
# Swipe screen
./agent-android swipe 100,200 300,400

# Input text
./agent-android input "Hello World"

# Press home key
./agent-android press home

# Start/stop app
./agent-android start_app com.example.app
./agent-android stop_app com.example.app

# Get element text
./agent-android get text @e1

# Export UI dump
./agent-android dump ui_dump.xml
```

## 📖 Core Features

### 1. Snapshot + Ref Mode (Core)

```bash
# Get UI snapshot, auto-generate element refs
./agent-android snapshot -i

# Output:
# - TextView "Learning" [id=com.app:id/tabTV] [ref=e1]
# - Button "Settings" [id=com.app:id/settings] [clickable] [ref=e2]
# - ImageView "Search" [id=com.app:id/search] [ref=e3]

# Use ref to tap
./agent-android tap @e2
./agent-android get text @e1
```

**Advantages**:
- ✅ Deterministic - refs point to elements precisely
- ✅ Fast - no need to reparse UI
- ✅ AI friendly - snapshot provides complete context

### 2. Natural Language Control

```python
from core.android import create_android_device
from core.nlp_icon_helper import NLPIconHelper

device = create_android_device()
nlp = NLPIconHelper(device)

# Use natural language to control
nlp.tap_by_nlp("Click settings button")
nlp.tap_by_nlp("Click menu icon in top right")
nlp.tap_by_nlp("Click learning tab at bottom")

device.close()
```

**Supported Keywords**:
- Position: top-left, top-right, bottom, center, left, right
- Type: icon, button, text, input

### 3. Python API

```python
from core.android import create_android_device

device = create_android_device()

# App management
device.start_app("com.example.app")
device.stop_app("com.example.app")

# Touch operations
device.tap(500, 1000)
device.swipe(500, 1000, 500, 500)

# Input operations
device.input_text("Hello World")
device.press_home()
device.press_back()

# Element finding
element = device.find_element({
    "strategy": "text_contains",
    "value": "Settings"
})
device.tap(element['center']['x'], element['center']['y'])

# Screenshot
device.screenshot("screen.png")

device.close()
```

### 4. Multi-Device Management

```bash
# Connect all devices
./agent-android multi-connect

# List connected devices
./agent-android multi-list

# Parallel screenshot all devices
./agent-android multi-screenshot

# Parallel tap on all devices
./agent-android multi-tap 500 1000

# Parallel start app on all devices
./agent-android multi-start-app com.example.app

# Disconnect all devices
./agent-android multi-disconnect
```

### 5. Smart Wait

```bash
# Wait for element to appear
./agent-android wait-for id com.app:id/button

# Wait for text (10 second timeout)
./agent-android wait-for-text "Welcome" --timeout 10000

# Wait for app to start
./agent-android wait-for-app com.example.app
```

## 📚 Command Reference

### Device Management

```bash
agent-android devices                     # List devices
agent-android connect [--serial <id>]     # Connect to device
agent-android disconnect                  # Disconnect
```

### Touch Operations

```bash
agent-android tap <selector>              # Tap element ref or coordinates
agent-android swipe <start> <end>         # Swipe screen
```

### Input Operations

```bash
agent-android input <text>                # Input text
agent-android press <key>                 # Press key (home/back/enter)
```

### Screenshot & Snapshot

```bash
agent-android screenshot [path]           # Take screenshot
agent-android snapshot [-i]               # UI snapshot (interactive only)
```

### App Management

```bash
agent-android start_app <package>         # Start app
agent-android stop_app <package>          # Stop app
```

### Smart Wait

```bash
agent-android wait-for <strategy> <value> # Wait for element
agent-android wait-for-text <text>       # Wait for text
agent-android wait-for-app <package>      # Wait for app start
```

### Multi-Device

```bash
agent-android multi-connect [--max <n>]   # Connect all devices
agent-android multi-list                  # List connected devices
agent-android multi-screenshot [path]     # Screenshot all devices
agent-android multi-tap <x> <y>           # Tap all devices
agent-android multi-start-app <package>   # Start app on all devices
agent-android multi-disconnect            # Disconnect all devices
```

### Global Options

```bash
--session <name>                         # Session name
--json                                   # JSON output
--debug                                  # Debug mode
```

## 🎯 Use Cases

### 1. AI Agents Control Android Devices

```python
# AI can use natural language directly
nlp.tap_by_nlp("Click settings button")
nlp.tap_by_nlp("Click back button")
```

### 2. UI Automation Testing

```python
# Automated testing workflow
device.start_app("com.example.app")
time.sleep(2)

element = device.find_element({"strategy": "text", "value": "Login"})
device.tap_element(element)
device.input_text("test@example.com")
device.press_enter()

# Verify results
assert device.wait_for_text("Welcome", timeout=5000)
```

### 3. Data Collection

```python
# Collect app data
device.start_app("com.example.app")

while True:
    # Take screenshot
    device.screenshot(f"data/screenshot_{int(time.time())}.png")

    # Get UI data
    ui_dump = device.get_ui_dump()

    # Check if done
    if device.find_element({"strategy": "text", "value": "Complete"}):
        break
```

### 4. Task Automation

```python
# Automate repetitive tasks
device.start_app("com.example.app")

# Login
device.tap(500, 1000)
device.input_text("username")
device.tap(500, 1200)
device.input_text("password")
device.tap(500, 1400)

# Navigate through app
device.swipe(500, 2000, 500, 500)
```

### 5. Multi-Device Testing

```python
from core.multi_device import create_multi_device_manager

manager = create_multi_device_manager()
manager.connect_all()

# Test app on all devices
manager.parallel_start_app("com.example.app")
manager.parallel_screenshot("test_{device_id}.png")
manager.parallel_tap(500, 1000)

manager.disconnect_all()
```

## 🔧 Requirements

- Python 3.7+
- ADB (Android Debug Bridge)
- Android device or emulator

## 📄 License

Apache License 2.0 - see [LICENSE](LICENSE) file

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📞 Support

For issues and questions:
- GitHub Issues: [Create Issue](https://github.com/Fast2x/agent-android/issues)

## 🎉 Summary

**agent-android** is a complete, production-ready Android automation tool designed for AI Agents.

### Core Highlights

1. ✅ **Snapshot + Ref Mode** - Matches agent-browser design
2. ✅ **Natural Language Control** - Industry-first innovation
3. ✅ **Multi-Device Support** - Parallel execution, 10x efficiency
4. ✅ **Smart Wait** - Automatic element waiting
5. ✅ **Production Ready** - All features tested
6. ✅ **Open Source** - Apache 2.0 license
7. ✅ **Cross-Platform** - Windows | Linux | macOS
8. ✅ **PyPI Published** - Easy installation via pip

### Installation

**Via PyPI (Recommended):**
```bash
pip install agent-android
```

**From Source:**
```bash
git clone https://github.com/Fast2x/agent-android.git
cd agent-android
./agent-android connect
```

**PyPI Package:** https://pypi.org/project/agent-android/

**Made with ❤️ for AI Agents**