beeos-device-agent 0.2.2

BeeOS DeviceAgent — AI-powered device control agent with ACP, MQTT, and WebRTC

BeeOS DeviceAgent

AI-powered device control agent supporting ACP, MQTT, and WebRTC channels.

Installation

pip install beeos-device-agent

For AI automation (MobileAgent v3.5):

pip install beeos-device-agent[ai]

Local Development Setup

# Install bridge-client first (local dependency)
cd sdks/bridge-client-python && python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"

# Install device-agent
cd sdks/device-agent && python3 -m venv .venv
.venv/bin/pip install -e ../bridge-client-python
.venv/bin/pip install -e ".[dev]"

# Run tests
.venv/bin/pytest tests/ -v

Usage

CLI (Android via ADB)

python -m device_agent \
    --bridge ws://localhost:18443 \
    --key ~/.beeos/test-device.key \
    --adb <serial> \
    --mqtt-host localhost --mqtt-port 1883 --no-mqtt-tls \
    --http --http-port 9090

CLI (Desktop mode, no ADB needed)

python -m device_agent \
    --bridge ws://localhost:18443 \
    --key ~/.beeos/test-device.key \
    --mode desktop \
    --mqtt-host localhost --mqtt-port 1883 --no-mqtt-tls \
    --http --http-port 9090

CLI Options

Flag	Default	Description
--bridge	(required)	Bridge WebSocket URL
--key	auto-generated	Ed25519 key file path
--mode	android	Runtime mode: android or desktop
--adb	auto-detect	ADB device serial (android mode)
--mqtt-host	(empty)	MQTT broker host (enables MQTT channel)
--mqtt-port	8883	MQTT broker port
--no-mqtt-tls	false	Disable MQTT TLS (for local dev)
--http	false	Enable REST API
--http-port	8080	REST API port
--vlm-model	gpt-4o	VLM model for AI automation

Python API

from device_agent import DeviceAgent, DeviceAgentConfig
from device_agent.runtime.android_adb import AndroidADBRuntime

runtime = AndroidADBRuntime(serial="R5CT1234")
config = DeviceAgentConfig(
    bridge_url="ws://localhost:18443",
    key_file="~/.beeos/test-device.key",
    mqtt_host="localhost",
    mqtt_port=1883,
    mqtt_use_tls=False,
)
agent = DeviceAgent(config, runtime)
await agent.start()

REST API (when --http is enabled)

Endpoint	Method	Description
/device/info	GET	Device metadata
/device/screenshot	GET	PNG screenshot
/device/action	POST	Touch/key/shell actions
/tasks	POST	Submit AI task
/tasks/{id}	GET	Get task status

Docker

The Dockerfile uses the repository root as the build context (because it needs sdks/bridge-client-python at build time).

docker build -f sdks/device-agent/Dockerfile -t beeos-device-agent .

docker run --rm \
  -e BRIDGE_URL=wss://bridge.beeos.ai \
  beeos-device-agent \
  python -m device_agent \
    --bridge wss://bridge.beeos.ai \
    --adb <device-serial> \
    --mqtt-host mqtt.beeos.ai

Architecture

Three independent channels:

• ACP (via Bridge) — AI chat + device management (JSON-RPC 2.0 over WebSocket)
• MQTT (via EMQX) — WebRTC signaling + device telemetry
• WebRTC (P2P/TURN) — on-demand video streaming + DataChannel control

Each DeviceAgent instance represents one device (1 device = 1 process = 1 BeeOS Instance). The agent manages all three channels independently and coordinates them for features like on-demand streaming (auto-start when viewed, auto-cooldown when idle).