# agent-browser: cho AI điều khiển trình duyệt bằng lệnh — hướng dẫn cài đặt và dùng

> agent-browser là công cụ dòng lệnh viết bằng Rust, cho AI agent (hoặc chính bạn) điều khiển trình duyệt Chrome qua từng lệnh ngắn: mở trang, đọc, bấm, điền form, chụp ảnh. Cài bằng npm và cần Node từ phiên bản 22 trở lên. Cài không khó, chỉ hai lệnh là chạy được.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-21 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/agent-browser-cho-ai-agent-dieu-khien-trinh-duyet

agent-browser là một công cụ dòng lệnh (CLI) giúp AI agent điều khiển trình duyệt như người dùng thật: mở trang web, đọc nội dung, bấm nút, điền form rồi kiểm tra kết quả. Tác giả mô tả nó là "browser automation CLI for AI agents". Nó viết bằng Rust, chạy nhanh, và mỗi thao tác chỉ là một lệnh shell ngắn.

Điểm khác biệt nằm ở cách nó đưa trang web cho AI. Thay vì ném cả đống HTML hoặc ảnh chụp, lệnh `snapshot` trả về trang dưới dạng văn bản gọn, mỗi phần tử có một mã tham chiếu như `@e1`. AI chỉ cần nói "bấm @e1" là xong. Cách này tiết kiệm token và ít nhầm hơn so với việc đoán toạ độ trên màn hình.

Bạn nên đọc bài này nếu đang dùng Claude Code hay một agent khác và muốn nó tự thao tác trên web. Bạn cũng đọc được nếu chỉ muốn một công cụ để tự động hoá vài việc lặp lại trên trình duyệt bằng dòng lệnh. Repo hiện có khoảng 50.289 sao và 3.502 fork, giấy phép Apache-2.0. Xem video ngắn bên dưới để thấy nó chạy thế nào, rồi quay lại làm theo từng bước.

```repo
- repo | vercel-labs/agent-browser
- kind | CLI
- desc | agent-browser là công cụ dòng lệnh giúp AI agent mở web, đọc trang dưới dạng văn bản gọn, rồi bấm, điền, chụp màn hình từng bước một.
- stars | 50k
- lang | Rust
- license | Apache-2.0
```

```video
- youtube | https://youtube.com/shorts/C3BFO_1VlrY
- facebook | https://www.facebook.com/reel/1439860060949861
- title | Video giới thiệu agent-browser
```

## agent-browser làm được gì

### Đọc trang thành văn bản có mã tham chiếu

Lệnh `snapshot` biến trang web thành cây phần tử dạng chữ. Mỗi nút, link, ô nhập có một ref như `@e1`. Thêm cờ `-i` thì chỉ hiện các phần tử tương tác được. Với AI, đây là bản đồ gọn để quyết định bấm vào đâu.

### Điều khiển từng lệnh một, trình duyệt giữ nguyên giữa các lệnh

Lệnh đầu tiên sẽ bật một tiến trình nền (daemon) điều khiển Chrome qua Chrome DevTools Protocol. Các lệnh sau dùng lại đúng trình duyệt đó. Vì vậy mỗi bước chỉ là một lần gọi ngắn, trang đang mở vẫn còn nguyên. Mặc định, trình duyệt chạy ngầm (headless) sẽ tự đóng nếu một giờ không có lệnh nào.

### Một bộ lệnh khá đầy đủ

Theo README, các nhóm lệnh gồm:

- Điều hướng và đọc: `open`, `back`, `forward`, `reload`, `read`, `snapshot`, `get`, `is`.
- Tương tác: `click`, `fill`, `type`, `press`, `hover`, `select`, `check`, `scroll`, `drag`, `upload`, `find`.
- Chờ: `wait`.
- Ghi lại: `screenshot`, `pdf`, `record`, `download`, `diff`.
- Trạng thái trang và mạng: `cookies`, `storage`, `network`, `eval`.
- Gỡ lỗi: `console`, `errors`, `trace`, `profiler`, `vitals`.
- Phiên và đăng nhập: `session`, `state`, `auth`, `profiles`.

