agent-browser

Overview

What is agent-browser?

agent-browser là công cụ automation trình duyệt dùng qua command line, được thiết kế cho AI agent và các workflow dựa trên shell. Nó kết nối trực tiếp tới Chrome hoặc Chromium qua Chrome DevTools Protocol (CDP), giúp bạn script các tương tác trình duyệt thực từ terminal hoặc trong môi trường runtime của agent.

Với agent-browser bạn có thể:

• Mở và điều hướng trang web (agent-browser open <url>)
• Khám phá các phần tử tương tác thông qua snapshot có cấu trúc
• Click nút, đi theo link và tương tác với form
• Điền input, gõ text và nhấn phím
• Chụp snapshot để hiểu cấu trúc trang và các hành động khả dụng
• Quản lý session và giữ lại trạng thái đã đăng nhập
• Thực hiện các flow đăng nhập (bao gồm OAuth và 2FA với hỗ trợ từ con người)
• Dùng proxy cho kiểm thử theo vùng địa lý hoặc trong môi trường doanh nghiệp
• Ghi trace hiệu năng để profiling
• Ghi lại video phiên trình duyệt phục vụ debug hoặc tài liệu hóa

Who is agent-browser for?

agent-browser phù hợp nếu bạn:

• Vận hành AI agent hoặc framework tự động hóa cần điều khiển trình duyệt thực
• Muốn một cách tiếp cận ưu tiên CLI để tự động hóa workflow trên Chrome/Chromium
• Cần cơ chế chọn phần tử mạnh, thân thiện với LLM (dùng @refs gọn nhẹ)
• Tự động hóa luồng đăng nhập, gửi form hoặc các flow web app nhiều bước
• Ghi lại test, demo hoặc phiên debug có thể tái lập dưới dạng video hoặc trace

Đặc biệt hữu ích trong các tình huống:

• Browser automation: điều hướng có script, click và điền form
• Workflow automation: các chuỗi end-to-end như "log in → navigate → export report"
• Test automation: smoke test, kiểm tra hồi quy và profiling hiệu năng web app

When agent-browser is and is not a good fit

Nên dùng agent-browser khi:

• Bạn có thể chạy CLI cục bộ và có quyền truy cập Chrome hoặc Chromium
• Bạn muốn hành vi trình duyệt có thể script, mang tính quyết định và phơi ra cho AI agent
• Bạn cần kiểm soát chi tiết session, cookie và cơ chế đăng nhập

Có thể không phù hợp khi:

• Bạn không thể cài hoặc chạy Chrome/Chromium trên máy host
• Bạn chỉ cần HTML thô hoặc các request HTTP đơn giản (HTTP client hoặc scraper thuần túy có thể đơn giản hơn)
• Bạn cần điều khiển headless browser trong ngôn ngữ hoặc runtime đã gắn chặt với các thư viện automation trình duyệt khác

How to Use

Installation options

agent-browser hỗ trợ nhiều cách cài đặt. Hãy chọn phương án phù hợp với môi trường của bạn:

• npm (Node.js)

  npm i -g agent-browser
  

• Homebrew (macOS/Linux)

  brew install agent-browser
  

• Rust / Cargo

  cargo install agent-browser
  

Sau khi cài CLI, chạy bước thiết lập Chrome tích hợp sẵn:

agent-browser install

Lệnh này tải về và cấu hình một bản Chrome/Chromium tương thích. Khi có phiên bản mới, cập nhật bằng:

agent-browser upgrade

Nếu bạn dùng agent-browser như một skill trong nền tảng agent, bạn cũng có thể thêm nó bằng:

npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser

Xem file SKILL.md trong repository để cập nhật chi tiết wiring dành riêng cho skill.

Core browser automation workflow

Mọi workflow với agent-browser tuân theo một vòng lặp đơn giản: open → snapshot → interact → re-snapshot.

1. Đi tới một trang

   agent-browser open https://example.com/form
   

2. Chụp snapshot để khám phá phần tử
   Dùng chế độ snapshot tương tác để lấy danh sách gọn các phần tử có thể click/điền với @refs:

   agent-browser snapshot -i
   

   Ví dụ output (đơn giản hóa):

   @e1 [input type="email"]
   @e2 [input type="password"]
   @e3 [button] "Submit"
   

