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à lớp điều khiển thiết bị mã nguồn mở cho AI coding agent. Repo giúp agent đọc giao diện, thao tác, gỡ lỗi, lưu bằng chứng và chạy lại quy trình trên ứng dụng mobile, web, TV và desktop. Cài CLI khá đơn giản nếu máy đã có Node.js phù hợp, nhưng từng nền tảng vẫn cần thiết bị hoặc trình mô phỏng tương ứng.
agent-device là lớp điều khiển thiết bị mã nguồn mở cho các AI coding agent. Repo cung cấp CLI, MCP server tích hợp sẵn và typed Node.js API để agent có thể mở ứng dụng, đọc trạng thái giao diện, bấm nút, nhập dữ liệu, chụp ảnh và kiểm tra kết quả trên thiết bị thật hoặc trình mô phỏng.
Công cụ hỗ trợ iOS, Android, HarmonyOS, tvOS, Android TV, Fire TV, Amazon Vega OS TV, web, macOS và Linux. Repo phù hợp với lập trình viên làm ứng dụng mobile, nhóm QA muốn tự động hóa kiểm thử, hoặc người dùng AI coding agent muốn giao cho agent việc chạy ứng dụng và đính kèm bằng chứng.
Điểm đáng giá là agent không chỉ nhìn ảnh chụp màn hình. Nó có thể đọc accessibility snapshot, dùng ref và selector để thao tác có cấu trúc, sau đó lưu screenshot, video, log, trace hoặc kết quả profiling. Repo hiện có khoảng 5.370 sao và 400 fork, dùng giấy phép MIT.
callstack/agent-device
Lớp điều khiển thiết bị cho AI coding agent, giúp kiểm tra ứng dụng mobile, web, TV và desktop qua CLI, MCP hoặc Node.js.
I.agent-device làm được gì
Đọc trạng thái ứng dụng qua accessibility snapshot: Agent có thể nhìn thấy vai trò, nhãn và ref của các thành phần trên màn hình. Cách này thường tiết kiệm token hơn việc chỉ phân tích ảnh chụp, đồng thời giúp agent biết chính xác phần tử nào có thể tương tác.
Điều khiển giao diện đang chạy: Công cụ hỗ trợ mở ứng dụng, nhấn hoặc tap phần tử, điền trường nhập, cuộn, thực hiện gesture, chờ giao diện ổn định và xử lý alert. Bạn có thể giao cho agent một quy trình như mở màn hình đăng nhập, nhập thông tin và kiểm tra kết quả.
Kiểm tra ứng dụng trên nhiều loại thiết bị: Cùng một mô hình session có thể dùng với iOS Simulator, Android Emulator, thiết bị thật, TV, web, macOS hoặc Linux. Việc này hữu ích khi đội phát triển cần xác minh thay đổi trên nhiều môi trường.
Gỡ lỗi và tìm nguyên nhân lỗi: agent-device có thể thu thập screenshot, video, log, trace, dữ liệu mạng, mẫu hiệu năng, thông tin crash và React profile. Nhờ vậy, agent không chỉ báo “màn hình bị lỗi” mà còn có thêm dữ liệu để phân tích.
Kiểm tra hiệu năng React Native: Agent có thể profile các lần render để tìm phần khiến thao tác chậm hoặc gây re-render không cần thiết. Đây là tính năng phù hợp khi bạn đã sửa UI nhưng muốn biết thay đổi có làm ứng dụng nặng hơn không.
Lưu và chạy lại quy trình: Một lần khám phá thành công có thể được lưu thành script
.adđể dùng lại ở máy cá nhân hoặc CI. Repo cũng hỗ trợ xuất strict Maestro YAML khi bạn cần đưa quy trình sang công cụ khác.Kết nối với AI agent qua MCP: Lệnh MCP mở một stdio MCP server chính thức. Agent có thể gọi các thao tác có cấu trúc thay vì tự tạo lệnh CLI, trong khi session, quyền sở hữu thiết bị, bằng chứng và replay vẫn dùng chung một runtime.
Dùng như thư viện Node.js có kiểu dữ liệu:
createAgentDeviceClient()cho phép bạn gọi cùng các lệnh từ mã Node.js. Đây là nền tảng để xây agent QA riêng hoặc tích hợp vào hệ thống điều phối của đội phát triển.Quản lý thiết bị khi chạy song song: Session được gắn với git worktree. Cơ chế claim thiết bị trên máy giúp các agent chạy song song không lấy nhầm simulator hoặc emulator của nhau. Bạn cũng có thể xem trạng thái sở hữu và giải phóng claim cũ.
Chạy cục bộ, trong CI hoặc trên cloud: Bạn có thể bắt đầu với simulator, emulator hoặc thiết bị thật tại máy cá nhân. Khi cần mở rộng, repo có hướng dẫn kết nối remote proxy và các device cloud như BrowserStack, AWS Device Farm, TestMu AI và Limrun.
II.Cần chuẩn bị gì
Theo package.json, máy 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 cài được npm để cài CLI toàn cục. README không liệt kê yêu cầu cụ thể về phiên bản npm, hệ điều hành máy chủ, bộ nhớ hay dung lượng ổ đĩa.
Bạn cũng cần có mục tiêu để điều khiển: iOS Simulator, Android Emulator, thiết bị iOS hoặc Android thật, thiết bị TV, ứng dụng web, macOS hoặc Linux tùy trường hợp. README mô tả các backend mà công cụ sử dụng, nhưng phần yêu cầu cài riêng cho từng target nằm ở tài liệu Installation và không được ghi đầy đủ trong nội dung README đã cung cấp.
Nếu dùng MCP, bạn cần một AI agent hoặc client có thể kết nối stdio MCP. README nêu các client như Claude Code, Codex, Cursor, Windsurf, Cline và Goose. Nếu dùng Node.js API, bạn cần một dự án Node.js có thể import gói agent-device.
README không yêu cầu API key cho cách chạy CLI cơ bản. Khi dùng thiết bị cloud hoặc remote proxy, thông tin xác thực và yêu cầu riêng của nhà cung cấp sẽ phụ thuộc nền tảng đó; tư liệu được cung cấp chưa nêu chi tiết các biến môi trường hay key cụ thể.
III.Cài đặt từng bước
- Cài Node.jsBảo đảm máy dùng Node.js 22.12 trở lên, hoặc Node.js 24 trở lên nếu tự động hóa web
- Cài CLICài agent-device toàn cục bằng npm
- Kiểm tra môi trườngChạy doctor để phát hiện vấn đề thiết lập
- Xem quy trìnhMở hướng dẫn workflow ngay từ CLI
- Kết nối agentThêm cấu hình MCP nếu muốn agent gọi công cụ có cấu trúc
A.Cài Node.js phù hợp
Hãy kiểm tra máy đã có Node.js 22.12 trở lên. Với web automation, hãy dùng Node.js 24 trở lên. README chỉ nêu yêu cầu phiên bản Node.js, không cung cấp lệnh cài Node.js cho Windows, macOS hay Linux.
Nếu bạn đang dùng Windows, hãy mở PowerShell; nếu dùng macOS hoặc Linux, mở Terminal. Sau khi Node.js đã sẵn sàng, bạn có thể kiểm tra phiên bản bằng lệnh phổ thông sau:
node --version
npm --versionNếu phiên bản Node thấp hơn yêu cầu, hãy nâng cấp trước khi cài agent-device. Người mới thường cài CLI thành công nhưng doctor vẫn báo lỗi vì terminal đang dùng một bản Node khác với bản đã cài. Sau khi đổi phiên bản Node, hãy đóng và mở lại terminal.
B.Cài CLI agent-device
README cung cấp lệnh cài toàn cục sau:
npm install -g agent-device@latestTùy chọn -g giúp lệnh agent-device có thể gọi từ nhiều thư mục. @latest yêu cầu npm lấy bản phát hành mới nhất. Bạn cần có quyền cài gói toàn cục; nếu terminal báo lỗi quyền, hãy xử lý quyền của npm theo cách phù hợp với hệ điều hành, không tự thêm các cờ chưa được README đề cập.
C.Kiểm tra thiết lập bằng doctor
Sau khi cài xong, chạy:
agent-device doctorLệnh này dùng để kiểm tra thiết lập trước khi giao CLI cho agent. Đây là bước quan trọng vì mỗi target có thể cần một bridge hoặc backend khác nhau. Nếu có lỗi, hãy đọc phần chỉ dẫn mà doctor in ra và đối chiếu với tài liệu Installation của dự án.
D.Xem workflow có sẵn
README cung cấp lệnh:
agent-device help workflowLệnh này mở thông tin về các workflow liên quan đến debugging, replay và profiling. Nếu bạn mới dùng repo, nên xem phần này sau doctor để biết cách tổ chức một phiên làm việc thay vì tự đoán tên lệnh.
E.Thêm MCP server cho AI agent
agent-device mcp khởi động MCP server chính thức qua stdio. Trong cấu hình MCP của client, thêm JSON sau:
{
"mcpServers": {
"agent-device": {
"command": "agent-device",
"args": ["mcp"]
}
}
}command trỏ tới CLI đã cài. args yêu cầu CLI chạy ở chế độ MCP. Vị trí file cấu hình thay đổi theo từng client, nên README hướng người dùng xem phần AI agent setup cho từng client. Tư liệu được cung cấp không nêu một đường dẫn cấu hình chung cho Windows hay macOS.
F.Gọi từ Node.js
Nếu muốn tích hợp vào agent hoặc chương trình điều phối của mình, import client có kiểu dữ liệu:
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ụ này tạo session tên qa-run, mở ứng dụng Settings trên iOS, lấy snapshot chỉ gồm các node có thể tương tác, tìm button đầu tiên rồi nhấn button đó. Khối finally đóng session kể cả khi thao tác trước đó gặp lỗi. Tên app trong ví dụ là bundle identifier của ứng dụng iOS, nên bạn cần thay bằng app phù hợp với thiết bị của mình.
IV.Kiểm tra đã chạy được chưa
Dấu hiệu đầu tiên là lệnh cài npm hoàn tất và terminal nhận diện được agent-device. Sau đó, agent-device doctor phải chạy được và đưa ra kết quả kiểm tra thiết lập. README không quy định một dòng output cố định, vì kết quả phụ thuộc target và môi trường của bạn.
Tiếp theo, agent-device help workflow phải hiển thị hướng dẫn workflow. Nếu dùng MCP, client cần khởi động được tiến trình tương đương agent-device mcp và nhận cấu hình server từ JSON.
Để kiểm tra end-to-end, README dùng quy trình mở ứng dụng Contacts trên iOS:
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 closeKết quả mong đợi là snapshot có ref của nút Add, thao tác nhấn hiển thị trường First name, thao tác điền tạo diff cho thấy giá trị Ada, sau đó một file screenshot được lưu và session được đóng.
Ref chỉ có hiệu lực trong output mới nhất. Sau mỗi lệnh có --settle, hãy dùng ref trong diff mới. Nếu diff không chứa phần tử cần dùng, hãy lấy snapshot mới thay vì dùng lại ref cũ.
V.Dùng vào việc thật
A.Chủ shop kiểm tra luồng đặt hàng trên ứng dụng mobile
Chủ shop có thể nhờ agent mở ứng dụng bán hàng trên emulator, đi qua luồng chọn sản phẩm, thêm vào giỏ và kiểm tra màn hình thanh toán. Prompt có thể viết: “Mở ứng dụng bán hàng trên Android emulator, kiểm tra luồng thêm một sản phẩm vào giỏ, chụp screenshot màn hình thanh toán và báo nếu nút tiếp tục không xuất hiện”.
Agent sẽ đọc accessibility snapshot để tìm nút và trường phù hợp, thực hiện thao tác, rồi lưu bằng chứng. Nếu ứng dụng có lỗi, nhóm phát triển nhận được screenshot hoặc log thay vì chỉ một mô tả bằng chữ.
B.Nhân viên văn phòng kiểm tra ứng dụng nội bộ
Một nhân viên QA không cần tự viết ngay một bộ test lớn. Họ có thể mở ứng dụng nội bộ, dùng snapshot để tìm trường tìm kiếm, điền mã khách hàng và kiểm tra kết quả hiển thị. Khi quy trình đã chạy đúng, họ lưu các bước thành .ad script để chạy lại sau mỗi thay đổi.
Cách này hữu ích cho các luồng ổn định như tra cứu khách hàng, tạo phiếu hoặc kiểm tra biểu mẫu. Nếu cần chạy trong CI, script có thể được replay và screenshot, log được lưu thành artifact để người review xem lại.
C.Dev React Native tìm màn hình bị re-render chậm
Lập trình viên có thể giao cho agent nhiệm vụ: “Mở màn hình danh sách, thực hiện thao tác lọc, kiểm tra có re-render React Native không cần thiết và đính kèm dữ liệu profiling”. Agent-device hỗ trợ React profile cùng các công cụ chẩn đoán khác để tìm phần khiến tương tác chậm.
Kết quả phù hợp cho việc điều tra hiệu năng sau một pull request. Agent có thể kết hợp việc thao tác trên màn hình với dữ liệu profile, thay vì chỉ đo một hàm riêng lẻ.
D.Nhóm phát triển xác minh pull request trên thiết bị thật
Nhóm có thể yêu cầu agent chạy ứng dụng trên thiết bị thật, kiểm tra một quy trình cụ thể và đính kèm bằng chứng: “Xác minh thay đổi của pull request trên thiết bị iOS, chạy luồng onboarding, chụp ảnh từng trạng thái quan trọng và báo lỗi nếu không thể hoàn tất”.
Với thiết bị cloud, quy trình có thể mở rộng sang các dịch vụ được repo hỗ trợ. Tuy vậy, phần thiết lập tài khoản, chi phí và quyền truy cập của từng dịch vụ không được nêu trong README, nên cần xem tài liệu riêng trước khi triển khai.
Một lần agent nhìn thấy, thao tác được và lưu bằng chứng sẽ biến việc “hình như đã chạy” thành một lần kiểm tra có thể review.
Ông T
E.Dev xây agent QA riêng bằng Node.js
Nếu công ty có hệ thống điều phối riêng, dev có thể dùng createAgentDeviceClient() thay vì gọi CLI thủ công. Client có kiểu dữ liệu và dùng chung runtime với CLI, MCP, session, evidence, replay và cloud routing.
Ví dụ trong README mở Settings trên iOS, lấy các node tương tác rồi nhấn button đầu tiên. Trong sản phẩm thật, bạn nên chọn node theo role, ref hoặc selector phù hợp với ứng dụng, sau đó luôn đóng session trong finally để tránh giữ thiết bị.
Accessibility snapshot phụ thuộc vào nhãn, role và test ID của ứng dụng. Hãy đặt các giá trị này rõ ràng để agent thao tác ổn định. Screenshot và video nên được dùng làm bằng chứng, không nên là nguồn duy nhất khi accessibility tree đã đủ thông tin.
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 báo lỗi khi cài hoặc CLI chạy không ổn định, nguyên nhân có thể là Node.js thấp hơn 22.12. Nếu bạn đang tự động hóa web, Node.js 22 vẫn chưa đủ theo README; hãy dùng Node.js 24 trở lên. Kiểm tra lại phiên bản bằng node --version, mở terminal mới rồi chạy agent-device doctor.
B.Dùng ref cũ sau khi giao diện thay đổi
Ref chỉ hợp lệ trong output mới nhất. Sau press --settle hoặc fill --settle, giao diện có thể tạo ref mới; dùng ref cũ sẽ khiến agent chọn sai hoặc không tìm thấy phần tử. Hãy đọc diff mới và chỉ lấy snapshot mới khi diff không có thông tin cần thiết.
C.Chưa có thiết bị hoặc simulator phù hợp
Cài CLI không đồng nghĩa với việc đã có iOS Simulator, Android Emulator hay thiết bị thật sẵn sàng. Hãy chạy agent-device doctor, kiểm tra target bạn muốn dùng và xem phần Installation tương ứng. README chưa ghi đầy đủ lệnh thiết lập từng nền tảng, vì vậy không nên tự đoán thêm biến môi trường hoặc cờ lệnh.
D.Accessibility snapshot thiếu phần tử cần thao tác
Nếu snapshot không có nhãn hoặc role rõ ràng, agent sẽ khó chọn đúng phần tử. Hãy cải thiện accessibility label, role và test ID trong ứng dụng; dùng screenshot hoặc video để bổ sung bằng chứng khi dữ liệu accessibility không đủ.
E.Target không hỗ trợ toàn bộ lệnh
Mức hỗ trợ thay đổi theo target. HarmonyOS và Vega OS là những ví dụ có thể chỉ hỗ trợ một phần command. Hãy dùng lệnh sau để xem capability của nền tảng cụ thể:
agent-device capabilities --platformREADME không ghi giá trị nền tảng cụ thể cho tùy chọn này trong khối lệnh, nên bạn cần xem hướng dẫn command hoặc trợ giúp của bản CLI đang cài để điền đúng target.
VII.Có nên dùng không
Nên dùng nếu bạn muốn AI coding agent thật sự mở và kiểm tra ứng dụng thay vì chỉ đọc mã nguồn. CLI dễ bắt đầu, MCP giúp kết nối với nhiều agent, còn Node.js API phù hợp khi bạn muốn xây sản phẩm QA hoặc agent riêng. Việc dùng chung session, evidence, replay và cơ chế quản lý thiết bị cũng giúp quy trình từ khám phá đến CI liền mạch hơn.
Repo đặc biệt hợp với đội làm React Native, Expo, Flutter hoặc ứng dụng native cần kiểm tra trên mobile và thiết bị thật. Khả năng lưu screenshot, log, trace, video và script giúp kết quả dễ review hơn. Giấy phép MIT cũng phù hợp cho việc nghiên cứu và tích hợp vào hệ thống nội bộ.
Giới hạn chính là cài đặt thực tế không chỉ có npm. Bạn vẫn phải chuẩn bị simulator, emulator, thiết bị thật hoặc backend cloud phù hợp. Mức hỗ trợ không giống nhau giữa các nền tảng, và README chưa cung cấp toàn bộ yêu cầu cài đặt riêng cho từng target trong nội dung được cung cấp.
Nếu mục tiêu của bạn là một bộ test tĩnh, lặp lại với kịch bản ổn định, README khuyên cân nhắc e2e, một framework TypeScript cho web và mobile. agent-device phù hợp hơn khi agent cần tự quan sát trạng thái, chọn thao tác ở thời gian chạy, điều tra lỗi và tạo bằng chứng. Nó cũng có thể lưu workflow thành .ad hoặc xuất strict Maestro YAML nếu bạn cần chuyển sang cách chạy lặp lại.
Câu hỏi thường gặp
agent-device có miễn phí không?
README cho biết repo là mã nguồn mở và dùng giấy phép MIT. Cách dùng CLI cục bộ được mô tả bằng lệnh npm, nhưng tư liệu không nói rõ chi phí của các dịch vụ thiết bị cloud hoặc các dịch vụ liên quan.
Có cần GPU để chạy agent-device không?
README không nêu yêu cầu GPU. Công cụ là CLI, MCP server và typed Node.js API, nhưng yêu cầu phần cứng cụ thể cho từng simulator, emulator hoặc thiết bị chưa được cung cấp.
agent-device chạy trên Windows được không?
README mô tả khả năng chạy trên nhiều môi trường và có nhắc tới macOS, Linux cùng các thiết bị mobile, TV và web. Tư liệu được cung cấp không 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 quick start bằng CLI. Nếu kết nối device cloud hoặc remote proxy, thông tin xác thực phụ thuộc dịch vụ được chọn và chưa được nêu chi tiết trong tư liệu.
agent-device có dùng được với React Native, Expo và Flutter không?
Có. README nói công cụ hỗ trợ ứng dụng native iOS, Android, React Native, Expo và Flutter trên các target được hỗ trợ. Command và mức bằng chứng có thể thay đổi theo từng nền tảng.
agent-device khác Appium, Detox hoặc Maestro thế nào?
agent-device cho phép agent đọc trạng thái ứng dụng và chọn lệnh tại thời gian chạy, đồng thời lưu workflow thành `.ad` hoặc xuất strict Maestro YAML. Với bộ test ổn định, lặp lại, README gợi ý dùng e2e; agent-device có thể phù hợp hơn cho khám phá, chẩn đoán và tạo bằng chứng.
Có thể chạy agent-device trong CI không?
Có. README mô tả việc lưu một lần chạy thành script `.ad`, replay trong CI và giữ screenshot cùng log làm artifact. Việc chạy CI cụ thể vẫn phụ thuộc target và thiết bị mà bạn kết nối.


