Agent muốn bay phải có checklist

Đừng đo agent bằng demo chạy được một lần. Hãy dựng workspace nhỏ, có guardrail, tiêu chí dừng và log đủ để biết khi nào nên scale.

Bạn đã bao giờ thấy một demo agent chạy mượt trong meeting, rồi tuần sau team ngồi gỡ vì nó gọi nhầm tool, đọc nhầm file, hoặc trả lời rất tự tin về thứ không có trong tài liệu chưa?

Mình thấy cảnh này hơi nhiều. Không phải vì developer dở. Mà vì nhiều team đang thử agent như thử một prompt dài: chạy được là vui, chưa chạy được thì đổi model. Trong khi với hệ thống agent, câu hỏi quan trọng hơn là: ai điều phối, ai được phép làm gì, khi nào phải dừng, và mình đo lỗi bằng cách nào?

QwenPaw gần đây có một tutorial khá thực dụng: dựng workspace trong Colab, cấu hình model provider, tạo custom skill, thêm knowledge file, mở console, rồi test streaming API. Mình không muốn biến nó thành bài “làm theo từng lệnh”. Góc đáng giữ lại là khác: một agent workspace tốt không phải sân khấu demo, mà là đường băng thử nghiệm có kiểm soát.

Dưới đây là playbook mình sẽ dùng nếu phải đưa một agent assistant vào team thật, nhất là team đang build automation nội bộ, RAG, hoặc workflow hỗ trợ dev.

Sơ đồ tóm tắt ý chính của bài viết.

Mục tiêu: đừng cho agent “tự do bay” ngay từ ngày đầu

Dịch sang tiếng người: orchestration là cách điều phối nhiều bước, nhiều tool hoặc nhiều agent để hoàn thành việc; guardrail là hàng rào kỹ thuật giúp hệ thống không làm quá quyền, quá phạm vi, hoặc trả lời bừa.

Hiểu lầm phổ biến là: “Chọn model tốt hơn thì agent sẽ đáng tin hơn.” Sai một nửa. Model tốt giúp câu trả lời mượt hơn, nhưng production failure thường nằm ở chỗ khác:

• Tool được gọi khi không nên gọi.
• Agent đọc context thiếu nhưng vẫn kết luận.
• Console mở ra tiện quá, nhưng quyền truy cập lỏng.
• Streaming API nhìn “đã mắt”, nhưng không log đủ để debug.
• Skill viết hay, nhưng không có test case để biết khi nào nó lệch.

QwenPaw-style workspace gợi ý một cách tiếp cận đáng học: gom cấu hình, provider, skill, knowledge file, console và API test vào một nơi. Nhưng phần bạn cần thêm là quy tắc vận hành. Không có quy tắc, agent giống chuyến bay không có tháp không lưu: cất cánh thì được, hạ cánh mới hồi hộp.

Checklist trước khi thử trong một buổi

Nếu team bạn có một buổi chiều, đừng bắt đầu bằng “làm agent biết mọi thứ”. Bắt đầu bằng một tác vụ hẹp.

Ví dụ cụ thể: agent tạo research_brief cho một issue kỹ thuật nội bộ. Input là một câu hỏi, vài file knowledge, và output là bản brief có cấu trúc: bối cảnh, giả định, rủi ro, câu hỏi cần xác minh, bước tiếp theo.

Checklist tối thiểu:

• Một nhiệm vụ duy nhất: ví dụ “tóm tắt tài liệu triển khai” hoặc “phân loại bug report”, không làm cả trợ lý tổng hợp.
• Một workspace riêng: tách file cấu hình, knowledge, skill, log khỏi repo chính.
• Một model provider mặc định: có thể dùng OpenAI, OpenRouter, DashScope, DeepSeek, Gemini hoặc provider bạn đang có key; quan trọng là có fallback rõ.
• Một custom skill: skill là hướng dẫn có cấu trúc cho một loại việc, không phải prompt tùy hứng.
• Một tập knowledge nhỏ: 3-5 file đủ đại diện, tránh nhồi cả ổ tài liệu ngay ngày đầu.
• Một đường gọi API: test được qua console và qua streaming API để biết tích hợp thật sẽ ra sao.
• Một tiêu chí dừng: nếu agent vi phạm quyền tool, thiếu citation, hoặc trả lời ngoài tài liệu quá số lần bạn chấp nhận, dừng thử nghiệm.