3. Tương tác bằng ref

   agent-browser fill @e1 "user@example.com"
   agent-browser fill @e2 "password123"
   agent-browser click @e3
   

4. Chờ và chụp lại snapshot

   agent-browser wait --load networkidle
   agent-browser snapshot -i
   

Mẫu này cho phép AI agent suy luận dựa trên một ảnh cấu trúc gọn thay vì toàn bộ DOM, từ đó giảm đáng kể mức sử dụng context.

Command reference basics

agent-browser cung cấp bộ lệnh phong phú (xem references/commands.md), bao gồm:

• Navigation

  agent-browser open <url>
  agent-browser back
  agent-browser forward
  agent-browser reload
  agent-browser close
  

• Snapshot and refs

  agent-browser snapshot          # full tree
  agent-browser snapshot -i       # chỉ phần tử tương tác (khuyến nghị)
  agent-browser snapshot -c       # output gọn
  agent-browser snapshot -d 3     # giới hạn độ sâu
  agent-browser snapshot -s "#main"  # giới hạn theo CSS selector
  

• Interactions

  agent-browser click @e1
  agent-browser dblclick @e1
  agent-browser hover @e1
  agent-browser focus @e1
  agent-browser fill @e2 "text"
  agent-browser type @e2 "text"
  agent-browser press Enter
  

Tham khảo references/snapshot-refs.md để hiểu chi tiết cách @refs được tạo và thời gian chúng còn hiệu lực.

Working with sessions and authentication

agent-browser tích hợp sẵn công cụ cho duyệt web có đăng nhập và đa session. Điều này hữu ích cho luồng đăng nhập, kiểm thử đa tài khoản hoặc tách biệt vai trò người dùng.

• Named sessions (xem references/session-management.md):

  # Session "auth": luồng đăng nhập
  agent-browser --session auth open https://app.example.com/login
  
  # Session "public": duyệt tách riêng
  agent-browser --session public open https://example.com
  

  Mỗi session có cookie, storage, cache và history độc lập.

• Session state persistence:

  # Lưu cookie và storage
  agent-browser state save ./auth-state.json
  
  # Khôi phục sau này
  agent-browser state load ./auth-state.json
  agent-browser open https://app.example.com/dashboard
  

• Authentication patterns (xem references/authentication.md):

  • Import cookie từ một phiên Chrome bật debug mà bạn đã đăng nhập sẵn
  • Đi qua form đăng nhập chuẩn bằng snapshot và lệnh fill/click
  • Xử lý đăng nhập dựa trên cookie, HTTP basic auth và token refresh

Với các luồng OAuth hoặc 2FA phức tạp, thường vẫn cần con người tham gia thiết lập ban đầu, sau đó agent-browser có thể tái sử dụng trạng thái đã đăng nhập đã lưu.

Proxy support and network configuration

Nếu cần route traffic qua proxy (cho kiểm thử vùng địa lý, giới hạn tần suất hoặc mạng doanh nghiệp), hãy dùng các lựa chọn trong references/proxy-support.md:

• HTTP/HTTPS proxy qua CLI flag

  agent-browser --proxy "http://proxy.example.com:8080" open https://example.com
  

• Cấu hình qua biến môi trường

  export HTTP_PROXY="http://proxy.example.com:8080"
  export HTTPS_PROXY="https://proxy.example.com:8080"
  agent-browser open https://example.com
  

• SOCKS proxy

  export ALL_PROXY="socks5://proxy.example.com:1080"
  agent-browser open https://example.com
  

Profiling and performance tracing

Cho test automation và điều tra hiệu năng, agent-browser có thể ghi Chrome performance trace (xem references/profiling.md):

# Start profiling
agent-browser profiler start

# Run your scenario
agent-browser open https://example.com
agent-browser click @e1
agent-browser wait 1000

# Stop and save trace
agent-browser profiler stop ./trace.json

Bạn có thể mở trace.json trong Chrome DevTools (tab Performance) hoặc các viewer tương thích để phân tích thực thi JavaScript, render và các sự kiện user timing.

Video recording for debugging and documentation

agent-browser có thể ghi video phiên trình duyệt, rất hữu ích khi debug automation lỗi hoặc tạo hướng dẫn sử dụng (xem references/video-recording.md):

