droidrun-agent
# Droidrun Agent
Provides two async clients (`PortalHTTPClient` and `PortalWSClient`), a configuration helper (`PortalConfig`), and a built-in MCP server for communicating with Android devices running DroidRun Portal. All client methods are `async` and support `async with` context managers.
## Installation
```bash
cd droidrun-agent && uv sync # core only
cd droidrun-agent && uv sync --extra mcp # with MCP server support
```
## PortalHTTPClient
Communicates with Portal's HTTP server (default port 8080) using Bearer token authentication.
```python
from droidrun_agent import PortalHTTPClient
async with PortalHTTPClient(base_url="http://192.168.1.100:8080", token="YOUR_TOKEN") as client:
await client.ping()
state = await client.get_state_full()
await client.tap(200, 400)
png = await client.take_screenshot()
```
### Query Methods (GET)
| Signature | Return Type | Description |
|-----------|-------------|-------------|
| `ping()` | `dict` | Health check, no auth required |
| `get_a11y_tree()` | `dict` | Simplified accessibility tree |
| `get_a11y_tree_full(*, filter: bool = True)` | `dict` | Full accessibility tree, `filter=False` keeps small elements |
| `get_state()` | `dict` | Simplified UI state |
| `get_state_full(*, filter: bool = True)` | `dict` | Full UI state (a11y_tree + phone_state), `filter=False` keeps small elements |
| `get_phone_state()` | `dict` | Phone state info (current app, activity, keyboard status, etc.) |
| `get_version()` | `str` | Portal app version string |
| `get_packages()` | `list[dict]` | List of launchable apps, each containing `packageName`, `label`, etc. |
| `take_screenshot(*, hide_overlay: bool = True)` | `bytes` | Device screenshot as PNG bytes, `hide_overlay=False` to show overlay |
### Action Methods (POST)
| Signature | Return Type | Description |
|-----------|-------------|-------------|
| `tap(x: int, y: int)` | `dict` | Tap screen coordinates |
| `swipe(start_x: int, start_y: int, end_x: int, end_y: int, duration: int \| None = None)` | `dict` | Swipe gesture, `duration` is optional duration in milliseconds |
| `global_action(action: int)` | `dict` | Execute Android accessibility global action (1=Back, 2=Home, 3=Recents) |
| `start_app(package: str, activity: str \| None = None, stop_before_launch: bool = False)` | `dict` | Launch an app |
| `stop_app(package: str)` | `dict` | Best-effort stop an app |
| `input_text(text: str, clear: bool = True)` | `dict` | Input text (auto base64-encoded), `clear=True` clears field first |
| `clear_input()` | `dict` | Clear the focused input field |
| `press_key(key_code: int)` | `dict` | Send Android key code (e.g. 66=Enter, 3=Home, 4=Back) |
| `set_overlay_offset(offset: int)` | `dict` | Set overlay vertical offset in pixels |
| `set_socket_port(port: int)` | `dict` | Update the HTTP server port |
## PortalWSClient
Communicates with Portal's WebSocket server (default port 8081) using JSON-RPC style messages. Automatically reconnects when a method is called on a broken connection.
```python
from droidrun_agent import PortalWSClient
async with PortalWSClient("ws://192.168.1.100:8081", token="YOUR_TOKEN") as ws:
await ws.tap(200, 400)
state = await ws.get_state()
png = await ws.take_screenshot()
time_ms = await ws.get_time()
```
### Methods
Supports all action methods from PortalHTTPClient (`tap`, `swipe`, `global_action`, `start_app`, `stop_app`, `input_text`, `clear_input`, `press_key`, `set_overlay_offset`, `set_socket_port`, `take_screenshot`) with identical signatures.
Query methods:
| Signature | Return Type | Description |
|-----------|-------------|-------------|
| `get_packages()` | `Any` | List of launchable packages |
| `get_state(*, filter: bool = True)` | `Any` | Full state, `filter=False` keeps small elements |
| `get_version()` | `Any` | Portal version string |
| `get_time()` | `Any` | Device Unix timestamp in milliseconds |
| `install(urls: list[str], hide_overlay: bool = True)` | `Any` | Install APK(s) from URL(s), supports split APKs (WebSocket only) |
WebSocket screenshots automatically parse binary frames and return PNG `bytes` directly.
## Exceptions
All exceptions inherit from `PortalError`:
| Exception | Trigger |
|-----------|---------|
| `PortalError` | Base exception |
| `PortalConnectionError` | Cannot connect to Portal server |
| `PortalAuthError` | Invalid or missing token (HTTP 401/403) |
| `PortalTimeoutError` | Request timed out |
| `PortalResponseError` | Server returned unexpected status or error |
## Full Usage Example
```python
import asyncio
from droidrun_agent import PortalHTTPClient, PortalWSClient
async def demo_http():
async with PortalHTTPClient("http://localhost:8080", token="YOUR_TOKEN") as client:
print(await client.ping())
print("Version:", await client.get_version())
print("Packages:", len(await client.get_packages()))
await client.tap(500, 800)
await client.swipe(500, 1500, 500, 500, duration=300)
await client.input_text("Hello World")
await client.press_key(66) # Enter
state = await client.get_state_full()
png = await client.take_screenshot()
print(f"Screenshot: {len(png)} bytes")
async def demo_ws():
async with PortalWSClient("ws://localhost:8081", token="YOUR_TOKEN") as ws:
print("Version:", await ws.get_version())
print("Time:", await ws.get_time())
await ws.tap(500, 800)
await ws.start_app("com.android.settings")
png = await ws.take_screenshot()
print(f"Screenshot: {len(png)} bytes")
asyncio.run(demo_http())
asyncio.run(demo_ws())
```
## PortalConfig
Helper dataclass for managing connection settings. Supports direct construction or loading from environment variables.
```python
from droidrun_agent import PortalConfig
# Direct construction
config = PortalConfig(base_url="http://192.168.1.100:8080", token="YOUR_TOKEN")
client = config.create_client()
# Load from environment variables
config = PortalConfig.from_env()
client = config.create_client()
```
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `base_url` | `str` | (required) | Portal HTTP or WebSocket base URL |
| `token` | `str` | (required) | Bearer authentication token |
| `timeout` | `float` | `10.0` | Request timeout in seconds |
| `transport` | `str` | `"http"` | `"http"` or `"ws"` |
Environment variables for `from_env()`: `PORTAL_BASE_URL`, `PORTAL_TOKEN`, `PORTAL_TIMEOUT`, `PORTAL_TRANSPORT`.
## MCP Server
A built-in MCP (Model Context Protocol) server exposes all Portal operations as tools for AI agent integration. Requires the `mcp` optional dependency (`pip install droidrun-agent[mcp]`).
### Starting the server
```bash
# Via CLI entry point
droidrun-agent --mcp
# Or as a Python module
python -m droidrun_agent --mcp
```
The server reads `PORTAL_BASE_URL`, `PORTAL_TOKEN`, `PORTAL_TIMEOUT`, and `PORTAL_TRANSPORT` from environment variables and communicates over stdio.
### MCP Tools
| Tool | Description |
|------|-------------|
| `portal_ping` | Health check (HTTP only) |
| `portal_tap` | Tap screen coordinates |
| `portal_swipe` | Swipe gesture |
| `portal_screenshot` | Take screenshot, returns PNG image |
| `portal_get_state` | Get simplified UI state |
| `portal_get_state_full` | Get full UI state (a11y tree + phone state) |
| `portal_get_a11y_tree` | Get simplified accessibility tree (HTTP only) |
| `portal_get_a11y_tree_full` | Get full accessibility tree (HTTP only) |
| `portal_get_phone_state` | Get phone state info (HTTP only) |
| `portal_get_version` | Get Portal app version |
| `portal_get_packages` | List launchable packages |
| `portal_global_action` | Execute accessibility global action (1=Back, 2=Home, 3=Recents) |
| `portal_start_app` | Launch an app by package name |
| `portal_stop_app` | Stop an app |
| `portal_input_text` | Input text into focused field |
| `portal_clear_input` | Clear focused input field |
| `portal_press_key` | Send Android key code (66=Enter, 3=Home, 4=Back) |
| `portal_set_overlay_offset` | Set overlay vertical offset |
| `portal_get_time` | Get device timestamp (WebSocket only) |
| `portal_install` | Install APK(s) from URL(s) (WebSocket only) |
### openclaw integration
Register as an openclaw MCP skill:
```json
{
"mcpServers": {
"droidrun-agent": {
"command": "uvx",
"args": ["--with", "mcp", "droidrun-agent", "--mcp"],
"env": {
"PORTAL_BASE_URL": "http://192.168.1.100:8080",
"PORTAL_TOKEN": "YOUR_TOKEN"
}
}
}
}
```
标签
skill
ai