Điểm cuối rất quan trọng. Team hay có tiêu chí thành công, ít khi có tiêu chí dừng. Với agent, không có tiêu chí dừng thì bạn sẽ cứ vá prompt mãi như vá đường băng giữa lúc máy bay đang lăn bánh.

Bước 1: dựng workspace như môi trường kiểm thử, không phải đồ chơi Colab

Bạn có thể dùng Colab để thử nhanh vì tiện cho secret, notebook và tunnel. Nhưng hãy đặt kỷ luật như đang chuẩn bị đưa vào staging.

Một cấu trúc tối thiểu có thể như sau:

agent-workspace/
  config/
    agent.yaml
    providers.yaml
  skills/
    research_brief.md
  knowledge/
    setup_notes.md
    product_context.md
    runbook.md
  logs/
  tests/
    cases.jsonl

Trong agent.yaml, đừng chỉ ghi model. Hãy ghi cả quyền, memory, streaming, và policy gọi tool:

agent:
  name: internal_research_assistant
  default_skill: research_brief
  streaming: true
  memory: limited
  tools:
    file_read: allow
    shell_exec: deny_by_default
    web_search: require_confirmation
  output_contract:
    must_include:
      - assumptions
      - evidence
      - open_questions
      - next_steps

Đây không phải cú pháp bắt buộc của mọi framework; coi nó là mẫu tư duy cấu hình. Nếu framework bạn dùng có schema khác, hãy chuyển ý tưởng này sang schema đó.

Mục tiêu của bước này: khi agent làm sai, bạn biết nó sai vì model, vì skill, vì knowledge thiếu, hay vì tool permission quá rộng.

Bước 2: viết skill như hợp đồng đầu ra

Custom agent trong Copilot CLI hay skill trong QwenPaw-style workspace đều đang đẩy developer từ “one-off prompt” sang workflow có thể lặp lại. Đây là thay đổi đáng giá.

Một skill tốt không nên chỉ viết:

Hãy nghiên cứu vấn đề và trả lời rõ ràng.

Nó nên đóng vai trò hợp đồng:

# research_brief

Bạn hỗ trợ tạo brief kỹ thuật từ knowledge nội bộ.

## Luôn làm
- Nêu phạm vi câu hỏi.
- Liệt kê bằng chứng từ file được cung cấp.
- Tách phần chắc chắn và phần suy đoán.
- Đưa ra câu hỏi cần xác minh trước khi triển khai.

## Không được làm
- Không bịa version, API, benchmark.
- Không đề xuất thay đổi production nếu thiếu runbook.
- Không gọi tool ngoài danh sách được phép.

## Output
1. Tóm tắt ngắn
2. Bằng chứng
3. Rủi ro
4. Việc cần kiểm tra tiếp

Hình dung thế này: bạn giao việc cho agent như giao kế hoạch bay. Nếu chỉ nói “bay tới nơi an toàn nhé”, nghe lịch sự nhưng vô dụng. Cần điểm đến, vùng cấm, điều kiện quay đầu, và ai có quyền cho phép đổi hướng.

Bước 3: test streaming API bằng case xấu, không chỉ case đẹp

Streaming API — API trả kết quả từng phần theo thời gian — rất hữu ích cho UX. Người dùng thấy agent đang suy nghĩ, frontend có thể render từng đoạn, backend có thể hủy request nếu vượt giới hạn.

Nhưng streaming cũng làm lộ một vấn đề: agent có thể bắt đầu trả lời trước khi đủ context. Với workflow có RAG hoặc multi-hop query, đây là vùng nguy hiểm.

Google Research nói nhiều về hướng agentic RAG — RAG có agent lập kế hoạch, viết lại truy vấn, tìm nhiều nguồn và kiểm tra đủ context trước khi trả lời. Điểm đáng học không phải là tên sản phẩm, mà là ý tưởng sufficient context check: kiểm tra xem ngữ cảnh đã đủ chưa.

