Template chuẩn (golden template / paved road) là thứ biến "mỗi team làm một kiểu" thành "ai cũng bắt đầu giống nhau". Mục tiêu: một dev mới platform new-agent my-agent là có ngay bộ khung có logging, guardrails, test, CI/CD, tài liệu — chỉ cần điền phần nghiệp vụ.
Một golden template gồm gì?
my-agent/
├─ agent.py # định nghĩa agent, tools, prompt
├─ prompts/ # system prompt tách riêng, versioned
├─ config.yaml # capability, guardrails, quota, owner
├─ evals/ # bộ test chất lượng (golden set)
├─ tests/ # unit test cho tools
├─ .platform-ci.yml # pipeline: lint, eval, scan secret
└─ AGENT_CARD.md # ai sở hữu, data dùng, rủi ro
Điểm mấu chốt: những thứ về an toàn và quan sát được cài sẵn và khó gỡ, còn phần nghiệp vụ thì dễ sửa.
config.yaml — hợp đồng của agent
name: support-summarizer
owner: team-cskh
capability: chat
guardrails: default # kế thừa bộ chuẩn
data_classification: internal # public|internal|confidential
tools:
- name: lookup_customer
scopes: [crm:read]
quota:
daily_token_budget: 500000
rollout: canary # canary -> production
File này là hợp đồng để cổng quản trị đọc: biết owner, mức dữ liệu, quota, quyền tool — không cần đọc code.
Prompt phải được version hóa
Đừng nhét system prompt thành chuỗi trong code. Tách ra prompts/system.v3.md và tham chiếu theo phiên bản, để rollback được khi prompt mới làm hỏng chất lượng.
system = load_prompt("system", version="v3")
Các bước tạo golden template
- Bắt đầu từ một agent thật đã chạy tốt, đừng thiết kế template trên giấy — rút ra khung từ cái đã hoạt động.
- Tách phần "khung" (khó sửa) và "nghiệp vụ" (dễ sửa): guardrails, logging, CI thuộc khung.
- Đóng thành scaffolder: lệnh
platform new-agent <tên>sinh thư mục từ template (dùng cookiecutter/copier). - Nhúng sẵn eval tối thiểu: mỗi agent bắt buộc có ít nhất 5 ca kiểm thử golden set.
- Nhúng CI mặc định: quét secret, chạy eval, chặn merge nếu điểm eval tụt dưới ngưỡng.
- Viết AGENT_CARD.md: tài liệu 1 trang bắt buộc mô tả rủi ro và dữ liệu.
AGENT_CARD.md — tài liệu một trang bắt buộc
Mỗi agent phải kèm một "thẻ căn cước" ngắn gọn, viết bằng ngôn ngữ người đọc được (không chỉ máy đọc như config.yaml). Nó trả lời các câu mà bất kỳ ai đến sau — kiểm toán viên, thành viên mới, đội bảo mật — sẽ hỏi: Agent này làm gì? Ai chịu trách nhiệm khi nó hỏng? Nó chạm vào dữ liệu nào? Rủi ro lớn nhất là gì và ta đã giảm thiểu ra sao? Một AGENT_CARD tốt tiết kiệm hàng giờ điều tra khi có sự cố, và buộc chính người xây phải suy nghĩ về rủi ro trước khi deploy — thường phát hiện vấn đề ngay ở khâu viết thẻ.
Ví dụ nội dung tối thiểu: tên agent, owner và kênh liên hệ on-call, mục đích một câu, danh sách tool + scope, mức phân loại dữ liệu, ba rủi ro hàng đầu kèm biện pháp giảm thiểu, và cách tắt khẩn cấp (kill switch). Vì thẻ này nằm ngay trong repo template, nó luôn đi cùng code và không bị lạc như tài liệu rời.
Khung tư duy: "Bật sẵn, xin để tắt"
Mọi thứ an toàn phải on-by-default. Team muốn tắt guardrails, dùng model đắt, hay xin scope ghi dữ liệu thì phải khai báo trong config và qua review. Đường mặc định phải là đường an toàn nhất và cũng nhanh nhất — đó là cách khiến người ta tự nguyện đi theo. Nguyên tắc này đảo ngược động lực: thay vì bắt dev nhớ bật bảo mật (họ sẽ quên), bạn bắt họ phải chủ động xin phép mới được nới lỏng, và mỗi lần nới lỏng đều để lại dấu vết trong config để review sau này.
Checklist một template đạt chuẩn
- [ ] Sinh được bằng một lệnh, chạy được ngay (
hello agent). - [ ] Guardrails + logging bật sẵn, không cần cấu hình thêm.
- [ ] Có config.yaml khai báo owner, capability, scopes, data class.
- [ ] Có evals/ với golden set tối thiểu.
- [ ] CI chặn secret và eval tụt điểm.
- [ ] Có AGENT_CARD.md.
Sai lầm thường gặp
- Template quá nặng, quá nhiều tùy chọn: người ta thấy phức tạp hơn tự viết nên bỏ qua. Giữ mỏng.
- Không có scaffolder: bắt copy-paste tay thì mỗi bản sao sẽ trôi (drift) mỗi kiểu.
- Không nhúng eval: agent lên production rồi mới biết chất lượng kém.
- Hard-code prompt trong code: không rollback được khi prompt mới gây lỗi.
- Khung dễ sửa hơn nghiệp vụ: dev vô tình gỡ mất guardrails khi tùy biến.