mini-swe-agent: agent AI 100 dòng code sửa lỗi và viết code trên terminal — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
mini-swe-agent là một agent AI viết bằng Python, giao việc lập trình cho mô hình ngôn ngữ qua dòng lệnh `mini`. Nó chỉ dùng bash, phần lõi khoảng 100 dòng code, nên rất dễ đọc và dễ sửa. Cài bằng pip hoặc uvx, chỉ cần Python 3.10 trở lên, nên khá dễ với người mới.
mini-swe-agent là một agent AI lập trình viết bằng Python, chạy ngay trong terminal qua lệnh mini. Nó nhận một yêu cầu bằng chữ (ví dụ «viết cho mình một game sudoku»), rồi nhờ mô hình ngôn ngữ tự gõ lệnh bash để làm việc đó. Tác giả mô tả nó là «agent 100 dòng», vì phần lớp agent chính chỉ khoảng 100 dòng Python.
Repo này do nhóm ở Princeton và Stanford làm, chính là nhóm đứng sau SWE-bench và SWE-agent. Họ đặt câu hỏi: nếu agent đơn giản hơn 100 lần mà vẫn chạy gần như tốt như cũ thì sao? Theo README, câu trả lời là nó đạt hơn 74% trên bộ đánh giá SWE-bench verified. Hiện repo có khoảng 9573 sao và 1307 fork, giấy phép MIT.
Bạn nên đọc bài này nếu bạn là lập trình viên mới muốn một trợ lý code gọn nhẹ trên máy mình, hoặc người làm kỹ thuật muốn hiểu một agent hoạt động bên trong ra sao mà không phải đọc cả một monorepo khổng lồ. Điểm đáng giá nhất: không cấu hình rườm rà, không công cụ riêng, đọc một buổi chiều là hiểu hết.
SWE-agent/mini-swe-agent
Agent AI lập trình tối giản bằng Python: chỉ dùng bash, lõi khoảng 100 dòng, chạy ngay trên terminal và vẫn đạt trên 74% SWE-bench verified.
I.mini-swe-agent làm được gì
Dưới đây là những điểm chính, theo cách tác giả mô tả, kèm lợi ích thực tế cho bạn.
A.Chỉ dùng bash, không cần công cụ riêng
Agent này không có công cụ nào khác ngoài bash. Nó cũng không cần dùng giao diện tool-calling của mô hình. Nghĩa là gần như mô hình nào cũng chạy được. Muốn nó làm việc cụ thể như mở pull request? Bạn chỉ cần bảo mô hình tự tìm cách, không phải chờ ai viết thêm tính năng cho agent.
B.Lịch sử tuyến tính, dễ debug
Mỗi bước của agent chỉ nối thêm vào danh sách tin nhắn, vậy thôi. Cái agent đã làm (trajectory) và cái được gửi cho mô hình là một. Khi agent làm sai, bạn nhìn lại là biết mô hình đã được «dặn» những gì. README nói thiết kế này cũng tốt cho việc huấn luyện tinh chỉnh.
C.Mỗi lệnh chạy độc lập bằng subprocess.run
Agent không giữ một phiên shell sống lâu. Mỗi hành động là một lệnh riêng. Nhờ vậy, muốn chạy trong hộp cát (sandbox) thì chỉ cần thay subprocess.run bằng docker exec. README cho biết cách này giúp agent ổn định hơn và dễ mở rộng quy mô.
D.Chạy được ở nhiều môi trường
README liệt kê: môi trường local (chạy thẳng trên máy bạn), docker/podman, singularity/apptainer, bublewrap, contree và một số loại khác. Bạn có thể bắt đầu local cho nhanh, sau này chuyển sang container khi muốn an toàn hơn.
E.Tương thích nhiều mô hình
Nó hỗ trợ mọi mô hình qua litellm, openrouter, portkey và các lựa chọn khác, cùng các endpoint /completion và /response. Bạn không bị khoá vào một nhà cung cấp.
F.Dùng được từ dòng lệnh, Python và chạy hàng loạt
README giới thiệu giao diện CLI (mini), chế độ chạy hàng loạt (batch inference), trình duyệt trajectory để xem lại các lần chạy, và Python bindings để gọi agent từ code của bạn.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Python 3.10 trở lên. Đây là yêu cầu trong
pyproject.toml. - pip để cài gói. Nếu muốn thử nhanh không cài vào máy, README dùng
uvhoặcpipx, và hai công cụ này cũng cài được bằng pip. - Một mô hình ngôn ngữ để agent gọi. README nói agent hỗ trợ mô hình qua litellm, openrouter, portkey… Nhưng README chưa ghi cách khai báo API key hay tên mô hình. Phần này bạn xem ở trang Quick start và trang Global configuration trong tài liệu của dự án.
- Nếu muốn chạy trong sandbox: docker, podman hoặc công cụ tương ứng. Đây là tuỳ chọn.
README không nói gì về hệ điều hành cụ thể, cũng không yêu cầu GPU. Vì agent chạy lệnh bash, người dùng Windows nên kiểm tra kỹ phần hướng dẫn trong tài liệu trước khi dùng môi trường local.
Khi chạy ở môi trường local, agent sẽ gõ lệnh thật trên máy bạn. Hãy thử trong một thư mục thí nghiệm, không phải thư mục chứa dữ liệu quan trọng. Gọi mô hình qua API thường tính phí theo lượng dùng, nên theo dõi chi phí ở nhà cung cấp mô hình bạn chọn.
III.Cài đặt từng bước
- Mở terminalDùng terminal có Python 3.10 trở lên và pip
- Chọn cách càiThử nhanh (uvx/pipx), cài vào môi trường hiện tại, hoặc cài từ mã nguồn
- Chạy lệnh càiChép đúng lệnh của cách bạn chọn
- Chạy miniGõ mini để mở giao diện dòng lệnh
- Cấu hình mô hìnhXem tài liệu Quick start để khai báo mô hình và key
A.Mở terminal và kiểm tra Python
Trên Windows, bạn mở PowerShell hoặc Terminal. Trên macOS/Linux, mở Terminal. Kiểm tra Python trước, vì repo yêu cầu bản 3.10 trở lên:
python --versionNếu ra số thấp hơn 3.10, bạn cần cài Python mới hơn trước khi làm tiếp. Người mới hay vấp ở đây: máy có nhiều bản Python, lệnh python có thể trỏ nhầm bản cũ.
B.Cách 1: thử nhanh, không cài vào môi trường chính
Cách này dành cho bạn chỉ muốn xem thử CLI. Gói được cài trong một môi trường ảo ẩn danh, không làm bẩn máy. README ghi hai lựa chọn tương đương:
pip install uv && uvx mini-swe-agent
# or
pip install pipx && pipx ensurepath && pipx run mini-swe-agentDòng đầu cài uv rồi chạy gói mini-swe-agent bằng uvx. Dòng sau dùng pipx để làm điều tương tự. Chỉ cần chọn một trong hai. Với pipx, lệnh pipx ensurepath thêm đường dẫn cần thiết, có thể bạn phải mở lại terminal sau đó.
C.Cách 2: cài vào môi trường hiện tại
Cách này cài cả CLI lẫn Python bindings, hợp nếu bạn định gọi agent từ code Python của mình:
pip install mini-swe-agent
mini # run the CLILệnh đầu cài gói tên mini-swe-agent. Lệnh thứ hai, mini, mở giao diện dòng lệnh. Phần sau dấu # chỉ là ghi chú, bạn không cần gõ.
D.Cách 3: cài từ mã nguồn (dành cho người muốn sửa code)
Cách này cần có git. Bạn tải repo về rồi cài ở chế độ chỉnh sửa (-e), nên sửa file nào là có hiệu lực ngay:
git clone https://github.com/SWE-agent/mini-swe-agent.git
cd mini-swe-agent && pip install -e .
mini # run the CLILệnh cd đưa bạn vào thư mục vừa tải. Hãy chạy pip install -e . ngay trong thư mục đó, nếu không pip sẽ báo không tìm thấy dự án.
E.Khai báo mô hình và key
README chưa ghi cách đặt API key hay chọn mô hình. Bạn xem trang Quick start, Global configuration và Yaml configuration files trong tài liệu của dự án (README có liệt kê các trang này). Trong repo cũng có thư mục docs/ chứa cùng nội dung. Mình không đoán tên biến môi trường để tránh hướng dẫn sai.
IV.Kiểm tra đã chạy được chưa
Theo README, dấu hiệu thành công đơn giản nhất là gõ lệnh sau và thấy giao diện CLI của agent hiện ra:
miniNếu terminal báo không tìm thấy lệnh mini, gói chưa được cài vào đúng môi trường (xem phần lỗi bên dưới). Nếu giao diện mở lên nhưng khi giao việc thì báo lỗi gọi mô hình, nghĩa là bước khai báo mô hình/key chưa xong. Đó là một vấn đề khác, không phải lỗi cài đặt.
Cách thử thứ hai là dùng Python bindings. README đưa ví dụ ngắn này (bạn cần điền model_name bằng tên mô hình mình dùng):
agent = DefaultAgent(
LitellmModel(model_name=...),
LocalEnvironment(),
)
agent.run("Write a sudoku game")Đoạn này tạo agent với mô hình qua litellm và môi trường local, rồi giao việc «viết game sudoku». README không ghi các dòng import, nên bạn xem file ví dụ hello_world.py trong thư mục src/minisweagent/run/ để lấy đúng cách import.
V.Dùng vào việc thật
README mô tả ba kiểu dùng chính: CLI, chạy hàng loạt và Python bindings. Dưới đây là các tình huống bám theo đó.
Đừng viết thêm công cụ cho agent — hãy bảo mô hình tự dùng shell cho tới nơi.
Ông T
A.Lập trình viên mới nhờ viết thử một chương trình nhỏ
Bạn đang học Python và muốn có một game đơn giản để xem code mẫu. Bạn tạo một thư mục thí nghiệm, mở terminal trong đó, gõ mini rồi mô tả yêu cầu bằng chữ, ví dụ: «Viết một game sudoku bằng Python». Agent sẽ gọi mô hình, mô hình đề xuất các lệnh bash, agent chạy từng lệnh và ghi lại kết quả. Cuối cùng bạn có các file code trong thư mục đó để đọc và học. Ví dụ «Write a sudoku game» cũng chính là ví dụ trong README.
B.Dev nhờ xử lý một issue trong dự án có sẵn
Mô tả của tác giả nói rõ agent này «giải GitHub issue». Bạn mở terminal trong thư mục dự án, gõ mini, rồi dán nội dung issue kèm yêu cầu «tìm nguyên nhân và sửa». Agent chạy lệnh để đọc file, sửa và thử lại. Kết quả là một bản sửa nằm ngay trong thư mục của bạn. Bạn nên xem lại thay đổi trước khi dùng. Muốn nó mở pull request, README gợi ý cứ bảo mô hình tự làm bằng shell.
C.Nhà nghiên cứu so sánh mô hình bằng cùng một agent
Nếu bạn muốn biết mô hình nào làm tốt hơn trên cùng một bộ bài, README nói mini thích hợp làm hệ thống chuẩn (baseline). Vì agent đơn giản và mô hình là trung tâm, bạn đổi tên mô hình rồi chạy lại, kết quả phản ánh mô hình nhiều hơn là phản ánh agent. Với số lượng lớn, bạn dùng chế độ chạy hàng loạt, và xem lại từng lần chạy bằng trình duyệt trajectory.
D.Chạy trong sandbox khi chưa tin tưởng việc agent làm
Bạn chưa muốn agent gõ lệnh thẳng lên máy mình. README cho biết agent hỗ trợ docker/podman và nhiều môi trường khác. Bạn đọc phần cấu hình trong tài liệu để chuyển môi trường từ local sang container. Kết quả là agent làm việc trong hộp cô lập, nếu có lỡ tay thì máy chính an toàn hơn. Lưu ý README chưa ghi lệnh cụ thể cho bước này trong phần đầu, bạn xem trang tài liệu tương ứng.
VI.Lỗi hay gặp và cách xử lý
A.Gõ mini báo không tìm thấy lệnh
Thường do gói được cài vào một môi trường Python khác với môi trường terminal đang dùng, hoặc cài bằng pipx mà chưa mở lại terminal. Hãy chạy lại pipx ensurepath rồi mở terminal mới. Hoặc dùng cách uvx mini-swe-agent để khỏi lo đường dẫn.
B.Phiên bản Python quá cũ
Repo yêu cầu Python từ 3.10. Nếu pip báo không có bản phù hợp, kiểm tra lại bằng python --version, cài bản mới hơn và chạy lại lệnh cài.
C.Mở được mini nhưng gọi mô hình bị lỗi
Trường hợp rất dễ gặp với loại công cụ này: chưa khai báo mô hình hoặc API key, hoặc key sai. README chưa ghi chi tiết, bạn xem trang Quick start và Global configuration trong tài liệu. Đừng dán key vào file rồi đẩy lên GitHub công khai.
D.Đọc nhầm tài liệu của phiên bản cũ
README cảnh báo đây là mini-swe-agent v2 và có hướng dẫn chuyển đổi từ v1. Nếu bạn làm theo bài viết hay video cũ rồi gặp lệnh không khớp, hãy kiểm tra xem tài liệu đó viết cho v1 hay v2.
E.Agent chạy lệnh không như bạn mong muốn
Vì agent dùng bash thật, nó có thể sửa hoặc xoá file trong thư mục làm việc. Hãy làm trong thư mục thử nghiệm, có sao lưu hoặc dùng git để quay lại được. Cần an toàn hơn thì dùng môi trường container thay vì local.
VII.Có nên dùng không
Điểm mạnh. Rất gọn và dễ hiểu: lõi khoảng 100 dòng, chỉ dùng bash, lịch sử tuyến tính nên dễ debug. Tương thích nhiều mô hình, nhiều môi trường chạy. README nói nó đạt hơn 74% trên SWE-bench verified và khởi động nhanh hơn Claude Code. Giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây.
Giới hạn. Đây là công cụ dòng lệnh, không có giao diện đồ hoạ cầu kỳ, nên người chưa quen terminal sẽ cần thời gian làm quen. Bạn phải tự lo mô hình và key. Môi trường local không cô lập, nên cần cẩn thận. Chất lượng kết quả phụ thuộc nhiều vào mô hình bạn chọn.
Khi nào chọn cách khác. README gợi ý: nếu bạn muốn thử nghiệm nhiều bộ công cụ riêng với giao diện riêng, hoặc thử các cách xử lý lịch sử khác nhau, hãy dùng SWE-agent. Còn lại, tác giả coi mini-swe-agent là lựa chọn mặc định: cần một công cụ dòng lệnh chạy cục bộ, luồng điều khiển đơn giản, sandbox và đánh giá nhanh gọn, hoặc đang tinh chỉnh/RL mà không muốn bị gắn vào một agent cụ thể.
Câu hỏi thường gặp
mini-swe-agent có miễn phí không?
Repo dùng giấy phép MIT nên bạn dùng và sửa mã nguồn tự do. Tuy nhiên agent cần gọi một mô hình ngôn ngữ, và README không nói chi phí này. Phí phụ thuộc nhà cung cấp mô hình bạn chọn.
Cần cài những gì để chạy mini-swe-agent?
Theo pyproject.toml, bạn cần Python 3.10 trở lên và pip. README có ba cách cài: dùng uvx hoặc pipx để thử nhanh, `pip install mini-swe-agent`, hoặc tải mã nguồn rồi `pip install -e .`. Sau đó gõ `mini` để mở CLI.
Có cần GPU không?
README không yêu cầu GPU. Agent gọi mô hình qua các dịch vụ như litellm, openrouter, portkey. Tư liệu không nói gì về việc chạy mô hình cục bộ trên máy bạn.
Chạy được trên Windows không?
README không nói rõ về hệ điều hành. Agent hoạt động bằng cách chạy lệnh bash, nên bạn nên xem tài liệu của dự án về môi trường chạy trước khi dùng trên Windows. Hiện chưa có thông tin cụ thể hơn trong tư liệu.
Dữ liệu và máy của tôi có an toàn không?
Ở môi trường local, agent chạy lệnh thật trên máy bạn nên cần thận trọng, chỉ làm trong thư mục thử nghiệm. README nói agent hỗ trợ docker/podman, singularity/apptainer, bublewrap, contree để chạy trong môi trường cô lập. Tư liệu chưa nói về chính sách dữ liệu gửi cho nhà cung cấp mô hình.
mini-swe-agent khác SWE-agent ở điểm nào?
Theo README, mini-swe-agent chỉ dùng bash, lịch sử tuyến tính và chạy mỗi lệnh độc lập bằng subprocess.run, nên đơn giản hơn nhiều. SWE-agent phù hợp khi bạn muốn thử nhiều bộ công cụ riêng hoặc nhiều cách xử lý lịch sử. Tác giả coi mini-swe-agent là lựa chọn mặc định.
Tôi dùng được với mô hình nào?
README nói agent hỗ trợ mọi mô hình qua litellm, openrouter, portkey và các lựa chọn khác, kể cả endpoint /completion và /response. Cách khai báo tên mô hình và key nằm ở tài liệu Quick start, README chưa ghi chi tiết.


