Agentero: bàn làm việc nghiên cứu cho người và Agent đọc PDF, ghi chú — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về poco-ai/Agentero — 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: Agentero: bàn làm việc nghiên cứu cho người và AI Agent — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Agentero là ứng dụng desktop mã nguồn mở (MIT) để đọc PDF, ghi chú và hỏi đáp tài liệu cùng Agent AI chạy trên máy bạn. Dữ liệu lưu thành file PDF và Markdown thường, có thể nhập từ Zotero. Cài khá dễ: tải bản dựng sẵn trên trang chủ hoặc GitHub Releases, hoặc dùng Homebrew trên macOS.
Agentero là một ứng dụng desktop dành cho người làm nghiên cứu, gom ba việc hay bị tách rời vào cùng một chỗ: đọc PDF, ghi chú, và làm việc với Agent AI. Bạn đọc PDF như bình thường, còn Agent nhận được bản nội dung đã được tách gọn (Markdown, LaTeX) để trả lời chính xác hơn. Repo có giấy phép MIT, viết chủ yếu bằng TypeScript.
Vấn đề mà tác giả nhắm tới khá quen thuộc. Bài báo nằm trong một phần mềm quản lý thư viện, ghi chú nằm ở một app khác, còn phần trao đổi với AI thì nằm rải rác trong các khung chat trên web. Mỗi lần muốn AI phân tích một bài báo kèm ghi chú cũ, bạn phải copy-paste qua lại. Agentero cố gắng nối các mảnh này lại, và tác giả nói rõ là không nhằm thay thế Zotero mà bổ sung cho nó.
Nếu bạn là sinh viên, nghiên cứu sinh, hay bất kỳ ai phải đọc nhiều tài liệu PDF dài và muốn có trợ lý AI đọc cùng, repo này đáng thử. Điểm đáng giá nhất là mọi thứ lưu thành file thường (PDF, Markdown) trên máy bạn, và Agent kết nối qua giao thức mở nên không bị buộc vào một hãng AI nào. Repo hiện có khoảng 2464 sao và 151 fork, vẫn được cập nhật trong vài tháng gần đây.
poco-ai/Agentero
Ứng dụng desktop gom đọc PDF, ghi chú Markdown và Agent AI cục bộ vào một nơi, giúp nghiên cứu tài liệu mà không phải copy-paste qua lại.
I.Agentero làm được gì
A.Đọc PDF và ghi chú ngay trong một ứng dụng
Trình đọc PDF có mục lục, chế độ vừa trang hoặc vừa chiều rộng, bôi chọn chữ, tô sáng, chú thích và tìm kiếm toàn văn. Bạn không phải học một cách đọc mới, vẫn là PDF quen thuộc.
Phần ghi chú là trình soạn Markdown dạng xem là thấy luôn kết quả. Nó hỗ trợ liên kết hai chiều kiểu [[tên ghi chú]], lệnh nhanh bằng dấu / và hiển thị công thức LaTeX. Ghi chú gắn trực tiếp với tài liệu, nên sau này tìm lại rất nhanh.
B.Tách bảng biểu và công thức cho AI đọc chính xác
PDF hai cột, bảng nhiều trang hay công thức toán là thứ AI hay đọc sai. Agentero tự tách công thức, mã giả thuật toán và bảng ra thành Markdown và LaTeX. Nhờ vậy khi bạn hỏi Agent về một bảng số liệu, nó làm việc trên bản sạch thay vì đoán từ ảnh chụp trang.
C.Dịch ngay khi đọc
Có dịch từ được bôi chọn, dịch song song theo trang và dịch cả tài liệu. Ứng dụng có sẵn kênh dịch dùng được, và bạn cũng có thể điền API key của riêng mình (kiểu BYOK). Với người đọc tài liệu tiếng Anh hay tiếng Trung, đây là phần tiện nhất.
D.Kết nối Agent chạy trên máy bạn
Agentero dùng giao thức Agent Client Protocol (ACP) để nối với các Agent cục bộ như Claude Code, OpenCode, Codex hoặc mô hình chạy local. Bạn chọn Agent nào tùy ý, và theo tác giả, ngữ cảnh vẫn nằm trên máy bạn.
Ngoài ra ứng dụng có thể chạy như một MCP Server, để các công cụ bên ngoài như Claude Desktop hay ChatGPT Web truy vấn thư viện tài liệu cục bộ của bạn làm ngữ cảnh.
E.Dòng lệnh để tự động hoá
Có công cụ CLI không cần giao diện, dùng để viết script nhập tài liệu hàng loạt, lấy metadata và ghi ghi chú. Hợp với người muốn tự động hoá, ví dụ sau khi một công cụ tìm kiếm trả về cả trăm bài.
F.Tìm tài liệu mới và lần theo trích dẫn
Ứng dụng tích hợp Cool Papers và cộng đồng ModelScope để duyệt và lưu bài báo bằng một cú bấm, kèm theo dõi RSS học thuật. Nó còn gợi ý bài arXiv mới mỗi ngày dựa trên những gì bạn đã có trong thư viện. Danh sách tài liệu tham khảo cuối bài được tách tự động và có thể nhập hàng loạt vào thư viện.
G.Tương thích Zotero, lưu trữ minh bạch
Bạn có thể nhập cả thư viện Zotero, giữ nguyên thẻ, ghi chú và tệp đính kèm. Tiện ích trình duyệt của Zotero vẫn lưu được bài vào Agentero, và có thể xuất BibTeX hoặc BibLaTeX.
Dữ liệu không nằm trong cơ sở dữ liệu kín: mọi thứ là PDF và Markdown trong thư mục bình thường, bạn mở bằng trình soạn thảo khác cũng được. Ngoài ra có đồng bộ qua dịch vụ lưu trữ tương thích S3 và truy cập thư viện đặt trên máy chủ từ xa qua đường hầm SSH.
II.Cần chuẩn bị gì
Tư liệu của repo nói khá ít về yêu cầu, nên mình chỉ nêu những gì có:
- Hệ điều hành: có bản cho macOS, Windows và Linux.
- Linux: cần Ubuntu 22.04 trở lên, vì phần mềm phụ thuộc
webkit2gtk 4.1. - macOS: nếu muốn cài bằng dòng lệnh thì cần Homebrew.
- Agent AI (tuỳ chọn): muốn hỏi đáp với Agent thì bạn cần có sẵn một Agent chạy cục bộ, ví dụ Claude Code, OpenCode hoặc Codex. Mỗi Agent có yêu cầu tài khoản hoặc key riêng, README của Agentero chưa nói chi tiết phần này.
- API key dịch (tuỳ chọn): chỉ cần nếu bạn muốn dùng kênh dịch riêng thay cho kênh có sẵn.
README không nêu phiên bản Node hay yêu cầu GPU. Nếu bạn dùng bản cài dựng sẵn thì thường không cần quan tâm.
III.Cài đặt từng bước
- Chọn bản càiQuyết định dùng bản desktop, CLI hay cả hai
- Cài app desktopTải bộ cài từ trang chủ/Releases, hoặc dùng Homebrew trên macOS
- Cài CLI (nếu cần)Dùng Homebrew để có lệnh agentero
- Mở app lần đầuNhập thư viện Zotero hoặc thêm PDF đầu tiên
- Nối AgentCấu hình Agent cục bộ trong phần Agent và kết nối
A.Chọn bản cài phù hợp
Có hai thứ tách biệt: ứng dụng desktop (có giao diện) và công cụ dòng lệnh. Người mới nên bắt đầu với ứng dụng desktop. CLI chỉ cần khi bạn muốn viết script tự động.
B.Cài ứng dụng desktop trên Windows, macOS, Linux
README hướng dẫn tải bộ cài dựng sẵn từ trang chủ agentero.app hoặc mục Releases trên GitHub của dự án. Bạn chọn đúng file cho hệ điều hành của mình, tải về và chạy như mọi phần mềm khác. README không ghi tên file cụ thể, nên bạn nhìn tên file trên trang Releases để chọn cho đúng.
Trên macOS có thêm cách dùng Homebrew. Mở ứng dụng Terminal rồi chạy:
brew tap poco-ai/agentero
brew install --cask agenteroDòng đầu thêm kho phần mềm của tác giả vào Homebrew. Dòng thứ hai cài ứng dụng có giao diện (--cask nghĩa là ứng dụng đồ hoạ). Nếu máy báo không có lệnh brew, nghĩa là bạn chưa cài Homebrew, hãy dùng cách tải bộ cài.
Với Linux, hãy chắc chắn bạn dùng Ubuntu 22.04 trở lên. README trỏ đến tài liệu cài đặt trong thư mục docs/ của repo cho phần phụ thuộc chi tiết.
C.Cài công cụ dòng lệnh (không bắt buộc)
README ghi cách cài CLI bằng Homebrew:
brew tap poco-ai/agentero
brew install agentero
# xem các lệnh và tuỳ chọn thường dùng
agentero --helpLưu ý chỗ này không có --cask, vì đây là gói dòng lệnh. Lệnh agentero --help in ra danh sách lệnh con và tham số. Mình không liệt kê lệnh con ở đây vì README không ghi, bạn chạy --help trên máy là chính xác nhất. README chỉ nêu cách cài CLI qua Homebrew; nếu bạn dùng Windows hay Linux, mình chưa thấy hướng dẫn riêng, nên hãy xem thêm mục Releases hoặc thư mục docs/.
D.Chạy lần đầu
Mở ứng dụng, sau đó bạn có thể nhập thư viện Zotero cũ hoặc thêm PDF đầu tiên. Phần Agent nằm trong mục cấu hình Agent và kết nối, nơi bạn quản lý và chuyển đổi các Agent cục bộ qua ACP.
E.Tự dựng từ mã nguồn
README chưa ghi cách tự build. Repo có package.json, Cargo.toml, thư mục src-tauri/ và tệp CONTRIBUTING.md, nên nếu bạn muốn tự dựng, hãy đọc CONTRIBUTING.md và docs/ trước, đừng đoán lệnh. Việc lấy mã về thì chắc chắn đúng:
git clone https://github.com/poco-ai/Agentero.git
cd AgenteroF.Cài plugin cho DeepSeek Harness (tuỳ chọn)
Nếu bạn dùng DeepSeek Harness (dsh), README có lệnh cài plugin để dùng thư viện tài liệu, ghi chú và trình đọc PDF của Agentero ngay trong đó:
dsh plugin --profile web add @poco-ai/agentero-dshChi tiết có ở repo riêng tên agentero-dsh-plugin.
IV.Kiểm tra đã chạy được chưa
Với ứng dụng desktop, dấu hiệu thành công đơn giản là cửa sổ Agentero mở ra và bạn thêm được một file PDF để đọc, tô sáng và ghi chú. Hãy thử mở một bài báo có công thức hoặc bảng để xem phần tách nội dung hoạt động.
Với CLI, chạy:
agentero --helpNếu in ra danh sách lệnh và tham số thì CLI đã cài xong. Nếu báo không tìm thấy lệnh, hãy mở lại cửa sổ terminal mới rồi thử lại.
Với phần Agent, bạn nên thử hỏi một câu ngắn về bài đang mở và xem Agent có trả lời dựa trên nội dung bài hay không. README không mô tả thông báo cụ thể, nên đây là cách kiểm tra thực tế.
V.Dùng vào việc thật
A.Nghiên cứu sinh chuyển từ Zotero sang
Bạn có vài trăm bài trong Zotero, kèm thẻ và ghi chú. Thay vì làm lại từ đầu, hãy dùng chức năng nhập thư viện Zotero của Agentero. Theo README, thẻ, ghi chú và tệp đính kèm được giữ nguyên. Sau đó bạn vẫn dùng tiện ích trình duyệt của Zotero để lưu bài mới, còn việc đọc và hỏi Agent thì làm trong Agentero. Kết quả là bạn có thư viện cũ nhưng thêm được khả năng hỏi đáp trên nội dung.
B.Đọc một bài báo khó có nhiều công thức
Bạn đọc một bài có bảng so sánh nhiều cột và vài công thức. Mở bài trong Agentero, tô sáng đoạn quan trọng, rồi hỏi Agent đã kết nối, ví dụ:
Tóm tắt phương pháp chính của bài này. Giải thích công thức ở mục 3 bằng lời đơn giản và cho biết bảng 2 so sánh những gì.Vì công thức và bảng đã được tách thành Markdown và LaTeX, câu trả lời ít bị sai hơn so với việc dán đoạn văn bản bị vỡ từ PDF. Ý hay trong lúc đọc thì bạn lưu thẳng vào ghi chú Markdown.
Người đọc giữ phần phán đoán, Agent lo phần việc lặt vặt: đó là cách chia việc mà Agentero hướng tới.
Ông T
C.Dùng thư viện cá nhân từ Claude Desktop qua MCP
Bạn đã quen hỏi trong Claude Desktop và muốn nó biết bạn đang có những bài nào. Agentero có thể chạy như một MCP Server, nên bạn cấu hình Claude Desktop trỏ đến nó rồi hỏi kiểu: tìm trong thư viện của tôi các bài nói về một chủ đề, rồi so sánh kết quả của chúng. README không ghi chi tiết cách cấu hình, bạn xem thêm trong docs/ hoặc trang chủ dự án. Kết quả là bạn không phải tải từng PDF lên khung chat nữa.
D.Nhập hàng loạt bằng script
Bạn là lập trình viên và có sẵn danh sách bài cần lưu từ một công cụ tìm kiếm. Hãy chạy agentero --help để xem lệnh nhập có sẵn, rồi viết một script nhỏ lặp qua danh sách. README nói CLI hỗ trợ nhập hàng loạt, lấy metadata và ghi ghi chú, nhưng không liệt kê cú pháp, nên đừng chép lệnh từ nơi khác mà không kiểm tra. Kết quả là thư viện đầy đủ mà không phải bấm lưu từng bài trên trình duyệt.
Agent và dịch vụ dịch có thể cần tài khoản hoặc API key riêng, và có thể tốn phí theo nhà cung cấp. Hãy giữ key ở nơi an toàn, đừng đưa vào file hoặc ảnh chụp màn hình chia sẻ công khai. Nếu tài liệu của bạn là bí mật, hãy kiểm tra Agent bạn dùng gửi dữ liệu đi đâu.
VI.Lỗi hay gặp và cách xử lý
A.Không cài được trên Linux
Thường do hệ điều hành cũ hoặc thiếu thư viện. README yêu cầu Ubuntu 22.04 trở lên và webkit2gtk 4.1. Hãy kiểm tra phiên bản hệ điều hành trước, rồi xem tài liệu cài đặt trong docs/.
B.Gõ lệnh brew báo không tìm thấy
Nghĩa là máy chưa có Homebrew, hoặc terminal chưa nhận. Hãy cài Homebrew theo hướng dẫn chính thức của nó, mở terminal mới, hoặc bỏ qua và tải bộ cài từ Releases.
C.Agent không trả lời hoặc không kết nối được
Agentero chỉ là cầu nối, còn Agent như Claude Code hay Codex phải được cài và đăng nhập riêng trước. Hãy thử chạy Agent đó một mình trong terminal để chắc nó hoạt động, sau đó quay lại phần cấu hình Agent trong ứng dụng.
D.Dịch không chạy
Nếu bạn dùng kênh dịch riêng, thường là do key sai, hết hạn hoặc hết hạn mức. Kiểm tra lại key ở nhà cung cấp, hoặc quay về kênh dịch có sẵn.
E.Nhập Zotero chưa như ý
Hãy sao lưu thư viện Zotero trước khi nhập, và thử với một thư viện nhỏ để xem kết quả. Nếu thấy thiếu tệp đính kèm, kiểm tra xem đường dẫn tệp trong Zotero còn đúng không, rồi xem mục Issues của repo để biết lỗi đã được báo hay chưa.
VII.Có nên dùng không
Điểm mạnh. Mọi thứ nằm trên máy dưới dạng file thường, nên bạn không bị khoá vào một định dạng riêng. Việc nhập từ Zotero giúp chuyển sang nhẹ nhàng. Kết nối Agent qua giao thức mở nghĩa là bạn chọn Agent theo ý mình, và có thể dùng cả MCP lẫn CLI. Giấy phép MIT, dự án đang được cập nhật.
Giới hạn. README viết bằng tiếng Trung là chính, có bản tiếng Anh, chưa có tài liệu tiếng Việt. Phần hướng dẫn cài chi tiết cho CLI trên Windows và Linux, cũng như cách cấu hình MCP, README chưa ghi rõ. Chất lượng trả lời phụ thuộc vào Agent bạn nối, không phải do Agentero. Việc đồng bộ và truy cập từ xa cần bạn tự có dịch vụ S3 hoặc máy chủ.
Khi nào chọn cách khác. Nếu bạn chỉ cần quản lý trích dẫn đơn giản và không dùng AI, Zotero thuần vẫn đủ. Nếu bạn chỉ thỉnh thoảng hỏi AI về một file PDF, dán vào khung chat có thể nhanh hơn. Agentero đáng thử khi bạn đọc nhiều tài liệu, ghi chú nhiều, và muốn AI làm việc trên cùng một kho dữ liệu của mình.
Câu hỏi thường gặp
Agentero có miễn phí không?
Repo dùng giấy phép MIT, là mã nguồn mở. README không nói về gói trả phí của chính Agentero. Tuy nhiên Agent hoặc dịch vụ dịch bạn nối vào có thể tính phí riêng theo nhà cung cấp.
Agentero chạy được trên Windows không?
Có. README nói có bản cài dựng sẵn cho macOS, Windows và Linux, tải từ trang chủ agentero.app hoặc mục Releases trên GitHub. Riêng Linux cần Ubuntu 22.04 trở lên.
Có cần GPU không?
README không nhắc yêu cầu GPU. Nếu bạn nối với mô hình chạy cục bộ thì yêu cầu phần cứng phụ thuộc vào mô hình đó, tư liệu của Agentero chưa có thông tin cụ thể.
Dữ liệu của tôi có an toàn không?
Theo README, tài liệu và ghi chú được lưu ở thư mục trên máy dưới dạng PDF và Markdown, và ngữ cảnh khi dùng Agent cục bộ được giữ trên máy. Tuy vậy, nếu Agent bạn chọn gửi dữ liệu lên dịch vụ đám mây thì còn tuỳ chính sách của dịch vụ đó.
Agentero khác gì Zotero?
Tác giả nói Agentero không nhằm thay thế Zotero. Điểm khác là nó tích hợp sẵn đọc PDF, ghi chú, Agent AI, dịch và tách công thức, bảng thành Markdown cho mô hình đọc. Bạn có thể nhập thư viện Zotero vào và vẫn dùng tiện ích trình duyệt của Zotero để lưu bài.
Dùng được với Claude Code hay Claude Desktop không?
Có. Agentero kết nối Agent cục bộ như Claude Code, OpenCode, Codex qua giao thức ACP. Nó cũng chạy được như MCP Server để Claude Desktop hay ChatGPT Web truy vấn thư viện của bạn. README chưa ghi từng bước cấu hình cho phần MCP.
Có dùng được từ dòng lệnh không?
Có. README ghi cách cài CLI bằng Homebrew (brew tap poco-ai/agentero rồi brew install agentero) và dùng agentero --help để xem lệnh. CLI hỗ trợ nhập tài liệu hàng loạt, lấy metadata và ghi ghi chú.


