Decision Layer: System One, Jev, Clef và chuyện cho AI "ra quyết định có kiểu"

Bài 8/20 trong bộ onboarding AgentKit v3. Đọc khoảng 8 phút.

Trước khi vào bài, tui phải đính chính một chuyện: "Decision Layer" chưa phải là tên một tính năng trong AgentKit. Bạn sẽ không tìm thấy chữ này trong ak, trong docs hay trên site. Đây là cách tui gọi chung một hướng đi đang thử nghiệm: dùng model nhỏ, chuyên ra phán đoán có cấu trúc để giúp agent chọn đúng thay vì đoán mò.

Phần đã có trong ak 3.0.0 là chế độ shadow 🧪. Phần còn lại là định hướng 🗺️. Đọc với tâm thế đó nghen.

1/ Vấn đề cần giải

Agent mỗi ngày ra hàng trăm quyết định nhỏ:

• Yêu cầu này nên dùng skill nào?

• Bug này đơn giản hay phức tạp, cần quy trình nào?

• Việc này chia cho nhiều agent chạy song song có rủi ro không?

Hiện tại, mấy quyết định đó dựa vào luật cứng (regex, bảng tra) hoặc để model lớn tự đoán trong lúc đang làm việc khác. Luật cứng thì gãy khi gặp câu hỏi lạ. Model lớn thì tốn token, và mỗi lần hỏi một kiểu.

Ý tưởng: tách những phán đoán nhỏ đó ra, giao cho model chuyên làm phán đoán, trả về kết quả có kiểu (typed) kèm xác suất, để code bình thường dùng được như một hàm.

2/ System One và Jev

System One là dòng model của TypeSafe, trong đó có Jev. Chúng biến ngôn ngữ tự nhiên cộng với trạng thái ứng dụng thành phán đoán có kiểu và xác suất: chọn một trong N, chấm điểm, có/không... Code ghép mấy phán đoán đó lại như ghép hàm.

Kit có skill typesafe-ai hướng dẫn agent build tính năng dùng TypeSafe.

3/ Clef

Clef (clef và clef-flash) là tên model khi chọn provider Cloudflare trong cấu hình semantic decision. Hiện nó chỉ xuất hiện dưới dạng tên model trong cấu hình provider.

4/ Thứ đã có trong ak 3.0.0: shadow mode 🧪

ak eval decision chạy một so sánh bóng (shadow): đưa cùng một tình huống cho phán đoán ngữ nghĩa, rồi so với quyết định mà luật cũ đã đưa ra. Nó không bao giờ thay quyết định cũ, chỉ in ra để bạn xem phán đoán mới có tốt hơn không.

Có 4 profile: domain-routing, fix-complexity, orchestration-risk, skill-routing-eval.

Bật (phải tự tay, ở scope user)

ak config prefs set semantic_decision.enabled true --scope user
ak config prefs set semantic_decision.provider typesafe --scope user

hoặc dùng Cloudflare:

ak config prefs set semantic_decision.provider cloudflare --scope user

Credential không bao giờ nằm trong config. Đặt bằng biến môi trường hoặc trong ~/.agentkit/.env:

• Provider typesafe: TYPESAFE_API_KEY

• Provider cloudflare: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN

.env của project không được đọc cho mấy key này. Cố ý vậy: một repo lạ không thể tự bật provider tốn tiền của bạn. Config cấp project chỉ được tắt, không được bật.

Kiểm tra

ak doctor --check semantic_decision

Chạy thử

ak eval decision request.json --validate-only   # kiểm tra file input, không gọi provider
ak eval decision request.json --json

Mấy điểm an toàn tui cố ý thiết kế:

• Gọi lệnh không tự bật provider.

• Chỉ gửi dữ kiện đã tóm gọn và redact, không gửi file thô, transcript hay credential.

• Không lưu input.

• Có thể phát sinh phí từ provider, nên mới bắt bạn đồng ý rõ ràng ở scope user.

5/ Tại sao làm chậm vậy?

Vì một phán đoán sai trong định tuyến skill thì chỉ phiền. Một phán đoán sai trong "việc này có rủi ro không" thì có thể toang.

Nên quy trình của tui là: shadow trước, đo đủ, rồi mới cho quyết định thật. Khi nào số liệu shadow cho thấy phán đoán ngữ nghĩa thắng luật cũ một cách ổn định, nó mới được lên chức. Còn hôm nay, nó chỉ là người ngồi bên cạnh ghi chép.

Bài tiếp: Cài AgentKit trên cloud và CI →

Nguồn

• ak eval decision --help, ak config prefs set --help (ak 3.0.0): profile shadow, consent scope user, "never changes the legacy decision"

• Output thật ak doctor --check semantic_decision trong HOME tạm, 02/11/2026

• Tài liệu TypeSafe System One: https://docs.typesafe.ai/concepts/system-one.md (dẫn trong skill typesafe-ai)