# agent-browser: 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à một công cụ dòng lệnh viết bằng Rust, cho AI agent một trình duyệt để điều khiển từng bước: mở trang, đọc nội dung dạng văn bản gọn, rồi bấm hoặc điền vào từng phần tử. Bạn cài bằng npm, cần Node 22 trở lên, và chạy được trên macOS, Linux và Windows. Cài đặt chỉ cần hai lệnh, nhưng muốn dùng hiệu quả bạn nên có sẵn một AI agent như Claude Code.

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

agent-browser là một công cụ dòng lệnh (CLI) viết bằng Rust, giúp AI agent mở trình duyệt, đọc trang web và thao tác trên đó ngay từ terminal. Thay vì bắt AI "đoán" giao diện qua ảnh chụp màn hình, công cụ này trả về trang web 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 vào `@e1`" là xong.

Ai nên dùng? Những người đang cho AI agent (như Claude Code hoặc các agent khác) làm việc thật và cần nó đi lại trên web: kiểm tra một trang, điền form, lấy số liệu, thử giao diện. Lập trình viên mới cũng dùng được, vì mỗi bước chỉ là một lệnh ngắn trong terminal. Bạn không cần viết kịch bản dài như khi dùng các công cụ kiểm thử trình duyệt truyền thống.

Điểm đáng giá nhất là cách làm việc từng bước. Trình duyệt được giữ mở giữa các lệnh, nên mỗi bước là một lệnh shell ngắn: đọc trang, hành động, đọc lại để kiểm tra kết quả. Repo hiện có khoảng 50.425 sao và 3.511 fork, giấy phép Apache-2.0, và vẫn được cập nhật trong vài tháng gần đây. Bạn có thể xem video ngắn bên dưới để thấy nó chạy trước khi cài.