Bạn không cần nhớ hết. Gõ `agent-browser --help` để xem danh sách, hoặc `agent-browser <lệnh> --help` để xem một lệnh.

### Báo lỗi thật thay vì báo thành công giả

Nếu nút bị ẩn, bị vô hiệu, nằm ngoài màn hình hoặc bị một thứ khác che (ví dụ banner đồng ý cookie), lệnh `click` sẽ thất bại và báo cho bạn. Nó không giả vờ là đã bấm. Nhờ đó AI biết cần tắt banner rồi thử lại, thay vì tưởng đã xong.

### Nhiều cách chọn phần tử và nhiều loại trình duyệt

Ngoài ref, bạn có thể chọn bằng CSS selector, văn bản, XPath hoặc kiểu ngữ nghĩa, ví dụ `agent-browser find role button click --name "Submit"`. Mặc định nó dùng Chrome for Testing. Bạn cũng có thể gắn vào Chrome đang chạy (`--cdp`, `--auto-connect`), chọn engine khác bằng `--engine` (Lightpanda, Obscura), điều khiển Mobile Safari trong iOS Simulator, hoặc dùng trình duyệt đám mây như Browserbase, Browserless, Browser Use, Kernel, AgentCore.

### Có sẵn "kỹ năng" cho AI và máy chủ MCP

CLI đi kèm các skill khớp đúng phiên bản đang cài. Lệnh `agent-browser mcp` còn bật một máy chủ MCP qua stdio cho các ứng dụng hỗ trợ MCP.

## Cần chuẩn bị gì

Theo tư liệu, bạn cần:

- **Node.js từ phiên bản 22 trở lên.** `package.json` của repo ghi yêu cầu này. Nếu bạn muốn tự build từ mã nguồn thì cần Node 24 trở lên, pnpm 11 trở lên và Rust.
- **Hệ điều hành:** có bản chạy sẵn cho macOS (ARM64, x64), Linux (ARM64, x64, glibc và musl) và Windows (x64). Gói npm tự chọn đúng bản cho máy bạn.
- **Kết nối mạng** ở lần đầu, vì cần tải Chrome for Testing.
- **Linux:** có thể cần thêm thư viện hệ thống cho trình duyệt. README có lệnh riêng cho việc này.

README không nhắc đến yêu cầu GPU, tài khoản hay API key cho chính CLI. Nếu bạn dùng trình duyệt đám mây (Browserbase…), mỗi nhà cung cấp có yêu cầu riêng. Phần này README chỉ trỏ sang trang tài liệu, mình không có thông tin chi tiết.

## Cài đặt từng bước

```steps
- Kiểm tra Node | Chạy node -v, cần phiên bản 22 trở lên
- Cài gói | Dùng npm cài agent-browser toàn cục
- Tải trình duyệt | Chạy agent-browser install để tải Chrome for Testing
- Chạy thử | Mở example.com và đọc snapshot
- Nối với AI agent | Cài skill hoặc thêm vài dòng vào AGENTS.md
```

### Kiểm tra Node

Mở terminal. Trên Windows bạn dùng PowerShell hoặc Windows Terminal. Trên macOS và Linux dùng Terminal. Gõ lệnh dưới đây để xem phiên bản Node.

```bash
node -v
```

Nếu kết quả bắt đầu bằng `v22` trở lên là đạt. Thấp hơn thì bạn cần cập nhật Node trước, vì `package.json` yêu cầu từ 22.

### Cài gói bằng npm

Lệnh này cài agent-browser ở dạng toàn cục, nghĩa là gõ `agent-browser` ở thư mục nào cũng chạy được.

```bash
npm install -g agent-browser
```

README còn ghi hai cách khác. Trên macOS bạn có thể dùng Homebrew: `brew install agent-browser`. Nếu chỉ muốn thử mà không cài, dùng `npx agent-browser open example.com`.

### Tải trình duyệt

Gói npm chỉ là công cụ điều khiển. Bạn cần tải thêm trình duyệt Chrome for Testing, làm một lần là đủ.

