Bỏ qua tới nội dung
Ông T.vn

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

10 phút đọcCập nhật
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.

Agent

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.

★ 9.6kPythonMIT
Xem repo trên GitHub

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 uv hoặc pipx, 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

  1. Mở terminalDùng terminal có Python 3.10 trở lên và pip
  2. 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
  3. Chạy lệnh càiChép đúng lệnh của cách bạn chọn
  4. Chạy miniGõ mini để mở giao diện dòng lệnh
  5. 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:

Terminal
python --version

Nế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:

Terminal
pip install uv && uvx mini-swe-agent
# or
pip install pipx && pipx ensurepath && pipx run mini-swe-agent

Dò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:

Terminal
pip install mini-swe-agent
mini  # run the CLI

Lệ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:

Terminal
git clone https://github.com/SWE-agent/mini-swe-agent.git
cd mini-swe-agent && pip install -e .
mini  # run the CLI

Lệ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:

Terminal
mini

Nế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):

Python
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ể.

4.5/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

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.

Chuyển nhanh tới mục

  1. I.mini-swe-agent làm được gì
    1. A.Chỉ dùng bash, không cần công cụ riêng
    2. B.Lịch sử tuyến tính, dễ debug
    3. C.Mỗi lệnh chạy độc lập bằng subprocess.run
    4. D.Chạy được ở nhiều môi trường
    5. E.Tương thích nhiều mô hình
    6. F.Dùng được từ dòng lệnh, Python và chạy hàng loạt
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Mở terminal và kiểm tra Python
    2. B.Cách 1: thử nhanh, không cài vào môi trường chính
    3. C.Cách 2: cài vào môi trường hiện tại
    4. D.Cách 3: cài từ mã nguồn (dành cho người muốn sửa code)
    5. E.Khai báo mô hình và key
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Lập trình viên mới nhờ viết thử một chương trình nhỏ
    2. B.Dev nhờ xử lý một issue trong dự án có sẵn
    3. C.Nhà nghiên cứu so sánh mô hình bằng cùng một agent
    4. D.Chạy trong sandbox khi chưa tin tưởng việc agent làm
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Gõ mini báo không tìm thấy lệnh
    2. B.Phiên bản Python quá cũ
    3. C.Mở được mini nhưng gọi mô hình bị lỗi
    4. D.Đọc nhầm tài liệu của phiên bản cũ
    5. E.Agent chạy lệnh không như bạn mong muốn
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.