```repo
- repo | vercel-labs/agent-browser
- kind | CLI
- desc | CLI viết bằng Rust cho AI agent lái trình duyệt từng lệnh một: mở trang, đọc cây truy cập, bấm, điền form, chụp màn hình.
- 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ì

Dưới đây là các tính năng chính theo tư liệu, kèm lợi ích thực tế.

**Đọc trang dưới dạng cây truy cập (snapshot).** Lệnh `snapshot` trả về trang như một đoạn văn bản gọn, mỗi phần tử tương tác có một mã `ref` (ví dụ `@e1`). Văn bản gọn nghĩa là AI đọc nhanh hơn, tốn ít ngữ cảnh hơn so với đọc cả trang HTML dài. Thêm `-i` để chỉ lấy các phần tử tương tác như nút và liên kết.

**Thao tác bằng một lệnh mỗi bước.** Nhóm lệnh tương tác gồm `click`, `dblclick`, `fill`, `type`, `press`, `hover`, `select`, `check`, `uncheck`, `scroll`, `drag`, `upload` và nhiều lệnh khác. Gần như mọi việc một người làm trên trang web đều có lệnh tương ứng.

**Tìm phần tử theo nhiều cách.** Ngoài mã `@e1`, bạn có thể dùng CSS selector, văn bản, XPath hoặc locator theo ngữ nghĩa, ví dụ `agent-browser find role button click --name "Submit"`. Khi trang đổi, cách này giúp bạn không phụ thuộc vào mã ref cũ.

**Báo lỗi thật khi không bấm được.** Lệnh click sẽ thất bại, thay vì báo thành công giả, khi phần tử bị ẩn, bị vô hiệu hoá, nằm ngoài vùng nhìn hoặc bị che bởi phần tử khác như banner đồng ý cookie. Nhờ vậy AI không tưởng nhầm là đã bấm xong.

**Chụp và ghi lại.** Có `screenshot`, `pdf`, `record`, `download` và `diff` để lưu lại hoặc so sánh trang.

**Quản lý đăng nhập và phiên.** Mỗi `--session` có một trình nền (daemon) và trình duyệt riêng. Nhóm lệnh `session`, `state`, `auth`, `profiles` giúp lưu trạng thái. Tư liệu cũng nhắc đến kho đăng nhập (auth vault), danh sách tên miền được phép và chính sách hành động trong phần bảo mật.

**Gỡ lỗi và đo hiệu năng.** Các lệnh như `console`, `errors`, `highlight`, `inspect`, `trace`, `profiler`, `vitals` giúp lập trình viên xem lỗi trang và hiệu năng.

**Nhiều loại trình duyệt.** Mặc định là Chrome for Testing. Bạn có thể gắn vào Chrome đang chạy bằng `--cdp` hoặc `--auto-connect`, chọn engine Lightpanda hoặc Obscura bằng `--engine`, điều khiển Mobile Safari trong iOS Simulator, hoặc dùng nhà cung cấp trình duyệt đám mây như Browserbase, Browserless, Browser Use, Kernel, AgentCore.

**Đi kèm kỹ năng cho AI.** CLI mang theo các skill khớp phiên bản, và có thể chạy như một MCP server qua stdio bằng lệnh `agent-browser mcp`.

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

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

- **Hệ điều hành:** macOS (ARM64, x64), Linux (ARM64, x64, cả glibc và musl) hoặc Windows (x64). Gói npm tự chọn đúng file chạy cho máy bạn.
- **Node.js:** file `package.json` yêu cầu Node 22 trở lên nếu bạn cài qua npm.
- **Trình duyệt:** lệnh `agent-browser install` sẽ tải Chrome for Testing về, chỉ cần làm lần đầu.
- **Trên Linux:** nên dùng `agent-browser install --with-deps` để cài luôn các thư viện hệ thống mà trình duyệt cần.
- **Nếu build từ mã nguồn:** cần Node.js 24 trở lên, pnpm 11 trở lên và Rust. Người mới không cần đi đường này.

Tư liệu không nói công cụ cần tài khoản hay API key riêng. Còn AI agent bạn dùng cùng nó (ví dụ Claude Code) có thể cần tài khoản của chính agent đó, việc này nằm ngoài repo.

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

```steps
- Mở terminal | Dùng Terminal, PowerShell hoặc bất kỳ cửa sổ dòng lệnh nào
- Cài công cụ | Chạy npm install -g agent-browser
- Tải trình duyệt | Chạy agent-browser install để lấy Chrome for Testing
- Chạy thử | Mở example.com, đọc snapshot, bấm thử một phần tử
- Nối với AI agent | Cài skill hoặc thêm hai dòng vào AGENTS.md
```

### Mở terminal và kiểm tra Node

Bạn cần một cửa sổ dòng lệnh. Trên Windows, mở PowerShell. Trên macOS, mở Terminal. Cách chính thức cần Node 22 trở lên, nên hãy kiểm tra trước:

```bash
node --version
```

Nếu số hiện ra nhỏ hơn 22, bạn cần nâng Node lên trước khi cài. Chỗ này người mới hay vấp nhất.

### Cài agent-browser

Đây là lệnh trong README. Cờ `-g` nghĩa là cài toàn cục, để bạn gọi `agent-browser` từ bất kỳ thư mục nào:

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

Nếu bạn dùng Homebrew (macOS), README còn cho cách khác:

```bash
brew install agent-browser
```

Nếu chỉ muốn thử mà không cài, README ghi bạn có thể chạy thẳng bằng `npx`:

```bash
npx agent-browser open example.com
```

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

Sau khi cài, chạy lệnh dưới đây để tải Chrome for Testing. README ghi là chỉ cần làm lần đầu:

```bash
agent-browser install
```

Trên Linux, dùng bản có cờ `--with-deps` để cài thêm thư viện hệ thống:

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

Lệnh này tải file về máy nên có thể mất một lúc tuỳ mạng. Đừng tắt giữa chừng.

### Nối với AI agent của bạn

Có ba cách theo README. Cách thứ nhất là cài skill khám phá từ skills.sh vào agent:

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

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

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

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

Cách thứ ba dành cho các ứng dụng hỗ trợ MCP. Lệnh dưới khởi động một MCP server qua stdio. README chưa hướng dẫn chi tiết cách khai báo ở từng ứng dụng, bạn xem mục MCP server trong trang tài liệu của dự án:

```bash
agent-browser mcp
```

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

Cách nhanh nhất là chạy đúng chuỗi lệnh quick start trong README:

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

Với trang example.com, kết quả của `snapshot -i` theo README là một dòng như sau:

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

Nếu bạn thấy dòng này, nghĩa là cài thành công. Lệnh `click @e1` bấm vào liên kết đó, và `get url` cho bạn biết trình duyệt đã chuyển sang địa chỉ nào. Cuối cùng `close` đóng trình duyệt.

Nếu có gì đó không ổn, README nhắc đến lệnh `doctor` trong nhóm Setup để kiểm tra môi trường. Chi tiết xem ở trang Installation của dự án.

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

Lưu ý chung: agent-browser là công cụ cho AI agent. Phần lớn các tình huống dưới đây là bạn nhờ agent làm, agent sẽ tự gọi các lệnh này. Bạn cũng có thể tự gõ để hiểu nó đang làm gì.

> Cho AI một trình duyệt, nó không còn đoán mò nữa mà tự đọc, tự bấm, tự kiểm tra lại.
>
> — Ông T

### Chủ shop kiểm tra trang đặt hàng của chính mình

Bối cảnh: bạn bán hàng online và vừa sửa trang thanh toán. Bạn muốn biết nút "Đặt hàng" còn bấm được không, hay bị banner cookie che mất.

Cách làm: nhờ agent mở trang và thử bấm. Bạn có thể giao câu lệnh mẫu: "Dùng agent-browser mở trang giỏ hàng của mình, tìm nút Đặt hàng và bấm thử, báo cho mình nếu bị che." Bên dưới, agent sẽ chạy kiểu như sau:

```bash
agent-browser open example.com
agent-browser snapshot -i
agent-browser find role button click --name "Submit"
```

Kết quả: nếu nút bị che hoặc bị ẩn, lệnh click báo thất bại thay vì báo thành công giả. Agent sẽ tìm banner che, đóng nó, chụp snapshot mới rồi thử lại. Bạn nhận được báo cáo cụ thể thay vì phải tự thử trên nhiều thiết bị.

### Nhân viên văn phòng thu thập thông tin từ trang công khai

Bối cảnh: mỗi tuần bạn phải mở một trang công khai để chép vài thông tin vào báo cáo. Việc lặp đi lặp lại và dễ sai.

Cách làm: viết cho agent một prompt rõ ràng, ví dụ: "Dùng agent-browser mở trang này, đọc nội dung bằng snapshot, rồi tóm tắt ba mục mình cần." README có lệnh `read` và `get` trong nhóm điều hướng và đọc, còn `screenshot` và `pdf` trong nhóm lưu lại. Cú pháp chi tiết từng lệnh bạn xem bằng `agent-browser <lệnh> --help`.

Kết quả: agent đọc trang dạng văn bản, trích đúng phần cần, và có thể chụp màn hình hoặc xuất PDF để bạn lưu bằng chứng. Hãy chỉ dùng cho các trang bạn được phép truy cập.

### Lập trình viên mới kiểm tra giao diện và lỗi

Bối cảnh: bạn vừa viết một trang web nhỏ và muốn AI kiểm tra giúp có lỗi console hay không.

Cách làm: thêm đoạn nhắc vào `AGENTS.md` như ở phần cài đặt, rồi nhờ agent: "Mở trang localhost của mình, xem lỗi console và báo lại." README liệt kê các lệnh `console`, `errors`, `highlight`, `inspect` trong nhóm gỡ lỗi.

Kết quả: agent mở trang, đọc lỗi, chỉ ra phần tử có vấn đề và đề xuất sửa. Bạn vẫn là người quyết định có sửa hay không.

### Dùng chung một trình duyệt đã đăng nhập

Bối cảnh: bạn có một trang cần đăng nhập, và bạn không muốn gõ lại mật khẩu mỗi lần.

Cách làm: README cho biết bạn có thể gắn vào Chrome đang chạy bằng `--cdp` hoặc `--auto-connect`, hoặc lưu phiên bằng nhóm lệnh `session`, `state`, `auth`, `profiles`. Cách dùng cụ thể nằm ở trang Sessions và Security trên trang tài liệu, README chưa ghi lệnh chi tiết.

Kết quả: agent làm việc trên phiên đã đăng nhập mà bạn không phải chuyển mật khẩu qua câu lệnh.

```note
Khi cho AI điều khiển trình duyệt đã đăng nhập, nó có thể thấy và làm mọi việc bạn làm được trên tài khoản đó. Hãy giới hạn tên miền được phép, đọc kỹ trang Security của dự án, và đừng dán mật khẩu hoặc key vào prompt.
```

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

**Lệnh `agent-browser` không được nhận ra.** Thường do cài xong nhưng terminal chưa nạp lại đường dẫn. Hãy đóng terminal, mở lại và thử `agent-browser --help`. Nếu vẫn lỗi, kiểm tra Node đã từ 22 trở lên chưa bằng `node --version`.

**Chưa có trình duyệt.** Nếu bạn chạy `open` mà báo thiếu trình duyệt, nhiều khả năng bạn chưa chạy `agent-browser install`. Chạy lệnh đó một lần rồi thử lại. Trên Linux, dùng `agent-browser install --with-deps` để có đủ thư viện hệ thống. README cũng nhắc đến lệnh `doctor` để chẩn đoán.

**Mã `@e1` không còn đúng.** README nói rõ: mã ref chỉ mô tả trang ở thời điểm chụp snapshot. Sau khi chuyển trang hoặc DOM thay đổi, hãy chụp snapshot mới trước khi dùng lại mã ref. Đây là lỗi người mới gặp nhiều nhất.

**Click báo thất bại.** Theo README, click sẽ lỗi khi phần tử bị ẩn, bị vô hiệu hoá, nằm ngoài vùng nhìn hoặc bị che, ví dụ bởi banner đồng ý cookie. Cách xử lý an toàn: đóng phần tử che, chụp snapshot mới rồi thử lại.

**Trình duyệt tự tắt sau một thời gian.** Trình nền sẽ đóng trình duyệt headless và thoát sau một giờ không có lệnh, theo mặc định. Nếu bạn cần giữ trạng thái, hãy cấu hình lưu phiên (session persistence) theo trang Sessions của dự án.

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

**Điểm mạnh.** Cách dùng đơn giản: mỗi bước là một lệnh shell, dễ hiểu cho cả người lẫn AI. Snapshot dạng văn bản gọn nên tiết kiệm ngữ cảnh cho agent. Click báo lỗi thật thay vì thành công giả. Hỗ trợ nhiều nền tảng, nhiều engine và nhà cung cấp trình duyệt đám mây. Có sẵn kỹ năng đi kèm và chế độ MCP. Giấy phép Apache-2.0 và dự án vẫn được cập nhật.

**Giới hạn.** Công cụ dành cho AI agent, nên nếu bạn không dùng agent nào thì lợi ích sẽ ít hơn. Bạn vẫn cần Node 22 trở lên. Mã ref phải làm mới liên tục khi trang thay đổi. Một số tính năng như phiên đăng nhập, CDP, nhà cung cấp đám mây cần đọc thêm tài liệu, README chỉ nêu tên chứ chưa hướng dẫn từng bước. Bảo mật là việc bạn phải tự cân nhắc khi cho AI thao tác trên tài khoản thật.

**Khi nào chọn cách khác.** Nếu chỉ cần lấy dữ liệu từ một trang tĩnh, một lệnh tải trang đơn giản có thể đủ. Nếu bạn cần bộ kiểm thử giao diện chạy tự động lâu dài theo kịch bản cố định, 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ự đi trên web và bạn thích kiểu từng-lệnh-một dễ kiểm soát, agent-browser là một lựa chọn đáng thử.

## 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, bạn có thể tải và dùng. Tư liệu không nói về phí cho phần mềm này. Nếu dùng nhà cung cấp trình duyệt đám mây hoặc AI agent có tính phí, chi phí đó nằm ở phía dịch vụ tương ứng, bạn cần xem riêng.

### Cần GPU hoặc máy cấu hình mạnh không?

Tư liệu không nhắc yêu cầu GPU hay cấu hình phần cứng. Công cụ điều khiển một trình duyệt Chrome for Testing qua dòng lệnh. Bạn nên thử trên máy của mình, và nếu gặp vấn đề thì dùng lệnh doctor để kiểm tra.

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

Có. README ghi file chạy native có cho macOS (ARM64, x64), Linux (ARM64, x64, glibc và musl) và Windows (x64). Gói npm tự chọn bản phù hợp với máy bạn. Bạn cần Node 22 trở lên nếu cài qua npm.

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

Tư liệu nói có các tính năng bảo mật như kho đăng nhập (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, chi tiết nằm ở trang Security của dự án. Tuy nhiên AI agent làm được gì trên phiên đã đăng nhập thì bạn tự chịu trách nhiệm, nên hãy giới hạn quyền và tên miền.

### Khác gì so với việc để AI xem ảnh chụp màn hình?

agent-browser trả về trang dưới dạng văn bản gọn, mỗi phần tử có mã ref như @e1, nên agent bấm đúng phần tử theo mã thay vì đoán vị trí trên ảnh. Tư liệu không so sánh trực tiếp với công cụ khác, nên mình chỉ nói được cách nó làm việc.

### Dùng với Claude Code hoặc agent khác thế nào?

Bạn có thể chạy npx skills add vercel-labs/agent-browser để cài skill khám phá, hoặc thêm hai dòng hướng dẫn vào file AGENTS.md. Với ứng dụng hỗ trợ MCP, lệnh agent-browser mcp khởi động MCP server qua stdio. Cách khai báo ở từng ứng dụng cụ thể thì README chưa có.

### Có cần cài trình duyệt riêng không?

Bạn không cần tự cài, nhưng phải chạy agent-browser install một lần để tải Chrome for Testing. Bạn cũng có thể gắn vào Chrome đang chạy bằng --cdp hoặc --auto-connect. Trên Linux nên dùng agent-browser install --with-deps.