```bash
agent-browser install
```

Nếu bạn dùng Linux và thiếu thư viện hệ thống, README hướng dẫn dùng bản có kèm phần phụ thuộc:

```bash
agent-browser install --with-deps
```

Người mới hay quên bước này rồi báo "không tìm thấy trình duyệt". Đã cài bằng Homebrew thì vẫn phải chạy `agent-browser install`.

### Chạy thử

Chạy lần lượt các lệnh sau, theo đúng phần Quick start của README:

```bash
agent-browser open example.com
agent-browser snapshot -i       # interactive elements, each with a ref
agent-browser click @e1         # act on a ref from that snapshot
agent-browser get url           # check the result
agent-browser close
```

`open` mở trang. `snapshot -i` liệt kê các phần tử bấm được. `click @e1` bấm vào phần tử mang mã e1. `get url` cho bạn xem địa chỉ hiện tại. `close` đóng trình duyệt. Đừng gõ cả dấu `#` và phần chữ sau nó, đó chỉ là chú thích.

### Nối với AI agent

Có hai cách, theo README. Cách một là cài skill khám phá vào agent của bạn:

```bash
npx skills add vercel-labs/agent-browser
```

Skill này chỉ là một "bản nháp ngắn", bảo agent tự chạy `agent-browser skills get core` để nạp hướng dẫn. Nhờ vậy hướng dẫn luôn khớp với phiên bản CLI đã cài.

Cách hai là thêm đoạn này vào file `AGENTS.md` trong dự án của bạn:

```markdown
Use `agent-browser` for browser automation. Before the first use, run
`agent-browser skills get core` and follow it.
```

Bạn cũng có thể xem trước nội dung skill để hiểu AI sẽ được dặn gì:

```bash
agent-browser skills get core
agent-browser skills list
```

## Kiểm tra đã chạy được chưa

Sau khi chạy `agent-browser open example.com` và `agent-browser snapshot -i`, bạn sẽ thấy kết quả như README mô tả cho trang example.com:

```
- link "Learn more" [ref=e1]
```

Nếu thấy dòng link kèm `[ref=e1]` nghĩa là trình duyệt đã mở, trang đã đọc được và ref hoạt động. Chạy tiếp `agent-browser click @e1` rồi `agent-browser get url`. Nếu địa chỉ đã đổi sang trang khác, bạn đã điều khiển thành công.

README còn nhắc hai lệnh để chẩn đoán cài đặt: `doctor` và `upgrade`. Nếu có gì lạ, thử `agent-browser doctor` trước. Chi tiết hai lệnh này nằm ở trang Installation trên trang chủ dự án.

Nhớ chạy `agent-browser close` khi xong việc để giải phóng trình duyệt chạy nền.

## Dùng vào việc thật

Các tình huống dưới đây bám đúng những gì README mô tả. Với lệnh chưa có ví dụ trong README, bạn xem cú pháp bằng `agent-browser <lệnh> --help` để chắc chắn.

### Chủ shop xem nhanh trang sản phẩm của đối thủ

Bạn bán đồ gia dụng online và muốn biết một trang đối thủ đang ghi gì, mà không muốn kéo cả trang dài. Mở trang rồi đọc bằng snapshot:

```bash
agent-browser open example.com
agent-browser snapshot -i
agent-browser get url
agent-browser close
```

Nếu bạn dùng Claude Code, chỉ cần nhắc: "Dùng agent-browser mở trang này, đọc phần giá và mô tả rồi tóm tắt cho mình." Agent sẽ tự chạy `open`, `snapshot`, `read`. Kết quả là bản tóm tắt chữ, không phải một đống HTML. Lệnh `screenshot` có thể chụp lại trang để bạn lưu đối chiếu.

> Mỗi bước chỉ là một lệnh ngắn: AI đọc trang, bấm một ref, rồi đọc lại để kiểm tra.
>
> — Ông T

### Nhân viên văn phòng điền form lặp đi lặp lại

Bạn phải nhập cùng một kiểu thông tin vào một cổng web nội bộ mỗi ngày. Cách làm: nhờ agent mở trang, lấy snapshot, rồi dùng `fill` để điền từng ô và `click` để gửi. Prompt mẫu:

