AI & AUTOMATION

Mobile Harness: Biến AI coding agent thành “Operator” cho Android, iOS và cloud phones

24/08/20267 views0

Tóm tắt nhanh:

Mobile Harness là một “harness” Markdown nhẹ, dùng Python mobilerun-core để cho AI coding agent (Claude Code, Cursor, Codex…) điều khiển Android, iOS và cloud phones qua một API thống nhất — không phải tự xây runtime agent mới.

Việc cài đặt rất đơn giản: tạo virtualenv Python 3.11–3.13, pip install "mobilerun-core[local]", cấu hình biến môi trường/API key (nếu dùng cloud), rồi cho agent đọc install.md là có thể kết nối, xem UI, chụp screenshot, mở app, scroll, tap, gõ text trên thiết bị thật hoặc cloud.

Mobile Harness là một bộ “portable operating instructions” kèm theo Python API mobilerun-core, cho phép bạn đưa cho AI coding agent hiện có (Claude Code, Cursor, Codex, OpenClaw…) khả năng điều khiển điện thoại Android, iPhone và cloud phones thông qua một control surface thống nhất. Khác với nhiều framework agent khác, Mobile Harness bản thân không phải là một agent runtime; nó chỉ là harness nhỏ gọn bằng Markdown + Python, để agent mà bạn đang dùng có thể đọc, cài đặt và dùng API điều khiển thiết bị mà không phải thêm một hệ thống phức tạp mới.

Mobile Harness tập trung vào việc chuẩn hoá control path: agent chỉ cần dùng mobilerun_core.Mobilerun để kết nối tới thiết bị local qua ADB/Portal, hoặc cloud phone qua API key, rồi thao tác UI, app lifecycle, screenshot… trong cùng một mô hình lập trình.

Tại sao Mobile Harness quan trọng trong kỷ nguyên AI agent?

Với việc LLM trở thành “coding co-pilot” và “autonomous agent”, điểm yếu lớn là chúng thiếu “tay chân” để tương tác trực tiếp với thiết bị di động thật, đặc biệt là Android/iOS và các cloud device farm. Mobile Harness lấp khoảng trống này bằng cách cung cấp một bộ hướng dẫn + API để coding agent có thể đọc, hiểu và triển khai tự động: clone repo, tạo virtualenv, cài mobilerun-core[local], rồi kết nối device và thực hiện workflow trên UI như một QA engineer hoặc automation tester.

Điều này rất hữu ích cho các use case như kiểm thử end-to-end app di động, tự động hoá thao tác POS trên thiết bị Android, hoặc cho phép agent xử lý các quy trình MFA/OTP trên màn hình điện thoại mà không cần một hệ thống RPA riêng biệt.

Kiến trúc và thành phần chính

Ở mức cao, Mobile Harness gồm ba phần chính: repo Markdown hướng dẫn (AGENTS.md, SKILL.md, các GUIDE.md), Python package mobilerun-core và các backend local/cloud cho Android/iOS. Base mobilerun-core hỗ trợ cloud thông qua mobilerun-sdk, trong khi extra local (mobilerun-core[local]) bổ sung mobilerun-core-local để nói chuyện với ADB, Android Portal HTTP và iOS Portal HTTP trên máy local.

API chính được dùng qua:

from mobilerun_core import Mobilerun

m = Mobilerun()
device = m.connect("loud-device-id>", backend="cloud")
device = m.connect("R5CT123456", backend="local-android-adb")
device = m.connect(backend="local-ios-http", url="http://127.0.0.1:6643")
device = m.connect(
    backend="local-android-http",
    url="http://127.0.0.1:18080",
    token="...",
)

device.ui()
device.screenshot()
device.start_app("com.android.settings")

Đối tượng device sẽ expose các helper như find_nodes, tap_node, tap_text, scroll, scroll_until, type, list_apps, và execute_script (cho cloud Chrome tab).

Yêu cầu môi trường và chuẩn bị trước

Để chạy Mobile Harness, bạn cần Python 3.11, 3.12 hoặc 3.13, với khả năng tạo virtualenv và cài package qua pip. Nếu dùng local Android, thiết bị phải bật ADB hoặc có Portal HTTP (Mobilerun Portal) chạy với base URL như http://127.0.0.1:18080 và bearer token để harness có thể kết nối.

Với local iOS, bạn cần iOS Portal HTTP (ios-portal) đang chạy, ví dụ http://127.0.0.1:6643, sao cho các endpoint như GET /device/date, GET /state và GET /vision/screenshot hoạt động bình thường. Trong chế độ cloud, bạn cần API key từ cloud.mobilerun.ai và cấu hình biến môi trường MOBILERUN_CLOUD_API_KEY cùng MOBILERUN_API_BASE_URL="https://api.mobilerun.ai/v1" để mobilerun-core có thể kết nối tới cloud phones.

Hướng dẫn cài đặt Mobile Harness

Bạn có hai cách cài đặt: cách “one-prompt” cho agent, và cách thủ công dành cho developer thích kiểm soát chi tiết.

1. Cài đặt bằng prompt cho coding agent

Ý tưởng là: bạn paste một prompt chuẩn vào coding agent (Claude Code, Cursor, Codex…) để nó tự động clone repo, đọc install.md và thực hiện các bước cài đặt.
Prompt gợi ý:

Set up https://github.com/droidrun/mobile-harness for me.
Read `install.md` and follow the steps to install `mobile-harness`.