# Start recording
agent-browser record start ./demo.webm

# Perform actions
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1

# Stop recording
agent-browser record stop

Bạn có thể nhúng các file .webm này vào tài liệu, chia sẻ với đồng đội hoặc đính kèm trong báo cáo bug.

Using templates for common workflows

Repository cung cấp các shell script mẫu trong thư mục templates/ để giúp bạn xây dựng workflow có thể lặp lại:

• templates/form-automation.sh – mẫu có cấu trúc cho việc điền và gửi form
• templates/authenticated-session.sh – ví dụ đăng nhập và lưu trạng thái session
• templates/capture-workflow.sh – mẫu cho việc snapshot hoặc ghi hình một flow nhiều bước

Bạn có thể sao chép và chỉnh sửa các script này cho môi trường của mình, cho job CI hoặc pipeline của agent.

FAQ

What problems does agent-browser solve compared to simple HTTP clients?

agent-browser điều khiển một instance Chrome/Chromium thực qua CDP. Điều đó có nghĩa là nó xử lý được:

• Render phía client và JavaScript phức tạp
• Single-page app phụ thuộc vào các API trình duyệt
• Tương tác giống người dùng thật như click, gõ phím và nhấn phím tắt
• Thời gian hiển thị, hành vi render và performance trace

Nếu bạn chỉ cần HTML hoặc JSON thô từ các endpoint cơ bản, HTTP client là đủ. Nhưng với mọi thứ cần hành vi giống người dùng trong trình duyệt, agent-browser phù hợp hơn.

How do I install Chrome or Chromium for agent-browser?

Sau khi cài CLI bằng npm, Homebrew hoặc Cargo, hãy chạy:

agent-browser install

Lệnh này tải và cấu hình bản Chrome/Chromium tương thích để agent-browser điều khiển qua CDP. Khi có bản mới, cập nhật bằng:

agent-browser upgrade

Can agent-browser reuse my existing logged-in browser session?

Có. references/authentication.md mô tả cách khởi động Chrome với --remote-debugging-port và import cookie từ phiên mà bạn đã đăng nhập sẵn. Sau khi import, bạn có thể lưu trạng thái đã đăng nhập bằng agent-browser state save và khôi phục sau mà không cần lặp lại toàn bộ luồng đăng nhập.

Is agent-browser suitable for CI and automated testing?

Có. agent-browser là công cụ CLI hoạt động tốt trong môi trường tự động, miễn là Chrome/Chromium khả dụng. Bạn có thể:

• Chạy các flow end-to-end như một phần của test suite
• Ghi performance trace trong quá trình build
• Ghi video các kịch bản lỗi

Đối với CI, hãy chọn cách cài đặt phù hợp với build image (npm, Homebrew hoặc Cargo), sau đó script các flow bằng shell script hoặc framework agent của bạn.

How does agent-browser help AI agents work with complex pages?

Thay vì đổ toàn bộ DOM, agent-browser cung cấp snapshot gọn với @refs ổn định cho các phần tử quan trọng (link, button, input, v.v.). Điều này giảm mạnh token và giúp AI agent dễ dàng:

• Hiểu cấu trúc trang
• Chọn đúng phần tử bằng ref
• Gửi lệnh click, fill và press chính xác

references/snapshot-refs.md giải thích cách tạo ref, khi nào nên refresh và các best practice cho automation ổn định.

Does agent-browser support proxies and corporate networks?

Có. Bạn có thể cấu hình proxy HTTP, HTTPS và SOCKS thông qua CLI flag (--proxy) hoặc biến môi trường (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY). references/proxy-support.md trình bày cấu hình cơ bản, proxy có xác thực, luật bypass và mẹo xử lý sự cố.

Where should I start in the repository to learn more?

Để tìm hiểu sâu hơn về agent-browser trong thực tế:

• Bắt đầu với SKILL.md để có overview và quick start
• Đọc references/commands.md để xem đầy đủ danh sách lệnh và tùy chọn
• Xem references/authentication.md, references/session-management.md, references/snapshot-refs.md, references/profiling.md và references/video-recording.md cho từng chủ đề chuyên sâu
• Khám phá thư mục templates/ để lấy các script workflow sẵn có và tùy biến cho use case của bạn