```text
Dùng agent-browser mở trang form này. Chụp snapshot, điền các ô theo bảng dữ liệu mình đưa,
không bấm Gửi. Dừng lại cho mình xem lại trước.
```

Dặn rõ "đừng bấm Gửi" ở bước đầu là thói quen tốt. Bạn được xem kết quả trước, rồi mới cho agent tiếp tục. Nếu phần tử bị che bởi một banner, lệnh `click` sẽ báo lỗi và agent sẽ tìm cách tắt banner rồi thử lại.

```note
Nếu cho agent làm việc trên trang cần đăng nhập, hãy đọc trang Security của dự án. README nhắc tới auth vault, danh sách tên miền được phép, chính sách hành động và ranh giới nội dung. Chỉ cho agent vào các trang bạn tin tưởng và đừng dán mật khẩu thẳng vào câu lệnh.
```

### Lập trình viên gỡ lỗi trang web của mình

Bạn vừa sửa một trang và nghi có lỗi JavaScript. Mở trang bằng agent-browser, rồi nhờ agent xem lỗi bằng các lệnh nhóm gỡ lỗi như `console` và `errors`. Khi cần, `network` cho biết các yêu cầu mạng, còn `vitals` và `profiler` giúp đo hiệu năng. Prompt mẫu:

```text
Mở trang http://localhost:3000 bằng agent-browser, xem console và errors,
rồi cho mình biết lỗi nào đang xuất hiện và nên kiểm tra file nào trước.
```

Kết quả là danh sách lỗi cùng gợi ý hướng xử lý. Bạn đỡ phải mở DevTools bằng tay và chép lại từng dòng.

### Người dùng Claude Code muốn agent tự thao tác web

Bạn đã dùng Claude Code và muốn nó có "đôi tay" trên trình duyệt. Chạy `npx skills add vercel-labs/agent-browser` hoặc thêm hai dòng vào `AGENTS.md` như phần trên. Sau đó giao việc bằng lời thường:

```text
Dùng agent-browser vào trang này, tìm nút Đăng ký, bấm thử và cho mình biết trang nào hiện ra sau đó.
```

Nếu ứng dụng của bạn hỗ trợ MCP, có thể dùng `agent-browser mcp` để chạy máy chủ MCP. Hướng dẫn cấu hình cụ thể nằm ở trang Commands trên trang chủ dự án.

## Lỗi hay gặp và cách xử lý

### Báo thiếu trình duyệt hoặc không khởi động được Chrome

Thường là bạn chưa chạy `agent-browser install`. Chạy lệnh đó một lần. Trên Linux, thử `agent-browser install --with-deps` để cài luôn thư viện hệ thống. Vẫn lỗi thì chạy `agent-browser doctor` để chẩn đoán.

### Lệnh `agent-browser` không được nhận ra

Ngay sau khi cài toàn cục, terminal cũ đôi khi chưa cập nhật đường dẫn. Hãy đóng terminal, mở lại rồi thử lần nữa. Cũng nên kiểm tra `node -v` để chắc chắn bạn đang ở Node 22 trở lên. Nếu muốn thử ngay không cần cài, dùng `npx agent-browser open example.com`.

### Dùng ref cũ nên bấm trượt hoặc bấm nhầm

README nói rõ: ref chỉ đúng tại thời điểm chụp snapshot. Sau khi chuyển trang hoặc trang đổi nội dung, hãy chạy lại `agent-browser snapshot -i` rồi mới dùng ref mới. Đây là lỗi người mới hay mắc nhất.

### Click báo thất bại

Đây là hành vi có chủ đích: nút bị ẩn, bị vô hiệu, nằm ngoài vùng nhìn thấy hoặc bị che bởi banner cookie. Cách xử lý theo README: tắt phần tử che, chụp snapshot mới rồi thử lại.

### Trình duyệt tự đóng sau một thời gian