Agent sẽ thực hiện git clone, tạo virtualenv với đúng phiên bản Python, cài mobilerun-core[local] và chuẩn bị environment để kết nối thiết bị.

2. Cài đặt thủ công qua Python virtualenv

Nếu bạn muốn tự cài và sau đó hướng dẫn agent sử dụng environment có sẵn, quy trình cơ bản như sau:

# Clone repo (tuỳ vị trí bạn muốn)
git clone https://github.com/droidrun/mobile-harness
cd mobile-harness

# Tạo virtualenv với Python 3.11–3.13
python -m venv .venv

# Cài đặt mobilerun-core với local extra
.venv/bin/python -m pip install "mobilerun-core[local]"

# Kiểm tra cài đặt thành công
.venv/bin/python -c "from mobilerun_core import Mobilerun"

Sau đó, bạn nói với agent (hoặc IDE, MCP config…) rằng runtime Python cho Mobile Harness nằm ở đường dẫn .venv/bin/python trong folder repo này.

Ví dụ:

Use /path/to/mobile-harness/.venv/bin/python for mobile-harness.

Kết nối thiết bị Android và iOS

Mobile Harness hỗ trợ nhiều mode kết nối Android tuỳ theo việc bạn có ADB và Portal HTTP hay không.

Bảng tóm tắt cho Android:

Có ADB + Có Portal HTTP → backend="local-android-adb": dùng ADB, tự động tận dụng tính năng Portal khi có.
Chỉ có ADB → backend="local-android-adb": dùng điều khiển gốc ADB cho UI, text input, screenshot và app lifecycle.
Chỉ có Portal HTTP → backend="local-android-http" với base URL và bearer token; yêu cầu người dùng tự cung cấp vì không có ADB để bật Portal hoặc lấy token.
Không ADB, không Portal → blocked, agent cần yêu cầu người dùng bật ADB hoặc cung cấp Portal HTTP.

Với iOS, local mode chính là backend="local-ios-http" nói chuyện với ios-portal trên URL mặc định như http://127.0.0.1:6643, chứ không phải server mobilerun-ios --local <udid> (port 8080) vì giao thức khác nhau.

Trong cloud mode, bạn chỉ cần device = m.connect("loud-device-id>", backend="cloud") cùng API key, là có thể thực thi các thao tác giống như local nhưng trên real cloud phones.

Ví dụ sử dụng với Python và AI agent

Sau khi cài mobilerun-core[local] và kết nối được thiết bị, bạn có thể viết các script Python để tự động hoá những tác vụ cụ thể hoặc để agent đọc, sửa và chạy.

Ví dụ: mở Settings trên Android local với ADB:

from mobilerun_core import Mobilerun

m = Mobilerun()
device = m.connect(backend="local-android-adb")

# Chụp screenshot màn hình home
device.screenshot()

# Mở app Settings
device.start_app("com.android.settings")

# Tìm node chứa text "Network & Internet" và tap
nodes = device.find_nodes(any_contains="Network & Internet")
if nodes:
    device.tap_node(nodes[0])

Với cloud Chrome tab, bạn có thể chạy JavaScript trong tab foreground để lấy thông tin UI hoặc dữ liệu page, qua device.execute_script("<js>"); API này chỉ khả dụng ở backend cloud và phải được gate bằng device.supports("execute_script") trước khi gọi.

Bạn cũng có thể tận dụng device.tap_text, device.scroll_until, device.type("...") để coding agent tự “điều hướng” UI theo mô tả tự nhiên, ví dụ “vào màn hình thanh toán và nhập mã OTP gửi qua SMS”.

Một số lưu ý về bảo mật và best practices

Vì Mobile Harness có thể điều khiển thiết bị thật (local hoặc cloud), bạn cần đặt các boundary rõ ràng về những hành động agent được phép thực hiện, đặc biệt khi liên quan tới cài app, thay đổi permission, hoặc truy cập dữ liệu riêng tư. Thiết kế ban đầu của hệ sinh thái Mobilerun nhấn mạnh việc dùng các guide như core/credentials/GUIDE.md để đảm bảo agent xử lý credential, OTP, và các màn hình nhạy cảm theo pattern an toàn thay vì hardcode hoặc để agent tự đoán.

Ngoài ra, sử dụng folder memory/ và credentials/ như storage cục bộ cho session agent cũng cần tuân theo các rule/template được mô tả trong repo; bản thân repo không track data thật, chỉ track rule, nên bạn có thể tự áp chính sách lưu trữ và xoá dữ liệu tương ứng với yêu cầu compliance của hệ thống.

Ứng dụng thực tế cho dev và doanh nghiệp

Đối với developer, Mobile Harness là cách nhanh nhất để kết nối các AI coding agent phổ biến với thiết bị Android/iOS thật cho mục tiêu test, debug UI, và triển khai các workflow automation phức tạp mà không phải tự xây driver ADB/Portal hoặc layer điều khiển iOS. Với doanh nghiệp, đặc biệt là các hệ thống POS, mini-supermarket, hoặc app bán hàng chạy trên điện thoại Android, Mobile Harness mở ra khả năng cho agent tự động kiểm thử UI, chạy regression test trên cloud device farm, hoặc hỗ trợ vận hành từ xa (ví dụ, khởi động app bán hàng, kiểm tra trạng thái mạng, mở màn hình báo cáo doanh thu…) một cách có kiểm soát.

Nếu bạn muốn bắt đầu ngay: