Prime Agent

1. Prime Agent là gì?

Prime Agent là một "trợ lý lập trình" chạy trong cửa sổ dòng lệnh (Terminal). Bạn mở nó trong một thư mục dự án, gõ yêu cầu bằng lời, và nó tự đọc file, chạy lệnh, sửa code thay bạn. Điểm khác so với các trợ lý cùng loại là nó được thiết kế cho việc chạy lâu: phiên làm việc tiếp tục chạy ngầm khi bạn đóng Terminal, nó có thể tự tạo các "trợ lý con" làm việc song song, và có lệnh /refine để ghi lại kinh nghiệm cho những lần sau.

Nói thẳng: đây là công cụ dành cho lập trình viên và người làm nghiên cứu AI. Nó không có giao diện bấm chuột, không có file cài .exe. Mã nguồn mở theo giấy phép MIT và tải về miễn phí, nhưng để nó hoạt động bạn phải đăng nhập một gói thuê bao hoặc một khóa API của nhà cung cấp mô hình AI (phần này có thể mất tiền, tùy nhà cung cấp bạn chọn).

Hợp với bạn nếu:

• Bạn đã quen dùng Terminal trên macOS hoặc Linux.
• Bạn có dự án code và muốn giao cho AI những việc dài hơi, chạy nhiều giờ.
• Bạn đã có sẵn gói thuê bao hoặc khóa API của một nhà cung cấp mô hình AI.

Chưa hợp nếu:

• Bạn chưa từng lập trình và chỉ muốn một ứng dụng chat để hỏi đáp.
• Bạn chỉ có máy Windows và không muốn cài thêm môi trường Linux.
• Bạn cần một công cụ chạy trong "hộp cát" an toàn: Prime Agent chạy lệnh bằng chính quyền của tài khoản bạn trên máy.

Lưu ý: Tài liệu chính thức cảnh báo rõ: Prime Agent chạy code Python và lệnh do mô hình AI tạo ra với quyền của bạn, và nó không phải là một hộp cát bảo mật. Chỉ dùng trên dự án bạn tin tưởng và có bản sao lưu.

2. Cần chuẩn bị gì?

Máy tính và hệ điều hành

Trình cài đặt chính thức chỉ nhận hai hệ điều hành:

• macOS 13 trở lên, chip Apple Silicon hoặc Intel.
• Linux 64-bit (x64 hoặc ARM64), kể cả các bản dùng musl như Alpine.