Tiến trình nền sẽ tự thoát sau một giờ không có lệnh, với trình duyệt headless. Nếu bạn cần giữ đăng nhập qua các lần chạy, hãy xem trang Sessions để cấu hình lưu phiên (session persistence). Hiện mình không có thêm chi tiết về cách cấu hình này ngoài những gì README ghi.

## Có nên dùng không

**Điểm mạnh.** Cài nhanh, chỉ hai lệnh. Mỗi thao tác là một lệnh ngắn nên dễ đọc lại, dễ gỡ lỗi. Cách đọc trang bằng snapshot gọn giúp AI làm việc chính xác hơn. Nó báo lỗi thật khi không bấm được. Công cụ có bản cho Windows, macOS, Linux và hỗ trợ nhiều loại trình duyệt, kể cả trình duyệt đám mây. Giấy phép Apache-2.0 và repo vẫn được cập nhật gần đây.

**Giới hạn.** Đây là công cụ dòng lệnh, không có giao diện kéo thả. Bạn cần quen mở terminal và hiểu một chút về Node. Với trang cần đăng nhập, bạn phải tự cân nhắc kỹ về an toàn, vì AI có thể thao tác thay bạn. Tư liệu cũng không đưa ra số liệu về độ ổn định trên mọi trang web phức tạp, nên mình không dám hứa nó chạy tốt với mọi trang.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần lấy dữ liệu từ một trang đơn giản, một công cụ tải trang thông thường có thể đủ. Nếu bạn cần kịch bản kiểm thử tự động lâu dài cho dự án lớn, các framework kiểm thử chuyên dụng có thể hợp hơn. Còn nếu bạn muốn AI tự lái trình duyệt, từng bước, có kiểm tra giữa chừng, thì agent-browser rất đáng thử. Hãy bắt đầu với example.com, thấy kết quả rồi mới giao việc thật.

## Câu hỏi thường gặp

### agent-browser có miễn phí không?

Repo dùng giấy phép Apache-2.0, nên bạn dùng và cài đặt được mà không phải trả phí cho công cụ. Nếu bạn dùng trình duyệt đám mây như Browserbase hay Browserless thì chi phí do nhà cung cấp đó quy định, tư liệu không nêu giá.

### Cần cài những gì trước khi dùng?

Bạn cần Node.js từ phiên bản 22 trở lên theo package.json của repo. Sau khi cài gói bằng npm, chạy thêm agent-browser install để tải Chrome for Testing. Tư liệu không nhắc tới yêu cầu GPU hay tài khoản cho chính CLI.

### Chạy được trên Windows không?

Được. README ghi có bản chạy sẵn cho Windows x64, ngoài macOS (ARM64, x64) và Linux (ARM64, x64, glibc và musl). Gói npm tự chọn bản đúng với máy bạn.

### Có dùng được với Claude Code hoặc các AI agent khác không?

Có. Bạn chạy npx skills add vercel-labs/agent-browser hoặc thêm đoạn hướng dẫn vào AGENTS.md. Ngoài ra lệnh agent-browser mcp bật máy chủ MCP qua stdio cho các ứng dụng hỗ trợ MCP.

### Dữ liệu và tài khoản đăng nhập của tôi có an toàn không?

README nhắc tới các tính năng bảo mật như auth vault, danh sách tên miền được phép, chính sách hành động và ranh giới nội dung, được mô tả ở trang Security. Tư liệu không nói rõ mọi trường hợp, nên bạn chỉ nên cho agent vào các trang tin cậy và tự kiểm soát những gì nó được phép làm.

### Tôi có phải dùng Chrome riêng không, hay dùng được Chrome đang mở?

Mặc định công cụ dùng Chrome for Testing do chính nó tải về. README cũng nói bạn có thể gắn vào Chrome đang chạy bằng cờ --cdp hoặc --auto-connect, chi tiết nằm ở trang CDP mode.

### Ref như @e1 có dùng lại được sau khi trang thay đổi không?

Không nên. Ref chỉ mô tả trang tại lúc chụp snapshot. Sau khi chuyển trang hoặc nội dung đổi, bạn cần chạy lại snapshot để lấy ref mới.
