agent-device: kiểm thử app bằng AI — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về callstack/agent-device — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: agent-device: tự động kiểm thử ứng dụng bằng AI — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
agent-device là CLI, MCP server và API Node.js có kiểu dữ liệu để AI agent kiểm tra, điều khiển và ghi lại bằng chứng từ app trên thiết bị hoặc trình giả lập. Công cụ hỗ trợ iOS, Android, HarmonyOS, TV, web, macOS và Linux; cài CLI khá đơn giản nhưng từng nền tảng cần bộ công cụ thiết bị tương ứng.
agent-device là lớp điều khiển thiết bị mã nguồn mở cho AI coding agent. Công cụ giúp agent đọc trạng thái app, bấm nút, điền biểu mẫu, kiểm tra lỗi và lưu bằng chứng trên mobile, web, TV và desktop. Bạn có thể dùng qua CLI, MCP server hoặc API Node.js có kiểu dữ liệu.
Repo này hợp với lập trình viên xây app React Native, Expo, Flutter hoặc app native; đội QA muốn tự động hóa kiểm thử; và người dùng AI coding agent cần xác minh thay đổi trực tiếp trên simulator, emulator, thiết bị thật hoặc thiết bị cloud. Điểm đáng giá nhất là agent không chỉ nhìn ảnh chụp màn hình. Nó đọc accessibility snapshot, dùng ref và selector để thao tác, sau đó lưu screenshot, video, log hoặc trace để người khác xem lại.
Repo hiện có khoảng 5370 sao và 400 fork. Mã nguồn chính dùng TypeScript, giấy phép MIT. Công cụ vẫn còn được cập nhật và có thể chạy cục bộ hoặc kết nối tới thiết bị từ xa.
callstack/agent-device
Lớp điều khiển thiết bị cho AI coding agent, hỗ trợ kiểm tra app mobile, web, TV và desktop qua CLI, MCP hoặc Node.js.
I.agent-device làm được gì
Đọc trạng thái giao diện bằng accessibility snapshot: Agent nhận được cây giao diện với vai trò, nhãn và ref của phần tử. Cách này thường tiết kiệm token hơn việc chỉ phân tích screenshot, đồng thời giúp agent biết chính xác phần tử nào cần tương tác.
Điều khiển app bằng ref và selector: Agent có thể bấm hoặc nhấn phần tử, điền trường nhập liệu, cuộn, thực hiện gesture, chờ giao diện ổn định, kiểm tra trạng thái và xử lý alert. Đây là các thao tác gần với cách người dùng thật sử dụng app.
Làm việc với nhiều loại nền tảng: README nêu hỗ trợ iOS, Android, HarmonyOS, tvOS, Android TV, Fire TV, Amazon Vega OS TV, web, macOS và Linux. Mức hỗ trợ khác nhau tùy backend, nên cần kiểm tra capabilities trước khi chọn một nền tảng cụ thể.
Kiểm tra app trong lúc phát triển: Bạn có thể yêu cầu agent mở app trên iOS Simulator hoặc Android Emulator, thực hiện một luồng và đính kèm screenshot. Điều này giúp phát hiện lỗi giao diện hoặc lỗi luồng ngay sau khi sửa code.
Chẩn đoán lỗi sâu hơn: Công cụ có thể hỗ trợ screenshot, video, log, trace, dữ liệu mạng, mẫu hiệu năng, thông tin crash và React profile. Nhờ đó, một lần chạy có thể cung cấp bằng chứng hữu ích cho việc tìm nguyên nhân thay vì chỉ báo “test thất bại”.
Lưu và chạy lại workflow: Sau khi khám phá một luồng thành công, bạn có thể lưu các bước thành script
.adđể chạy cục bộ hoặc trong CI. Khi cần, workflow cũng có thể xuất thành strict Maestro YAML.Kết nối với AI agent qua MCP: Lệnh
agent-device mcpkhởi động MCP server chính thức qua stdio. Agent có thể dùng các lệnh dưới dạng structured tools nhưng vẫn đi qua cùng runtime với CLI.Tích hợp vào chương trình Node.js:
createAgentDeviceClient()cung cấp API Node.js có kiểu dữ liệu. Bạn có thể dùng API này trong agent tự xây hoặc trong hệ thống orchestration, thay vì tự xử lý lệnh terminal.Quản lý phiên và quyền dùng thiết bị: Mỗi phiên giữ trạng thái thiết bị. Session được gắn với git worktree, còn cơ chế claim trên máy chủ giúp các agent chạy song song không chiếm cùng simulator hoặc emulator.
Chạy trong CI/CD hoặc cloud: Workflow có thể phát lại trong CI và lưu screenshot, log thành artifact. README cũng nêu khả năng kết nối BrowserStack, AWS Device Farm, TestMu AI và Limrun thông qua remote proxy hoặc device cloud.
II.Cần chuẩn bị gì
Bạn cần Node.js từ phiên bản 22.12 trở lên. Nếu muốn tự động hóa web, README yêu cầu Node.js từ phiên bản 24 trở lên.
Bạn cần một môi trường phù hợp với mục tiêu kiểm thử. Tùy nền tảng, đó có thể là iOS Simulator, Android Emulator, thiết bị iOS hoặc Android thật, macOS, Linux, trình duyệt web, Android TV, Fire TV hoặc môi trường HarmonyOS, Vega OS. README không đưa ra một danh sách cài đặt riêng cho từng SDK trong phần Quick start, nên các yêu cầu cụ thể của target cần xem trong tài liệu Installation và capabilities của dự án.
Bạn không được README yêu cầu API key cho việc chạy CLI cơ bản. Nếu dùng thiết bị cloud hoặc dịch vụ remote, thông tin xác thực và yêu cầu riêng của nhà cung cấp sẽ phụ thuộc vào dịch vụ đó; tư liệu được cung cấp chưa ghi chi tiết các biến môi trường hay key tương ứng.
Với MCP, bạn cần một AI client có thể chạy CLI hoặc kết nối MCP. README nêu các client như Claude Code, Codex, Cursor, Windsurf, Cline và Goose, cùng các agent khác có khả năng chạy CLI hoặc kết nối MCP.
Với API Node.js, bạn cần một dự án Node.js và có thể cài package agent-device. README cung cấp tên package và ví dụ import, nhưng phần tư liệu được gửi không có lệnh cài package cục bộ riêng cho API này.
III.Cài đặt từng bước
- Chuẩn bị Node.jsCài Node.js đúng phiên bản và mở terminal
- Cài CLICài agent-device trên toàn máy bằng npm
- Kiểm tra môi trườngChạy doctor để phát hiện thiếu cấu hình
- Xem quy trìnhMở hướng dẫn workflow trước khi giao việc cho agent
- Chọn cách tích hợpDùng CLI, MCP hoặc API Node.js tùy hệ thống
A.Chuẩn bị terminal và Node.js
Mở Terminal, PowerShell hoặc cửa sổ dòng lệnh tại nơi bạn muốn làm việc. Kiểm tra phiên bản Node.js bằng lệnh phổ thông sau:
node --versionBạn cần Node.js 22.12 trở lên cho CLI. Nếu có kế hoạch dùng web automation, hãy dùng Node.js 24 trở lên. Trên Windows, bạn có thể chạy các lệnh trong PowerShell; trên macOS hoặc Linux, dùng Terminal.
README không ghi lệnh cài Node.js. Vì vậy, nếu máy chưa có Node.js hoặc đang dùng phiên bản thấp hơn, hãy cài đúng phiên bản theo tài liệu môi trường của bạn trước khi tiếp tục.
B.Cài CLI agent-device
README cung cấp lệnh cài CLI toàn máy:
npm install -g agent-device@latestLệnh này cài package agent-device phiên bản mới nhất và tạo lệnh agent-device để gọi từ terminal. Nếu terminal báo không tìm thấy npm, Node.js chưa được cài đúng hoặc chưa được thêm vào PATH. Nếu cài xong nhưng không gọi được agent-device, hãy đóng rồi mở lại terminal và kiểm tra lại PATH.
C.Kiểm tra cấu hình bằng doctor
Chạy lệnh kiểm tra ngay sau khi cài:
agent-device doctorREADME khuyến nghị tự chạy doctor trước khi giao CLI cho agent. Hãy đọc các mục cảnh báo mà lệnh trả về. Những lỗi liên quan simulator, emulator, thiết bị thật hoặc backend nền tảng cần được xử lý theo target bạn định dùng.
D.Xem hướng dẫn workflow
Mở phần trợ giúp về workflow:
agent-device help workflowLệnh này liên kết tới các hướng dẫn về debugging, replay và profiling. Đây là điểm bắt đầu phù hợp nếu bạn chưa biết nên dùng lệnh nào cho việc kiểm thử, lưu lại một workflow hay tìm lỗi hiệu năng.
E.Cấu hình MCP nếu dùng AI client
MCP server chính thức được khởi động bằng lệnh agent-device mcp. Trong cấu hình MCP của client, README đưa ra JSON sau:
{
"mcpServers": {
"agent-device": {
"command": "agent-device",
"args": ["mcp"]
}
}
}Bạn cần đặt cấu hình này vào nơi mà AI client của bạn đọc MCP server. Không tự đổi command hoặc args nếu chưa có lý do, vì agent-device mcp là lệnh mà README dùng để khởi động stdio MCP server. Sau khi client nhận cấu hình, hãy kiểm tra danh sách tool hoặc thử một yêu cầu mở và đọc app.
F.Chuẩn bị API Node.js nếu tự xây agent
README cung cấp ví dụ dùng typed Node.js API:
import { createAgentDeviceClient } from 'agent-device';
const client = createAgentDeviceClient({ session: 'qa-run' });
try {
await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });
const snapshot = await client.capture.snapshot({ interactiveOnly: true });
const button = snapshot.nodes.find((node) => node.role === 'button');
if (button) await client.interactions.press({ ref: button.ref });
} finally {
await client.sessions.close();
}Ví dụ tạo session tên qa-run, mở app Settings của Apple trên iOS, lấy snapshot chỉ gồm phần tử tương tác, tìm node có role là button, bấm vào đó nếu tìm thấy rồi đóng session trong finally. Đây là mẫu cho chương trình Node.js tự xây; README được cung cấp chưa ghi lệnh tạo project hoặc cài dependency cục bộ, nên không nên tự đoán thêm lệnh.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra cơ bản là chạy thành công cả hai lệnh:
agent-device doctor
agent-device help workflowBạn cần thấy agent-device được nhận diện và phần trợ giúp workflow hiển thị. doctor là kiểm tra quan trọng hơn vì nó cho biết môi trường hiện tại có sẵn các thành phần cần thiết hay chưa.
Để kiểm tra một target cụ thể, README hướng dẫn dùng capabilities:
agent-device capabilities --platform <platform>Thay <platform> bằng target bạn định dùng. Kết quả cho biết target đó hỗ trợ những command nào. Nếu muốn kiểm tra luồng tương tác, hãy mở một app, lấy snapshot và xác nhận output có các node giao diện cùng ref. Snapshot thành công sẽ có dạng như @e2 [button] "Add", dù ref thực tế có thể khác.
V.Dùng vào việc thật
A.Chủ shop kiểm tra luồng thêm sản phẩm trên app bán hàng
Chủ shop có thể nhờ agent kiểm tra màn hình tạo sản phẩm trên app mobile sau khi đội phát triển sửa giao diện. Prompt mẫu là: “Mở app bán hàng trên iOS Simulator, kiểm tra luồng thêm sản phẩm, điền tên và chụp ảnh màn hình biểu mẫu để gửi cho tôi.”
Với CLI, workflow mẫu trong README mở app Contacts trên iOS, lấy snapshot, bấm ref, điền dữ liệu rồi chụp bằng chứng:
agent-device open Contacts --platform ios
agent-device snapshot -i
agent-device press @e2 --settle
agent-device fill @e7 "Ada" --settle
agent-device screenshot ./contact-form.png
agent-device closeTrong thực tế, ref @e2 và @e7 chỉ là ref minh họa từ output mẫu. Bạn phải dùng ref mới nhất mà snapshot hoặc diff trả về. Kết quả là một ảnh chụp như contact-form.png để người khác xem lại biểu mẫu sau khi điền.
B.Nhân viên văn phòng xác minh quy trình trên app nội bộ
Một nhân viên QA hoặc nhân viên văn phòng có thể dùng agent để kiểm tra luồng đăng nhập, tìm kiếm hoặc gửi biểu mẫu trên app nội bộ. Prompt mẫu: “Mở app, kiểm tra luồng gửi biểu mẫu, nếu có lỗi thì chụp màn hình, lưu log và mô tả bước gây lỗi.”
Agent sẽ đọc accessibility snapshot, chọn phần tử theo ref hoặc selector, điền trường, chờ giao diện ổn định và thu thập bằng chứng. Cách này phù hợp khi người kiểm thử cần một kết quả có thể gửi cho đội phát triển, thay vì chỉ nói rằng một nút không hoạt động.
C.Lập trình viên kiểm tra thay đổi React Native hoặc Expo
Sau khi sửa màn hình onboarding, lập trình viên có thể giao cho agent: “Implement the onboarding screen, run it on the iOS simulator and Android emulator, and attach screenshots.”
Agent có thể kiểm tra cùng một thay đổi trên hai target, đọc trạng thái giao diện và đính kèm screenshot. Nếu accessibility tree có nhãn, role và test ID rõ ràng, agent sẽ tương tác đáng tin cậy hơn. Đây cũng là cách phát hiện sớm việc một thay đổi chỉ chạy đúng trên iOS nhưng lỗi trên Android.
D.Đội QA lưu workflow để chạy trong CI
Đội QA có thể khám phá một lần luồng checkout, lưu các bước thành script .ad, sau đó phát lại trong CI cho mỗi pull request. Prompt mẫu: “Explore the checkout flow once, save it as a replay script, and run it in CI.”
Kết quả mong đợi là workflow có thể lặp lại, cùng screenshot và log được lưu thành artifact. Nếu hệ thống cần định dạng khác, README nêu khả năng xuất workflow thành strict Maestro YAML. Với nhiều agent hoặc nhiều worktree chạy đồng thời, có thể xem quyền sở hữu thiết bị bằng:
agent-device device statusNếu có claim cũ mà owner chắc chắn không còn chạy, README cung cấp lệnh giải phóng:
agent-device device release --staleChỉ dùng lệnh này khi bạn chắc chắn claim đã stale, vì thiết bị có thể đang được một tiến trình khác sử dụng.
Giá trị lớn nhất của agent-device là biến một lần agent thao tác trên app thành bằng chứng có thể xem lại và chạy lại.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Node.js thấp hơn yêu cầu
Nếu npm không cài được hoặc CLI hoạt động không đúng, hãy kiểm tra Node.js. CLI yêu cầu Node.js 22.12 trở lên; web automation yêu cầu Node.js 24 trở lên. Nâng Node.js rồi mở terminal mới trước khi chạy lại lệnh cài và agent-device doctor.
B.Agent dùng ref cũ
Ref chỉ hợp lệ trong output mới nhất. Sau một lệnh có --settle, hãy dùng ref trong phần diff; nếu diff không có phần tử cần thao tác, lấy snapshot mới. Không nên giữ nguyên @e2 hoặc @e7 từ ví dụ README cho mọi lần chạy.
C.Snapshot không đủ thông tin để tương tác
Snapshot dựa trên accessibility tree. Nếu app thiếu label, role hoặc test ID rõ ràng, agent có thể không chọn đúng phần tử. Hãy bổ sung thông tin accessibility trong app; dùng screenshot hoặc video làm bằng chứng, hoặc khi dữ liệu accessibility chưa đủ.
D.Target không hỗ trợ command cần dùng
Mỗi backend có độ sâu hỗ trợ khác nhau. HarmonyOS và Vega OS có thể chỉ hỗ trợ một phần command. Chạy agent-device capabilities --platform <platform> để xem target hiện tại hỗ trợ gì, rồi điều chỉnh workflow hoặc chọn target khác.
E.Hai agent tranh cùng thiết bị
Session được gắn với git worktree và host-local device claim giúp ngăn agent song song chiếm cùng simulator hoặc emulator. Kiểm tra bằng agent-device device status. Chỉ giải phóng claim stale khi owner thực sự không còn chạy; không nên giải phóng một phiên đang hoạt động.
VII.Có nên dùng không
Nên dùng nếu bạn muốn AI agent trực tiếp kiểm tra app, cần bằng chứng từ thiết bị, hoặc muốn nối cùng một runtime qua CLI, MCP và API Node.js. Đây cũng là lựa chọn đáng cân nhắc cho đội phát triển mobile muốn kết hợp khám phá bằng agent với replay trong CI.
Điểm mạnh là phạm vi nền tảng rộng, có accessibility snapshot, ref, selector, bằng chứng, replay, quản lý session và kết nối cloud. Mã nguồn MIT, package có CLI, MCP server tích hợp sẵn và API Node.js có kiểu dữ liệu.
Giới hạn là yêu cầu môi trường thiết bị không giống nhau giữa các nền tảng. Mức hỗ trợ command cũng không đồng đều, đặc biệt ở một số backend như HarmonyOS và Vega OS. README được cung cấp chưa ghi chi tiết toàn bộ cách cài SDK, simulator, emulator hoặc credential cho từng device cloud, nên người mới vẫn cần đọc tài liệu Installation và capabilities.
Nếu mục tiêu chính là bộ test hồi quy cố định, có cấu trúc và ít thay đổi, README khuyến nghị dùng e2e — một framework TypeScript cho web và mobile. agent-device phù hợp hơn khi agent cần đọc trạng thái app và tự chọn hành động trong lúc chạy; nó cũng có thể lưu run thành .ad hoặc xuất Maestro YAML khi cần quy trình lặp lại.
Câu hỏi thường gặp
agent-device có miễn phí không?
Repo là mã nguồn mở và dùng giấy phép MIT. README không nêu chi phí cho mọi thành phần; nếu dùng thiết bị cloud hoặc dịch vụ remote, chi phí và điều kiện phụ thuộc nhà cung cấp.
Có cần GPU để chạy agent-device không?
Tư liệu được cung cấp không nói agent-device yêu cầu GPU. README tập trung vào Node.js, simulator, emulator, thiết bị thật và các backend thiết bị.
Có chạy được trên Windows không?
README nêu macOS và Linux là các target desktop, đồng thời hướng dẫn cài CLI bằng npm. Tư liệu được cung cấp chưa ghi rõ ma trận hỗ trợ Windows, nên cần kiểm tra tài liệu Installation trước khi triển khai trên Windows.
Có cần API key không?
README không yêu cầu API key cho CLI cơ bản. Khi kết nối device cloud hoặc remote service, thông tin xác thực có thể phụ thuộc nhà cung cấp; phần tư liệu này chưa ghi chi tiết.
Dữ liệu và screenshot có an toàn không?
Công cụ có thể lưu screenshot, video, log, trace và dữ liệu mạng làm bằng chứng. README không đưa ra chính sách chi tiết về lưu trữ hoặc mã hóa, nên không nên đưa dữ liệu nhạy cảm vào môi trường kiểm thử nếu chưa kiểm tra cấu hình.
agent-device khác Appium, Detox hoặc Maestro thế nào?
README mô tả agent-device để agent đọc trạng thái app và tự chọn từng command trong lúc chạy. Với test suite ổn định, lặp lại, README khuyến nghị e2e; agent-device cũng có thể lưu run thành `.ad` hoặc xuất strict Maestro YAML.
Có dùng được với React Native, Expo và Flutter không?
Có. README nói agent-device hỗ trợ app native iOS và Android, cùng React Native, Expo và Flutter trên các target được hỗ trợ. Command và bằng chứng cụ thể thay đổi tùy target.


