AK Render: đừng bắt AI viết hàng trăm dòng HTML chỉ để trình bày một báo cáo

Bài 16 trong bộ onboarding AgentKit v3. Đọc khoảng 8 phút. Bài 10 có đoạn giới thiệu ngắn, bài này là hướng dẫn dùng.

Bảo AI "làm cho tui cái báo cáo", nó hì hục viết HTML, CSS, JavaScript, responsive, dark mode, biểu đồ... ra cả trăm KB. Lần sau yêu cầu báo cáo tương tự, nó lại viết gần như từ đầu. Dùng một model đắt tiền để làm việc mà trình biên dịch làm tốt hơn, nghe hổng hợp lý.

AK Render chia lại trách nhiệm: AI quyết định nội dung, compiler quyết định cách trình bày. AI chỉ viết một Page Spec (YAML hoặc JSON) mô tả trang cần chứa gì. Compiler biên dịch ra HTML hoàn chỉnh.

1/ Nó là gì, trong ba dòng

• Đầu vào: Page Spec, không có CSS, không có JavaScript.

• Đầu ra: một file HTML tự chứa, mở thẳng bằng file://, font nhúng sẵn, mặc định không phát sinh request mạng.

• Cùng spec, cùng phiên bản compiler, cùng cấu hình thì ra HTML giống hệt nhau ở mức byte (deterministic), nên kiểm tra bằng hash được.

Tại thời điểm tui kiểm tra (08/10/2026), danh mục có 83 loại block thuộc 8 nhóm, 16 dạng biểu đồ, 11 theme có sáng/tối, 10 mẫu khởi tạo (dashboard, benchmark report, incident report, implementation plan, decision memo...). Bài 10 ghi "khoảng 90 block", số này có thể đã đổi theo bản phát hành; hãy chạy catalog để lấy số hiện hành.

Tương tác khai báo bằng một tập action giới hạn. Bạn không nhét được JavaScript, CSS hay HTML thô vào spec. Đó là đánh đổi có chủ đích: bớt tự do, đổi lấy kết quả dễ đoán và an toàn khi giao cho agent.

2/ Khi nào dùng, khi nào đừng

Hợp: báo cáo, dashboard, kế hoạch triển khai, incident report, bản so sánh, tài liệu bàn giao, bất cứ thứ gì là thông tin có cấu trúc mà agent sinh ra lặp đi lặp lại.

Không hợp: ứng dụng có nghiệp vụ phức tạp, tích hợp backend, đồng bộ realtime, hay thiết kế tuỳ biến tới từng pixel. AK Render không thay React hay Next.js.

Cũng đừng kỳ vọng tiết kiệm phép màu: trong 12 trang tui phân tích, có một trường hợp Page Spec ước tính lớn hơn cách viết tay tới 35%. Trang toàn văn bản thuần thì compiler chẳng giúp được gì.

3/ Dùng từng bước (CLI)

Cần Node.js 20.11 trở lên. Mọi lệnh dưới đây có trong bài gốc và bài 10.

Cài skill cho coding agent:

npx skills add bestagentkits/ak-render

Xem danh mục block:

npx -y @bestagentkits/render catalog

Viết spec trong report.yaml. Ví dụ rút gọn:

version: 1
meta:
  title: "Báo cáo tiến độ"
theme:
  preset: editorial
blocks:
  - type: hero
    title: "Chuyển đổi AI trong doanh nghiệp"
  - type: callout
    tone: info
    title: "Lưu ý"
    text: "Số liệu trong ví dụ chỉ để minh hoạ."

Kiểm tra rồi biên dịch:

npx -y @bestagentkits/render validate report.yaml
npx -y @bestagentkits/render report.yaml --out report.html

Quy trình chuẩn cho agent: tìm block phù hợp, đọc contract, viết spec, validate, render. Trong lần chạy thử bằng MCP của tui, spec tiếng Việt validate không lỗi và ra khoảng 125 KB HTML với theme editorial, compiler 0.3.0. Con số byte đó chỉ là một lần chạy, không phải benchmark.

4/ Dùng qua MCP, và qua cờ trong skill AgentKit

MCP cục bộ (stdio), không cần tài khoản AgentKit, không gửi spec lên dịch vụ nào:

{
  "mcpServers": {
    "ak-render": {
      "command": "npx",
      "args": ["-y", "@bestagentkits/render", "mcp"]
    }
  }
}

Bộ MCP có 8 tool: catalog, search-catalog, describe, recipes, recipe, themes, validate, render. Với local, render ghi file ra đường dẫn out và chỉ trả về tóm tắt (bytes, hash, theme, warnings). Đừng bắt agent đọc ngược toàn bộ HTML vào context, vậy là tự phá lợi ích.

MCP từ xa (Streamable HTTP): https://render.agentkit.best/mcp, dành cho ChatGPT và client không cài được Node. Endpoint hosted kiểm tra OAuth hoặc API key AgentKit. Dùng API key thì đặt trong biến môi trường (ví dụ ${AGENTKIT_TOKEN}), không ghi key thật vào cấu hình commit lên repo. Link artifact thường hết hạn sau khoảng 1 giờ; render với share: true tạo link 30 ngày theo cấu hình hiện tại. Cấu hình có thể đổi.

Trong AgentKit: không có lệnh ak render. Các skill ak-brainstorm, ak-explain, ak-preview, ak-plan có cờ --ak-render (ngầm bật --html), ví dụ:

/ak-explain kiến trúc module thanh toán --ak-render

Cờ này cũng được chọn tự động nếu project có thư mục .ak-render/.

5/ Trạng thái và độ tin cậy của số liệu

Câu "tiết kiệm 60% token" tui từng đăng trên X là cách nói gọn của mức ước tính trên, không phải con số đo trên hoá đơn API. Hãy coi đó là bằng chứng ban đầu, chưa phải kết luận.

Tóm lại

1/ Agent viết Page Spec ngắn, compiler ra HTML tự chứa, chạy offline, kết quả xác định.

2/ Hợp với báo cáo và dashboard, không thay frontend tuỳ biến.

3/ Dùng bằng npx @bestagentkits/render, MCP cục bộ, hoặc cờ --ak-render.

4/ Số tiết kiệm token là ước tính. Đo lại trên tác vụ của bạn trước khi tin.

Nguồn

• AK Render: Đừng bắt AI viết hàng trăm dòng HTML chỉ để trình bày một báo cáo! (08/10/2026)

• render.agentkit.best, GitHub bestagentkits/ak-render

• Cờ --ak-render trong SKILL.md của ak-brainstorm, ak-explain, ak-preview, ak-plan