Trang Releases của dự án không có bản cho Windows. Nếu bạn dùng Windows, bạn cần một môi trường Linux trên máy (ví dụ WSL, tính năng chạy Linux bên trong Windows của Microsoft: https://learn.microsoft.com/windows/wsl/install). Dự án không viết hướng dẫn riêng cho WSL, nên hãy coi đây là cách dùng chưa được dự án xác nhận.

Phần mềm cần có

• curl: công cụ tải file bằng dòng lệnh. macOS và hầu hết Linux đã có sẵn.
• Python và uv: bạn không cần tự cài. Trong lúc cài, trình cài đặt sẽ hỏi có muốn chuẩn bị môi trường Python không; nếu đồng ý, nó tự cài uv (công cụ quản lý Python), Python 3.11 và phần chạy nền của Prime Agent.
• Node.js (nền tảng chạy JavaScript): chỉ cần khi máy bạn không có bản biên dịch sẵn phù hợp. Khi đó trình cài đặt chuyển sang cách cài qua Node.js và yêu cầu bản 20.6.0 trở lên. Tải tại https://nodejs.org nếu cần.
• Git (công cụ quản lý phiên bản code): không bắt buộc để cài, nhưng rất nên có, vì bạn cần một cách quay lại nếu AI sửa sai. Tải tại https://git-scm.com.

Tài khoản

Lần chạy đầu tiên bạn phải dùng lệnh /login để chọn một nhà cung cấp: hoặc một gói thuê bao, hoặc một khóa API (chuỗi ký tự bí mật dùng để gọi mô hình AI). Chi phí do nhà cung cấp đó tính; README không công bố bảng giá, nên hãy xem giá trên trang của nhà cung cấp bạn chọn.

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

Prime Agent chỉ có một cách cài chính thức: chạy một lệnh trong Terminal. Không có bản web hay file cài bấm đúp.

Bước 1: Chạy lệnh cài đặt

Mở Terminal (trên Windows là cửa sổ WSL) và dán lệnh sau:

curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh

Lệnh này tải trình cài đặt từ trang của Prime Intellect rồi chạy nó. Trình cài đặt tự nhận ra máy bạn là macOS hay Linux, chip gì, rồi tải đúng gói.

Thấy gì là đúng: màn hình hiện dòng "Installing Prime Agent" và tiến trình tải.

Bước 2: Trả lời câu hỏi về môi trường Python

Trong lúc cài, trình cài đặt hỏi:

Prepare Python runtime now?

Kèm giải thích rằng nó sẽ cài uv, Python 3.11 và phần chạy nền của Prime Agent. Nhấn Enter (mặc định là đồng ý) để chuẩn bị luôn. Nếu bạn từ chối, phần này sẽ được chuẩn bị ở lần đầu Prime Agent cần dùng Python, nên lần chạy đầu sẽ chậm hơn.

Bước 3: Kiểm tra kết quả

Cài xong, màn hình báo:

Prime Agent installed
Run it with: prime-agent

Trình cài đặt đặt chương trình vào thư mục ~/.local/share/prime-agent và tạo lệnh prime-agent trong ~/.local/bin. Hãy đóng Terminal, mở lại, rồi gõ:

prime-agent --version

Thấy gì là đúng: một số phiên bản hiện ra (bản mới nhất lúc viết bài là 0.9.8, phát hành ngày 29/9/2026). Nếu báo không tìm thấy lệnh, xem mục 5.

4. Dùng lần đầu

Bước 1: Tạo một thư mục thử nghiệm

Đừng thử ngay trên dự án quan trọng. Tài liệu chính thức khuyên dùng một bản sao có thể bỏ đi. Ví dụ tạo một thư mục trống:

mkdir ~/thu-prime-agent
cd ~/thu-prime-agent

Prime Agent làm việc trong đúng thư mục bạn đang đứng, và có quyền chạy lệnh, sửa file ở đó.

Bước 2: Khởi động và đăng nhập

prime-agent

Giao diện dạng chữ hiện ra trong Terminal. Gõ:

/login

Một danh sách nhà cung cấp hiện ra, gồm loại đăng nhập bằng gói thuê bao và loại dùng khóa API. Chọn loại bạn có và làm theo hướng dẫn trên màn hình.

Bước 3: Giao một việc nhỏ

Gõ một yêu cầu đơn giản, ví dụ nhờ nó tạo một file Python in ra bảng cửu chương rồi chạy thử. Bạn sẽ thấy nó viết code, chạy, và báo kết quả. Sau đó mở thư mục ra kiểm tra file nó vừa tạo.

Bước 4: Biết các lệnh quản lý phiên

Vì phiên làm việc chạy ngầm, bạn nên biết các lệnh sau (gõ ở Terminal, bên ngoài giao diện Prime Agent):

prime-agent agents
prime-agent attach ten-phien
prime-agent --resume
prime-agent status
prime-agent shutdown

• agents: xem các phiên đang chạy, đang nghỉ và đã lưu.
• attach: nối lại vào một phiên đang chạy (thay ten-phien bằng tên phiên thật).
• --resume: duyệt và mở lại phiên cũ.
• status: xem tình trạng dịch vụ chạy nền.
• shutdown: dừng toàn bộ phiên và dịch vụ nền.

Bên trong giao diện còn có các lệnh như /goal (giữ một mục tiêu qua nhiều lượt), /autonomous (cho chạy tự động trong giới hạn lượt, token và thời gian bạn đặt) và /refine (rút kinh nghiệm từ phiên vừa rồi).

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
Gõ prime-agent báo "command not found"	Thư mục ~/.local/bin chưa nằm trong PATH (danh sách nơi máy tìm lệnh)	Đóng và mở lại Terminal. Nếu vẫn lỗi, thêm ~/.local/bin vào PATH theo gợi ý trình cài đặt in ra
Trình cài đặt báo "Node.js 20.6.0 or newer is required"	Máy không có bản biên dịch sẵn phù hợp nên chuyển sang cách cài qua Node.js, mà Node.js thiếu hoặc quá cũ	Đồng ý để trình cài đặt tự cài Node.js, hoặc cài bản mới từ https://nodejs.org rồi chạy lại
Báo "refusing to replace existing command"	Đã có sẵn một lệnh tên prime-agent ở ~/.local/bin không phải do trình cài đặt này tạo	Xóa hoặc đổi tên lệnh cũ, hoặc đặt biến PRIME_AGENT_BIN_DIR sang thư mục khác rồi cài lại
Báo "installation is locked"	Một lần cài khác đang chạy hoặc bị ngắt giữa chừng	Chắc chắn không còn trình cài đặt nào chạy, rồi xóa file .install-lock trong thư mục cài như thông báo chỉ dẫn
Báo "Python preparation failed"	Tải uv hoặc Python thất bại, thường do mạng	Không cần cài lại: Prime Agent sẽ thử chuẩn bị lại ở lần đầu dùng Python
Phiên bị treo, dịch vụ nền không phản hồi	Dịch vụ chạy nền gặp sự cố	Chạy lệnh kiểm tra và sửa bên dưới

Lệnh kiểm tra và sửa dịch vụ nền:

prime-agent doctor
prime-agent doctor --fix

Trên Alpine Linux, nếu bản biên dịch sẵn báo thiếu thư viện C++, trình cài đặt gợi ý chuyển sang bản Node.js bằng cách đặt biến PRIME_AGENT_INSTALL_METHOD=node trước khi chạy lại lệnh cài.

Gặp lỗi khác, dự án nhận báo lỗi qua mục Discussions: https://github.com/PrimeIntellect-ai/prime-agent/discussions

6. Gỡ cài đặt / cập nhật

Cập nhật

prime-agent update

Thêm --force nếu muốn ép cập nhật. Bạn cũng có thể chạy lại lệnh cài ở mục 3. Nếu bản mới có vấn đề, trình cài đặt có chế độ quay về bản trước:

curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh -s -- --rollback

Gỡ cài đặt

README không có lệnh gỡ chính thức. Dựa trên những gì trình cài đặt tạo ra, bạn gỡ thủ công như sau. Trước hết dừng mọi phiên:

prime-agent shutdown

Sau đó xóa lệnh và thư mục chương trình:

rm ~/.local/bin/prime-agent
rm -rf ~/.local/share/prime-agent

Lưu ý: Hai đường dẫn trên là vị trí mặc định. Nếu lúc cài bạn đã đổi bằng biến PRIME_AGENT_INSTALL_DIR hoặc PRIME_AGENT_BIN_DIR, hãy xóa đúng nơi bạn đã chọn. Vị trí lưu dữ liệu phiên làm việc không được README nêu rõ, hãy hỏi tại mục Discussions nếu bạn cần xóa sạch.

7. Câu hỏi hay gặp

Có mất tiền không?

Bản thân Prime Agent miễn phí và mã nguồn mở (giấy phép MIT). Chi phí nằm ở mô hình AI: bạn cần một gói thuê bao hoặc khóa API của nhà cung cấp, và họ tính tiền theo cách của họ.

Có cần mạng không?

Có. Cần mạng để cài đặt và để gọi mô hình AI ở nhà cung cấp bạn đã đăng nhập.

Code của tôi có bị gửi đi đâu không?

Để làm việc, Prime Agent gửi nội dung cần thiết tới nhà cung cấp mô hình bạn chọn ở /login. Ngoài ra mã nguồn có một phần thống kê sử dụng; theo tài liệu của phần này, có thể tắt bằng biến môi trường DO_NOT_TRACK hoặc PRIME_AGENT_TELEMETRY. Chi tiết xem trong kho mã chính thức.

Dùng trên Windows được không?

Không có bản Windows. Trình cài đặt chỉ nhận macOS và Linux. Cách duy nhất là chạy trong một môi trường Linux như WSL, và cách này chưa được dự án viết hướng dẫn.

Đóng Terminal thì việc đang chạy có mất không?

Không. Phiên làm việc chạy nhờ một dịch vụ nền, nên vẫn tiếp tục khi Terminal ngắt kết nối. Dùng prime-agent agents để xem và prime-agent attach để nối lại.