Driver đánh giá AI agent — chạy bên ngoài, chấm điểm lai, cách ly thật.
Phát triển bởi Aerovfx · C++20 · macOS / Windows / Linux
AgentBenchmark là bộ đo năng lực agent do Aerovfx phát triển. Nó không sống bên trong agent: driver spawn agent như một subprocess độc lập, nói chuyện qua STDIO JSONL / JSON-RPC theo lượt, cho agent làm việc trong một workspace bị cách ly, rồi chấm kết quả bằng hai loại giám khảo — deterministic (test pass/fail, diff, hash artifact) và LLM-judge (rubric) — và xuất báo cáo máy đọc được.
Triết lý: mọi thứ mở rộng được đều là plugin (tham khảo cách làm của DeepSeek Harness / Cordis), và không hệ thống nào tự chấm chính mình — suite sinh đề, judge chấm, reporter xuất, ba vai trò tách bạch.
Là gì: một ứng dụng độc lập để đo và so sánh agent qua nhiều lần chạy. Không phải: plugin cài vào trong agent, không phải framework huấn luyện, không phải web service đa người dùng.
Cái đang được đo là một tiến trình lạ, có thể treo, có thể đẻ tiến trình con, có thể cố
ghi ra ngoài thư mục của nó. Driver vì thế cần điều khiển tiến trình ở mức hệ điều hành:
giết cả cây tiến trình khi hết giờ, đặt RLIMIT, bọc sandbox của OS, và không bao giờ
để lộ credential của chính nó sang tiến trình đang bị đo. Đó là công việc của C++ + một
lớp compat/ mỏng, không phải của một script.
| Vòng lặp agentic | nhiều turn, agent gọi tool → driver thực thi → nối kết quả vào lượt sau |
| Cách ly thật | sandbox OS (seatbelt trên macOS, bubblewrap trên Linux): chặn mạng + giới hạn ghi; RLIMIT CPU/RAM/file; Job Object trên Windows |
| An toàn bí mật | agent chỉ thấy env allowlist tối thiểu; API key của judge không bao giờ lọt sang agent, không qua argv, không qua temp file |
| Chấm lai | 7 judge deterministic + LLM-judge OpenAI-compatible, phân biệt rõ lỗi agent với lỗi judge |
| Tái lập được | reset workspace mỗi task, repeats → median, ghi git hash + config hash vào run_meta.json |
| Song song | --jobs N với result store thread-safe, báo cáo vẫn giữ nguyên thứ tự |
| Đa nền tảng | macOS arm64, Windows x64 (clang-cl), Linux x64 — một cây CMake, không #ifdef trong src/ |
| Suite | Đo cái gì | Task hiện có |
|---|---|---|
coding |
sửa bug / viết tính năng trong repo fixture (SWE-bench style) | 1 |
tooluse |
gọi tool đúng, kiểm side effect và output | 2 |
reasoning |
trả lời đúng (GAIA/MMLU style) | 1 |
planning |
tác vụ nhiều bước, chấm cả trajectory lẫn artifact | 1 |
safety |
thoát sandbox, prompt injection, từ chối, xử lý dữ liệu nhạy cảm | 3 |
cost |
token / độ trễ / chi phí (metric, không pass-fail) | — (metric đã thu, chưa thành suite) |
Dataset hiện là bộ mẫu để chứng minh đường chạy, chưa phải bộ đề đủ lớn để xếp hạng agent — xem Trạng thái.
| Dùng cho | Chạy | |
|---|---|---|
agentbench (CLI) |
tự động hoá, CI, người quen terminal | agentbench run --config … |
agentbench-gui |
người không rành kỹ thuật — chọn AI, chọn bài, bấm chạy | mở app, không cần gõ lệnh |
Cả hai chạy trên cùng một engine (ab::app::RunSession), nên kết quả và cách chấm
giống hệt nhau. Bản GUI hiển thị tiến trình theo thời gian thực, đồ thị điểm theo nhóm bài,
thời gian từng bài, và dịch mọi thông báo lỗi kỹ thuật sang tiếng Việt dễ hiểu.
GUI không được build mặc định (nó tải Dear ImGui + GLFW lúc configure):
cmake -S . -B build/gui -G Ninja -DCMAKE_BUILD_TYPE=Release -DAB_BUILD_GUI=ON && cmake --build build/guiTrên macOS lệnh trên sinh thẳng build/gui/AgentBenchmark.app — bundle tự chứa, đã ký
ad-hoc, kèm bộ đề trong Contents/Resources/datasets nên kéo sang máy khác vẫn chạy.
Đóng gói bản phát hành (ZIP cho CLI + DMG cho app):
sh scripts/package.shYêu cầu: CMake ≥ 3.20, Ninja, C++20 (Apple Clang / clang-cl + MSVC / g++);
libcurl ≥ 7.68 cho LLM-judge — dùng bản hệ thống nếu có (macOS SDK,
libcurl4-openssl-dev trên Linux), không có thì CMake tự tải bản ghim (mặc định trên
Windows; ép bằng -DAB_USE_SYSTEM_CURL=OFF); python3 tuỳ chọn cho mock judge server.
# preset khác: win-x64-release · linux-release
cmake --preset mac-arm64-release
cmake --build build/mac-arm64-release
ctest --test-dir build/mac-arm64-release --output-on-failure# liệt kê task
./build/mac-arm64-release/agentbench run --config datasets/run.json --list
# chạy toàn bộ suite với mock agent
./build/mac-arm64-release/agentbench run --config datasets/run.json
# một task, chạy song song 4 luồng
./build/mac-arm64-release/agentbench run --config datasets/run.json \
--task planning/multifile --jobs 4Kết quả nằm trong thư mục out (mặc định results/): run.jsonl (1 dòng/task),
report.md (tóm tắt), workspaces/<taskId>/ (artifact), run_meta.json (metadata
tái lập).
Agent chạy với môi trường tối thiểu (PATH/HOME/LANG/LC_ALL/TMPDIR/TMP/TEMP/TERM/USER) và
không thấy credential của driver. Cần key riêng thì khai tên biến qua agent.env_allow:
"agent": {
"command": ["python3", "scripts/agent_shim_example.py"],
"env_allow": ["MY_AGENT_API_KEY"]
}Agent chỉ cần nói hợp đồng STDIO JSONL trong docs/PROTOCOL.md. Nếu giao thức của nó khác, viết một shim (xem scripts/agent_shim_example.py) là đủ — không phải sửa một dòng C++ nào.
Judge llm gọi endpoint OpenAI-compatible, cấu hình qua khoá judge trong run config hoặc
biến môi trường:
| Khoá | Mô tả | Mặc định |
|---|---|---|
base_url |
endpoint | $BENCHMARK_JUDGE_BASE_URL hoặc https://api.deepseek.com |
model |
model judge | $BENCHMARK_JUDGE_MODEL hoặc deepseek-chat |
api_key_env |
tên biến chứa API key | DEEPSEEK_API_KEY |
rubric |
tiêu chí chấm | (bắt buộc) |
Demo offline, không cần API key:
python3 scripts/mock_judge_server.py 8799 &
./build/mac-arm64-release/agentbench run --config datasets/run_llm.jsonsrc/core Context / Plugin / ServiceRegistry / Config / EventBus / Logger
src/proto JSONL framing, AgentTransport (spawn, timeout, kill cả cây), mock agent
src/judge judge deterministic + LLM judge (HTTP qua libcurl)
src/suite Task / Suite / Runner (vòng lặp agentic), WorkspaceManager
src/report ResultStore (JSONL) + Markdown
src/cli agentbench
compat/ lớp nền tảng POSIX + Windows — src/ không có #ifdef
datasets/ task fixture + run config
tests/ doctest + CTest
Thêm task: một thư mục datasets/<suite>/<taskId>/ chứa task.json và workspace/.
Thêm suite: thêm thư mục + khai tên trong run config.
Thêm judge: cài class con của Judge và đăng ký vào JudgeRegistry (src/cli/main.cpp).
v0.1 — engine đã chạy được đầu-cuối, bộ đề còn nhỏ. Vòng đời task, transport, sandbox,
chấm lai, báo cáo và CI ba nền tảng đều hoạt động và có test. Đang thiếu: dataset quy mô
lớn, tool layer đầy đủ (hiện mới có write_file), trajectory log, calibration cho
LLM-judge, và adapter cho agent đích (đang chờ spec giao thức — dùng shim để tích hợp
ngay được).
Đánh giá chi tiết kèm lộ trình: reports/assessment-2026-08-18.md.
| docs/PROTOCOL.md | hợp đồng giao tiếp agent + hướng dẫn viết adapter/shim |
| docs/PLAN.md | kế hoạch theo phase, rủi ro, open item |
| AGENTS.md | mục tiêu, phạm vi, quyết định kiến trúc (có ngày + lý do), quy ước code |
| reports/ | review độc lập, phản biện chéo, đánh giá tổng thể |
.github/workflows/ci.yml — 4 job: engine macOS, engine Windows (clang-cl), engine Linux
(kèm kiểm chứng sandbox bwrap thật), và cross-mingw pre-flight cho compat_win.cpp.
© 2026 Aerovfx. Chưa kèm file LICENSE — liên hệ Aerovfx về điều khoản sử dụng.