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
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) cho nghiên cứu: đọc PDF, ghi chú, dịch, và cho AI Agent hỏi đáp trên chính kho tài liệu của bạn. Dữ liệu là file PDF và Markdown thường, nằm trong máy. Cài bằng bộ cài dựng sẵn hoặc Homebrew, không cần biên dịch.
Agentero là một ứng dụng desktop dành cho việc nghiên cứu, nơi bạn đọc PDF, ghi chú và để AI Agent hỏi đáp trên cùng một kho tài liệu. Nó chạy trên macOS, Windows và Linux. Nó là phần mềm mã nguồn mở, viết chủ yếu bằng TypeScript.
Vấn đề nó giải quyết rất quen thuộc. Bài báo nằm ở một phần mềm quản lý tài liệu, ghi chú nằm ở một app khác, còn phần phân tích với AI nằm rải rác trong các khung chat trên web. Mỗi lần nhờ AI phân tích một bài cụ thể, bạn lại phải copy-paste qua lại. Agentero gom ba thứ đó về một nơi. Tác giả nói rõ họ không định thay thế Zotero. Họ muốn thử một cách làm việc mới giữa người và Agent.
Bạn nên xem qua nếu bạn làm nghiên cứu, viết luận văn, đọc nhiều bài báo khoa học, hoặc đơn giản là hay đọc tài liệu PDF dài rồi phải tổng hợp. Điểm đáng giá nhất là tài liệu được lưu dưới dạng file PDF và Markdown bình thường trong thư mục trên máy. Bạn mở bằng phần mềm khác cũng được. Hiện repo có khoảng 2464 sao và 151 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.
poco-ai/Agentero
Ứng dụng desktop gom đọc PDF, ghi chú và hỏi đáp có trích dẫn vào một chỗ, để bạn và AI Agent cùng làm việc trên một kho tài liệu nằm ngay trong máy.
I.Agentero làm được gì
A.Đọc PDF và ghi chú
Bạn có trình đọc PDF với mục lục điều hướng, tự co theo trang hoặc theo chiều rộng, bôi đen chọn chữ, highlight, chú thích và tìm kiếm toàn văn. Bên cạnh đó là trình soạn thảo Markdown kiểu xem là thấy ngay, hỗ trợ liên kết hai chiều viết dạng [[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 bài báo, không cần ghép tay.
B.Trích công thức, bảng, thuật toán
Theo README, Agentero tự phân tích công thức toán, mã giả thuật toán và bảng trong bài, rồi chuyển thành Markdown và LaTeX. Lý do: PDF hai cột, bảng nhiều trang và công thức phức tạp rất dễ làm AI đọc sai. Dạng có cấu trúc giúp AI trả lời chính xác hơn.
C.Dịch thuật
Có dịch khi bôi chữ, dịch đối chiếu theo trang và dịch toàn văn. Có sẵn kênh dịch dùng được ngay. Nếu muốn, bạn điền API Key của riêng mình (README gọi là BYOK).
D.Kết nối Agent bên ngoài
Agentero dùng giao thức Agent Client Protocol (ACP) để nối với các Agent chạy trên máy bạn, như Claude Code, OpenCode, Codex hoặc mô hình chạy cục bộ. Nó không gắn với một hãng nào. Ngoài ra nó còn chạy được như một MCP server, để các ứng dụng như ChatGPT Web hay Claude Desktop truy vấn kho tài liệu của bạn.
E.Dòng lệnh để chạy hàng loạt
Có công cụ CLI chạy không cần giao diện, để viết script nhập nhiều tài liệu, trích metadata và ghi ghi chú tự động.
F.Tìm và theo dõi tài liệu mới
Bạn duyệt Cool Papers và cộng đồng ModelScope ngay trong app, lưu một cú nhấp. Có RSS học thuật, gợi ý bài arXiv mới mỗi ngày dựa trên kho tài liệu bạn đang có, và tự tách danh sách tài liệu tham khảo cuối bài để nhập hàng loạt.
G.Tương thích Zotero, lưu trữ minh bạch
Bạn nhập cả thư viện Zotero một lần, 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 bài vào được, và có thể xuất BibTeX/BibLaTeX. Đồng bộ qua dịch vụ lưu trữ tương thích S3, hoặc truy cập kho đặt trên máy chủ từ xa qua đường hầm SSH.
II.Cần chuẩn bị gì
- Hệ điều hành: macOS, Windows hoặc Linux. Với Linux, README yêu cầu Ubuntu 22.04 trở lên (phụ thuộc
webkit2gtk 4.1). - Nếu dùng Homebrew: bạn cần đã cài Homebrew sẵn.
- Nếu muốn hỏi đáp với AI: bạn cần một Agent chạy trên máy (ví dụ Claude Code, OpenCode, Codex) hoặc một mô hình cục bộ. Tài khoản và chi phí của các Agent đó thuộc về bên cung cấp, README không nói chi tiết.
- API Key: chỉ cần khi bạn muốn dùng kênh dịch riêng của mình.
- Phiên bản Node/Python: README không yêu cầu cho người dùng cuối, vì có bộ cài dựng sẵn. Bạn chỉ cần Node và pnpm nếu muốn tự build từ mã nguồn. Phần đó README chưa ghi, hãy xem
CONTRIBUTING.mdvà thư mụcdocs/trong repo. - Phần cứng: README không nêu yêu cầu GPU hay RAM.
III.Cài đặt từng bước
- Chọn cách càiBộ cài từ trang chủ/Releases, hoặc Homebrew trên macOS
- Cài ứng dụng desktopTải bộ cài hoặc chạy lệnh brew
- (Tuỳ chọn) Cài CLIDùng brew để có lệnh agentero
- (Tuỳ chọn) Cài plugin dshNếu bạn dùng DeepSeek Harness
- Mở app và nhập thư việnMở Agentero, nhập từ Zotero nếu có
A.Cài ứng dụng trên Windows hoặc Linux
README hướng dẫn tải bộ cài dựng sẵn cho từng hệ điều hành. Bạn vào trang chủ https://agentero.app hoặc mục Releases của repo trên GitHub, chọn file đúng hệ máy rồi chạy như cài phần mềm thông thường. README không đưa lệnh cài cho Windows, nên bạn chỉ cần tải file và mở lên.
Với Linux, README ghi môi trường cần là Ubuntu 22.04 trở lên. Chi tiết phụ thuộc nằm trong tài liệu cài đặt của dự án, bạn xem ở thư mục docs/.
B.Cài ứng dụng trên macOS bằng Homebrew
Mở ứng dụng Terminal (tìm trong Spotlight), rồi dán lần lượt các lệnh sau. Lệnh đầu thêm kho phần mềm của dự án, lệnh sau cài ứng dụng giao diện.
brew tap poco-ai/agentero
brew install --cask agenteroChỗ người mới hay vấp: nếu máy báo brew: command not found thì bạn chưa cài Homebrew. Hãy cài Homebrew trước.
C.Cài công cụ dòng lệnh (không bắt buộc)
Chỉ cần bước này nếu bạn muốn chạy script hoặc quản lý tài liệu bằng lệnh. Lệnh dưới đây cũng dùng Homebrew, và lệnh cuối liệt kê các lệnh và tuỳ chọn có sẵn.
brew tap poco-ai/agentero
brew install agentero
# xem các lệnh và tham số thường dùng
agentero --helpREADME không liệt kê chi tiết từng lệnh con. Hãy chạy agentero --help để xem đầy đủ.
D.Cài plugin cho DeepSeek Harness (không bắt buộc)
Nếu bạn đã dùng DeepSeek Harness (dsh), bạn có thể dùng thư viện, ghi chú và trình đọc PDF của Agentero ngay trong đó bằng lệnh sau. Chi tiết xem ở repo agentero-dsh-plugin mà README nhắc tới.
dsh plugin --profile web add @poco-ai/agentero-dshE.Mở app và nhập tài liệu
Mở Agentero như một ứng dụng bình thường. Nếu bạn đang dùng Zotero, README nói có tính năng nhập cả cơ sở dữ liệu Zotero, giữ thẻ, ghi chú và tệp đính kèm. Cách bấm cụ thể README chưa mô tả, bạn tìm trong phần cài đặt hoặc trong docs/.
Agentero lưu tài liệu trong thư mục trên máy bạn. Nếu bạn bật đồng bộ S3 hoặc nối Agent/dịch vụ bên ngoài, dữ liệu có thể đi ra khỏi máy tuỳ cấu hình của bạn. API Key của bạn tự giữ kỹ, đừng dán vào ghi chú hay chia sẻ cho người khác.
IV.Kiểm tra đã chạy được chưa
Với ứng dụng desktop, cách kiểm tra đơn giản nhất là mở app lên và thấy giao diện chính xuất hiện. Sau đó thử nhập một file PDF để xem trình đọc hiển thị bình thường. README không nêu một dòng "thành công" cụ thể nào.
Với CLI, chạy lệnh sau. Nếu terminal in ra danh sách lệnh và tham số thì CLI đã cài xong.
agentero --helpNếu bạn dùng Homebrew và muốn chắc ứng dụng nằm trong máy, hãy tìm Agentero trong danh sách ứng dụng. Nếu lệnh báo không tìm thấy, xem phần lỗi bên dưới.
V.Dùng vào việc thật
A.Sinh viên cao học đọc một bài báo dài
Bạn đang chuẩn bị luận văn và cần hiểu kỹ một bài báo có nhiều công thức. Bạn nhập PDF vào Agentero, mở ở chế độ đọc, highlight những đoạn quan trọng và dịch nhanh các câu khó bằng dịch khi bôi chữ. Sau đó bạn kết nối một Agent chạy trên máy qua ACP và hỏi theo kiểu: "Giải thích công thức chính của bài này theo từng bước". Vì công thức đã được tách ra dạng LaTeX, Agent ít đọc nhầm hơn. Kết quả là bạn có câu trả lời và những ý chính được ghi thẳng vào ghi chú Markdown gắn với bài.
Người đọc giữ phần phán đoán, Agent lo phần việc lặp đi lặp lại.
Ông T
B.Nhân viên nghiên cứu theo dõi tin ngành
Bạn làm ở bộ phận phân tích và cần theo dõi bài một trang tin tức mỗi ngày. Bạn thêm các nguồn RSS học thuật mà mình quan tâm, rồi xem phần gợi ý arXiv hằng ngày dựa trên những gì đã có trong kho. Bài nào đáng đọc, bạn lưu một cú nhấp. Kết quả là kho tài liệu của bạn lớn dần mà không phải mở trình duyệt lưu từng file.
C.Dev viết script nhập tài liệu hàng loạt
Bạn là lập trình viên đang có hàng chục bài cần đưa vào kho. Bạn cài CLI bằng Homebrew rồi chạy agentero --help để xem lệnh nào dùng cho nhập tài liệu, trích metadata hoặc ghi chú. Sau đó bạn nối các lệnh đó vào script của mình. README xác nhận CLI hỗ trợ các việc này nhưng không liệt kê tên lệnh con, nên bạn hãy đọc kết quả của --help rồi dùng đúng lệnh được in ra.
D.Người dùng ChatGPT hoặc Claude Desktop muốn trả lời theo kho riêng
Bạn muốn ứng dụng chat quen thuộc có thể tra cứu kho tài liệu trong máy. Theo README, Agentero chạy như một MCP server để các ứng dụng như ChatGPT Web hoặc Claude Desktop truy vấn kho của bạn. README chưa ghi từng bước cấu hình MCP, bạn xem hướng dẫn trong docs/ hoặc trên trang chủ. Kết quả mong đợi là AI trả lời dựa trên tài liệu thật của bạn thay vì đoán chung chung.
VI.Lỗi hay gặp và cách xử lý
A.Lệnh brew báo không tìm thấy
Bạn chưa cài Homebrew, hoặc terminal chưa nhận đường dẫn. Hãy cài Homebrew theo hướng dẫn chính thức của nó, mở lại terminal rồi chạy lại lệnh. Nếu bạn không muốn dùng Homebrew, hãy tải bộ cài từ trang chủ hoặc Releases.
B.Linux không mở được ứng dụng
README yêu cầu Ubuntu 22.04 trở lên và phụ thuộc webkit2gtk 4.1. Nếu bạn dùng bản cũ hơn, app có thể không chạy. Hãy kiểm tra phiên bản hệ điều hành và đọc tài liệu cài đặt của dự án trong thư mục docs/.
C.Lệnh agentero báo không nhận ra
Có thể bạn mới cài ứng dụng giao diện mà chưa cài CLI. Hai thứ này cài bằng hai lệnh khác nhau: brew install --cask agentero cho ứng dụng, brew install agentero cho CLI. Hãy chạy lệnh thứ hai rồi mở terminal mới.
D.Agent không trả lời hoặc không kết nối được
Agentero chỉ nối với Agent chạy trên máy bạn. Nếu Claude Code, OpenCode hay Codex chưa cài và đăng nhập được ở ngoài, thì app cũng không dùng được chúng. Hãy kiểm tra Agent đó chạy bình thường trước, rồi mới thêm vào phần cấu hình Agent trong app.
E.Dịch không chạy khi dùng khoá riêng
Nếu bạn tự điền API Key cho phần dịch, hãy kiểm tra lại key còn hiệu lực và còn hạn mức. Tuyệt đối không dán key vào ghi chú hay tin nhắn công khai. Nếu nghi ngờ lộ key, hãy tạo key mới ở nhà cung cấp.
VII.Có nên dùng không
Điểm mạnh lớn nhất là mọi thứ gom về một nơi và lưu bằng file thường (PDF, Markdown) trên máy. Bạn không bị khoá vào định dạng riêng, và có thể dùng song song với Zotero nhờ khả năng nhập thư viện. Việc kết nối Agent theo giao thức mở, cộng thêm MCP và CLI, cũng khiến nó linh hoạt hơn nhiều app đọc PDF thông thường.
Giới hạn thì bạn nên biết trước. README viết chủ yếu bằng tiếng Trung (có bản tiếng Anh riêng), nên người dùng Việt có thể phải đọc hoặc dịch tài liệu. README không nói rõ yêu cầu phần cứng, chi phí của các Agent mà bạn nối vào, hay chất lượng trích xuất công thức trên tài liệu quét xấu. Phần cấu hình MCP và Agent cũng chưa có hướng dẫn từng bước trong README, bạn phải tự tìm trong docs/.
Nếu bạn chỉ cần đọc PDF cho nhanh và không cần AI, một trình đọc PDF đơn giản là đủ. Nếu bạn đã quen và hài lòng với Zotero cùng bộ plugin của mình, bạn cũng chưa cần đổi. Còn nếu bạn hay phải copy-paste giữa bài báo, ghi chú và AI, Agentero đáng để thử, vì bạn có thể nhập thư viện cũ và quay lại bất cứ lúc nào.
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ở, và bạn có thể tải bộ cài từ trang chủ hoặc Releases. README không nêu phí cho chính ứng dụng. Các Agent hoặc dịch vụ bên ngoài mà bạn nối vào có thể có chi phí riêng theo nhà cung cấp.
Agentero chạy được trên Windows không?
Có. README nói có bộ cài dựng sẵn cho macOS, Windows và Linux, tải từ trang chủ hoặc GitHub Releases. Với Linux, hệ điều hành cần là Ubuntu 22.04 trở lên.
Có cần GPU không?
README không nêu yêu cầu GPU hay cấu hình phần cứng. Nếu bạn nối với mô hình chạy cục bộ thì nhu cầu phần cứng phụ thuộc vào chính mô hình đó.
Dữ liệu của tôi có an toàn không?
README cho biết tài liệu và ghi chú lưu dưới dạng file thường trong thư mục trên máy, không dùng cơ sở dữ liệu riêng, và ngữ cảnh với Agent giữ cục bộ. Nếu bạn bật đồng bộ S3 hoặc dùng dịch vụ bên ngoài thì dữ liệu sẽ đi theo cấu hình đó, nên hãy cân nhắc.
Agentero khác gì Zotero?
Tác giả nói họ không muốn thay Zotero. Agentero tập trung vào việc đưa tài liệu, ghi chú và AI Agent vào cùng một chỗ, và trích công thức, bảng sang Markdown/LaTeX cho AI đọc. Bạn có thể nhập cả thư viện Zotero vào và xuất BibTeX/BibLaTeX.
Dùng được với Claude, ChatGPT không?
Agentero nối với các Agent chạy trên máy như Claude Code, OpenCode, Codex hoặc mô hình cục bộ qua ACP. Nó cũng chạy như MCP server để ChatGPT Web và Claude Desktop truy vấn kho của bạn. README chưa ghi từng bước cấu hình.
Có dùng từ dòng lệnh được không?
Có. README nói có CLI chạy không cần giao diện, cài bằng Homebrew với brew install agentero. Chạy agentero --help để xem các lệnh và tham số.