Trong buổi thử, hãy có ít nhất 5 test case:

{"case":"câu hỏi có đủ thông tin trong knowledge","expect":"trả lời có evidence"}
{"case":"câu hỏi thiếu thông tin quan trọng","expect":"nói thiếu thông tin, không bịa"}
{"case":"câu hỏi cần nối 2 file","expect":"trích cả hai nguồn"}
{"case":"yêu cầu gọi tool bị cấm","expect":"từ chối hoặc xin xác nhận"}
{"case":"prompt injection trong file knowledge","expect":"bỏ qua chỉ dẫn độc hại"}

Đừng chỉ test câu hỏi “ngoan”. Production sẽ gặp câu hỏi thiếu, câu hỏi vòng, câu hỏi có mồi nhử, và cả người dùng vô tình paste nội dung gây nhiễu.

Bước 4: đặt guardrail theo ba tầng

Mình thích chia guardrail thành ba tầng, vì nó giúp team không tranh luận mơ hồ.

| Tầng | Kiểm soát gì | Ví dụ |
|---|---|---|
| Input | Thứ người dùng đưa vào | chặn secret, giới hạn file type, lọc prompt injection rõ ràng |
| Action | Việc agent được làm | tool allowlist, confirmation trước shell/API, timeout |
| Output | Thứ trả về | citation bắt buộc, schema validation, gắn nhãn “chưa đủ dữ kiện” |

Với builder, tầng Action thường là nơi đáng sợ nhất. Một agent có quyền shell, quyền đọc file, quyền gọi API nội bộ mà thiếu confirmation thì không còn là assistant nữa; nó là automation có khả năng gây sự cố.

Google DeepMind và các đối tác đang nhấn mạnh rủi ro của hệ multi-agent khi nhiều agent tương tác và sinh hành vi khó đoán. Với team nhỏ, bạn chưa cần nghĩ đến “hàng triệu agent”. Nhưng bạn cần nghĩ đến phiên bản mini: agent A ghi ticket, agent B đọc ticket để deploy, agent C gửi thông báo. Một lỗi nhỏ có thể lan qua workflow.

Khi nào scale, khi nào dừng?

Sau một buổi thử, đừng hỏi “agent có thông minh không?”. Hỏi 5 câu này:

1. Tỷ lệ case đạt có ổn định qua nhiều lần chạy không? Không cần benchmark hoành tráng, nhưng cùng input không nên cho hành vi quá lệch.
2. Log có đủ để debug không? Bạn cần thấy prompt, skill, tool call, latency, lỗi provider, và output cuối.
3. Agent có biết nói “không đủ dữ kiện” không? Đây là dấu hiệu trưởng thành hơn một câu trả lời dài.
4. Tool permission có bị mở quá tay không? Nếu có, thu hẹp trước khi thêm tính năng.
5. Chi phí vận hành có dự đoán được không? Model provider, retry, streaming, memory và context dài đều có hóa đơn riêng.

Nếu 4/5 câu trả lời ổn, bạn có thể scale sang thêm knowledge file hoặc thêm một skill mới. Nếu không, dừng ở workspace. Đừng đưa vào Slack, ticket system hay CI/CD chỉ vì demo nhìn mượt.

Điều nên đổi trong đầu sau bài này

Agent không phải là “prompt biết gọi tool”. Agent là một hệ thống vận hành nhỏ, có quyền, có trạng thái, có lỗi lan truyền, và có người phải chịu trách nhiệm khi nó làm sai.

QwenPaw-style workspace, custom agents trong CLI, agentic RAG hay nghiên cứu safety multi-agent đều đang chỉ về cùng một hướng: giá trị thật nằm ở workflow có kiểm soát, không nằm ở màn trình diễn trả lời nhanh.

Nếu là mình, mình sẽ bắt đầu bằng một skill hẹp, một workspace sạch, một bộ test case xấu, và một quy tắc rất đời: chưa có log thì chưa cho cất cánh. Agent có thể thông minh, nhưng vẫn cần bảng kiểm — phi công giỏi cũng đâu bay bằng cảm hứng.

---
Bụi Wire — nghiện đọc release notes lúc 2 giờ sáng