Dựng AI agent bằng thư mục— không cần viết code.
Mỗi agent chỉ là một thư mục markdown. Mọi việc nặng để cho LLM làm; một công cụ dòng lệnh nhỏ (~400 dòng) lo phần điều phối. Không bộ máy cồng kềnh, không database, và quan trọng nhất: không bị khóa vào một hãng AI nào — cùng một agent chạy được trên Claude, Codex hay Gemini, ở máy bạn hay trên server.
Tại sao làm ngược
Đa số framework bán cho bạn một cỗ máy. SCROLL chỉ đưa một quy ước.
Các framework agent nặng bắt bạn kéo theo cả một runtime (graph, scheduler, vector DB) rồi cột bạn vào một hãng model. SCROLL đi đường ngược lại — và đó cũng là hướng cả ngành đang ngả về trong 2026.
| Framework nặng | SCROLL | |
|---|---|---|
| Một agent là gì | một object trong code | một thư mục markdown |
| Dữ liệu chạy nằm đâu | trong database / session | ngay trên file + git |
| Ai điều phối | runtime của framework | một sơ đồ việc khai báo sẵn, chạy theo luật cố định |
| Phụ thuộc hãng | cột chặt vào một hãng | không cột ai — viết một lần, chạy mọi nơi |
| Cả framework | một cây thư viện | một quy ước + một CLI ~400 dòng |
Vì sao là thư mục
Sao phải tách ra nhiều file — viết đại một prompt không xong à?
Hỏi đúng. Thật ra một agent SCROLL cùng dạng với sub-agent của Claude thôi: markdown + vài dòng khai báo ở đầu. Tách thành IDENTITY · SOUL · TOOLS · hard-rules chỉ để đổi lấy ba thứ mà một file gộp không cho được:
🔌 Chạy được khắp nơi
Một sub-agent thường chỉ chạy trong Claude Code. Khi tách phần máy đọc được (model, quyền, nền tảng) ra khỏi phần văn mô tả tính cách, ta mới đổ được cùng một agent sang Cowork, Codex, Gemini, A2A — khỏi viết lại.
🔍 Soát được, chấm được
Luật cứng để riêng một file (dùng chung được giữa nhiều agent), bài kiểm tra để trong evals/ — nhờ vậy mới có cái để máy soát (scroll audit) và chấm điểm (scroll eval). Gộp một cục thì chịu.
🧰 Nối tool theo từng nền tảng
Khai "cần tìm web" ở mức ý niệm, còn nối vào tool thật nào thì tùy nền tảng. Một prompt cứng không làm được điều đó.
Cách nó chạy
Bốn bước, từ thư mục rỗng đến agent chạy thật.
Không có gì phải "đấu dây". Bạn tạo thư mục, viết tính cách bằng lời thường, rồi build một lần là ra mọi nền tảng.
# vòng chạy của một quy trình nhiều bước Thức dậy → nạp ngữ cảnh (đã cache) → chọn việc sẵn sàng → giao cho agent → ghi kết quả + checkpoint (git) → kiểm ngân sách / cổng duyệt → ngủ, lặp lại Crash giữa chừng? Đọc lại thư mục là chạy tiếp.
🧩 Mọi thứ là file
Không database, không session. Mỗi lần chạy là một thư mục; checkpoint là một commit git; máy hỏng thì đọc lại thư mục là tiếp tục được.
Cài đặt
Cài trong 2 phút.
Cần Node ≥ 20. Không kéo theo thư viện nào khác.
# Cách 1 — cài thẳng từ GitHub (repo công khai, chạy được ngay) npm i -g github:LeHungViet/scroll # Cách 2 — tải bản .tgz về cài (không cần tài khoản nào) npm i -g ./agentpro-scroll-0.6.0.tgz # Cách 3 — khi đã publish lên npm: npm i -g @agentpro/scroll # Thử ngay scroll new researcher scroll check researcher scroll audit scroll run researcher --task "Tóm tắt chủ đề X thành một kết luận ngắn"
Xong rồi thì sao?
Bạn có một thư mục agents/researcher/ đúng chuẩn, một báo cáo soát .scroll/audit.json, và một agent vừa chạy thật với log từng bước.
Cùng một thư mục đó, scroll build đổ ra được prompt cho Cowork, Codex, Gemini, hay A2A card — không phải viết lại lần nào.
Các lệnh
Mỗi lệnh làm một việc rõ ràng.
Cả framework gói gọn trong một CLI mỏng. Đây là việc của từng lệnh:
| scroll new <tên> | Dựng sẵn một thư mục agent đúng chuẩn để bạn điền vào — khỏi nhớ cấu trúc. |
| scroll check <tên> | Soát cấu trúc agent (khai báo hợp lệ, đủ file). Chạy ở pre-commit / CI. |
| scroll audit | Soát sâu mức tuân thủ: bắt prompt lạc trong code, model viết cứng, hạ tầng cấm, agent thiếu bài kiểm tra — rồi ghi báo cáo gắn-hash. |
| scroll build <tên> | Đổ một agent ra mọi nền tảng: Cowork · Codex · Gemini · Claude sub-agent · A2A card. |
| scroll run --work WORK.md | Chạy một quy trình nhiều agent thật. (Việc đơn: scroll run <agent> --task "…".) |
| scroll cost "<việc>" | Ước lượng token nếu làm bằng 1 agent vs nhiều agent — để quyết trước khi chạy. |
| scroll registry | Quét tất cả agent thành một bảng tổng quan (model, tool, nền tảng). |
Ví dụ nhiều agent
Những quy trình bạn dựng được ngay.
Một quy trình là một file WORK.md: mỗi việc ghi rõ ai làm, chờ việc nào xong mới chạy. Một "người điều phối" duy nhất giữ file này — nhờ vậy không có cảnh các agent đẩy việc qua lại loạn xạ.
📊 Memo quyết định
Một agent nghiên cứu thị trường, một agent đọc tài chính (chạy song song), người điều phối gộp lại thành một bản memo go/no-go.
🛠️ Tổ review code
Một agent đọc thay đổi, một agent chạy test; người điều phối bắt lỗi format/sai sót và yêu cầu sửa trước khi merge.
📚 Nghiên cứu dài
Sáu bước nối nhau (tìm → lên kế hoạch → làm → kiểm → sửa → báo cáo). Dừng giữa chừng vẫn chạy tiếp được từ checkpoint.
# WORK.md — ví dụ "memo quyết định" (rút gọn) controller: lead [việc] id: nghien-cuu-thi-truong owner: researcher parallel: true objective: Tóm tắt quy mô, tăng trưởng, đối thủ chính. [việc] id: doc-tai-chinh owner: analyst parallel: true objective: Tóm tắt đơn vị kinh tế và rủi ro chi phí. [việc] id: tong-hop owner: lead blockedBy: [nghien-cuu-thi-truong, doc-tai-chinh] objective: Gộp thành memo go/no-go. final: true
Kiểm soát agent
Làm sao chắc con agent thật sự làm theo chuẩn — chứ không nói suông?
Khi bạn để Claude Code / Cursor / Cowork tự viết agent, chúng hay tùy biến, hay bịa, hay nói "làm theo SCROLL rồi" mà thật ra không. SCROLL không tin lời — nó bắt máy kiểm, qua nhiều lớp:
🏗️ Đúng ngay từ đầu
scroll new dựng sẵn bộ khung chuẩn; trình soạn thảo gạch lỗi khai báo khi gõ; scroll check chạy ở CI; scroll build từ chối agent hỏng.
🤖 Dạy agent tự làm đúng
Một file AGENTS.md đi kèm dạy luật ngay trong repo — coding agent đọc và tự làm đúng, khỏi cần bạn nhắc.
Định vị
Không phải đối thủ của các SDK — nó đứng TRÊN chúng.
Claude Agent SDK, OpenAI Agents SDK, Google ADK đều là runtime cột vào một hãng. SCROLL là một quy ước trung lập, "đổ xuống" được chúng — nên agent của bạn không làm con tin của hãng nào.
| Khía cạnh | SDK của các hãng | SCROLL |
|---|---|---|
| Bản chất | một cỗ máy (code/thư viện) | một quy ước + CLI mỏng, đứng trên |
| Agent là | code / object của framework | văn markdown trong thư mục |
| Phụ thuộc hãng | cột vào một hãng | không cột ai — viết một lần, chạy mọi nơi |
| Nó đóng vai | điểm đến (cột chân bạn) | một trạm trung chuyển (cho bạn tự do đi) |
Tiết kiệm token
Rẻ ngay từ thiết kế — kể cả khi chạy qua CLI.
Cái rẻ của SCROLL đến từ cách sắp xếp ngữ cảnh và việc dùng file, không phải từ một vector store nào. Một loạt đòn bẩy, phần lớn áp dụng được dù bạn gọi model qua API hay qua CLI:
⚡ Né hẳn lần gọi model
Việc thuần cơ học (gộp, định dạng) chạy bằng code, tốn 0 token — đòn mạnh nhất, vì né được một lần gọi là né luôn cả phần "lời dẫn nền" nặng của model.
♻️ Tái dùng phần ngữ cảnh cố định
Phần đầu (định nghĩa agent) xếp ổn định để được cache; đọc lại từ cache chỉ tính ~0.1× giá.
✂️ Output gọn ở bước phụ
Chữ in ra bị tính ~5× giá chữ nhập. Nên bước phụ trả gọn, chỉ bước tổng hợp mới viết đầy đủ.
🎯 Dùng đúng model
Model rẻ cho việc phụ, model mạnh cho bước tổng hợp; cắt bớt phần dư trước khi chuyền sang bước sau.
Trạng thái — nói thật
Chứng minh ở chỗ quan trọng; thành thật về phần còn lại.
Một lần chạy A/B đầy đủ (3 lần lặp) đạt 26/26 bài kiểm khách quan: token, tốc độ, tuân thủ, không tụt chất lượng, dừng-rồi-chạy-tiếp, duyệt việc rủi ro, di động không lệch, và cổng chi phí. Độ tin được làm bằng kỹ thuật — giới hạn cứng, checkpoint, kiểm trước khi báo xong — chứ không phải cầu may.
Đã chạy được
Đang làm tiếp
Bằng chứng từ ngành
Không phải cảm tính — đây là hướng ngành đang đi.
Các lựa chọn của SCROLL trùng với điều mà những tiếng nói uy tín và số liệu thực tế đã chỉ ra. Đây là nhận định về cách làm (có nguồn, bấm xem được) — không phải họ quảng cáo cho SCROLL.
"Những bản triển khai thành công nhất KHÔNG dùng framework phức tạp… họ dựng bằng các mảnh đơn giản, ghép được với nhau."
Bầy nhiều agent dễ vỡ vì chia sẻ ngữ cảnh kém; cách chạy được là nhiều agent cùng góp, nhưng khâu ghi giữ một mối.
Hơn 60.000 dự án dùng AGENTS.md — "agent là markdown" nay đã thành chuẩn mở dưới Linux Foundation.