Khả năng quan sát AI agent: làm sao biết agent đã làm gì và cần ghi log những gì

Khả năng quan sát AI agent là gì

Khả năng quan sát của AI agent là việc có thể trả lời ba câu hỏi dựa trên các artifact, chứ không dựa vào trí nhớ hay lời nói của agent: nó đã làm gì, vì sao làm như vậy và điều gì chứng minh kết quả là đúng. Nếu sau hai mươi phút làm việc agent nói «xong rồi, nhưng hai test đang lỗi, có lẽ do timing», và khi hỏi «những đường dẫn nào bị ảnh hưởng» nó trả lời «cho tôi xem code đã», thì không có khả năng quan sát. Agent không ngu — chỉ là nó không có gì để đưa ra.

Vấn đề mang tính hệ thống. Cùng một agent trong một tuần có thể mười lần thành thật nói «xong», và mỗi lần điều đó có nghĩa khác nhau: chỗ thì đã chạy toàn bộ test, chỗ chỉ một test, chỗ thì không gì cả. Dự án càng sống lâu, mỗi phiên mới càng tốn kém, vì nó bắt đầu bằng việc đào bới.

Hai lớp: runtime và quy trình

Khả năng quan sát thường bị nhầm với log, nhưng log chỉ là một nửa.

Chỉ có runtime: thấy cái gì hỏng nhưng không rõ mục tiêu là gì. Chỉ có quy trình: hiểu muốn gì nhưng không thấy vì sao không đạt. Cần cả hai.

Vì sao agent không tự làm được điều này

Bảo agent «ghi log kỹ hơn» sẽ không hiệu quả vì ba lý do.

• Nó không biết mình không biết điều gì. Agent sẽ không ghi lại một tín hiệu mà nó không ngờ là quan trọng.
• Định dạng trôi dạt. Phiên này nó ghi chi tiết, phiên khác ghi một dòng. Không thể so sánh các phiên hay tính tổng hợp.
• Log không giải quyết được quy trình. Câu trả lời cho «vì sao lại như vậy» nằm trong tài liệu được tạo trước khi làm việc, chứ không nằm trong đầu ra của lệnh.

Vì thế khả năng quan sát được đưa vào harness — môi trường của agent: template, hook, script, định dạng báo cáo bắt buộc.

Nên ghi log gì: bộ tối thiểu

Nhật ký tốt không phải là bản ghi chép mọi thứ, mà là tập hợp các sự kiện đủ để khôi phục tiến trình công việc và tính thống kê.

• Định danh: id phiên, id nhiệm vụ hoặc tính năng, mô hình agent.
• Hành động có tác dụng phụ: lệnh nào đã chạy, file nào đã đổi. Việc đọc file thường không cần ghi.
• Kết quả kiểm tra: lệnh kiểm tra nào, mã trả về, bao nhiêu test pass và fail.
• Retry: mỗi bước tốn bao nhiêu lần thử và các lần thử khác nhau ở điểm nào.
• Chi phí: token và thời gian, nếu công cụ cung cấp.
• Kết luận: nhiệm vụ được chấp nhận, bị từ chối hay bị bỏ dở, và vì sao.

Không nên ghi: bí mật, token truy cập, dữ liệu cá nhân từ đầu ra lệnh. Nhật ký có thể bị chia sẻ rộng hoặc lại đi vào ngữ cảnh của mô hình.

Nhật ký hành động qua hook của Claude Code

Trong Claude Code, nhật ký thuận tiện nhất được ghi bằng hook — lệnh do chính công cụ chạy chứ không phải mô hình, nên chúng luôn được kích hoạt. Hook nhận đầu vào là JSON mô tả sự kiện, bao gồm id phiên, tên công cụ và các tham số. Ví dụ cấu hình trong .claude/settings.json để sau mỗi lần gọi Bash, Edit hoặc Write thì thêm một dòng vào nhật ký:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — một bản ghi JSON cho mỗi hành động
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

Định dạng JSONL (mỗi dòng một bản ghi JSON) tiện ở chỗ dễ lọc bằng jq và đưa vào bất kỳ hệ thống phân tích nào. Ngoài ra, Claude Code còn tự lưu lịch sử đầy đủ của các phiên trên máy trong thư mục ~/.claude/projects/ — có thể mở ra xem lập luận và đầu ra đầy đủ, nhưng để thống kê thì nhật ký gọn của riêng bạn tiện hơn.

Trace: một trace cho mỗi phiên, span cho mỗi nhiệm vụ

Khi có nhiều agent hoặc agent chạy theo lịch, log văn bản là không đủ: cần số liệu tổng hợp. Lúc này các công cụ tracing phân tán thông thường và chuẩn OpenTelemetry sẽ hữu ích.

• Trace — một phiên của agent.
• Span — một nhiệm vụ trong phiên.
• Span lồng nhau — các bước kiểm chứng: build, test, e2e.

Tối thiểu nên có các thuộc tính trên mỗi span: id tính năng và phiên, mô hình, kết quả kiểm tra, token, số lần retry. Dữ liệu như vậy đọc được trong Jaeger, Grafana Tempo, Honeycomb và trả lời những câu hỏi mà một phiên đơn lẻ không thấy được: loại tác vụ nào hay cần retry, agent tốn token nhiều nhất ở đâu, sau thay đổi nào của harness thì tỷ lệ nhiệm vụ được chấp nhận giảm. Claude Code có sẵn chức năng xuất metric và sự kiện qua OpenTelemetry — bật bằng biến môi trường, chi tiết xem trong tài liệu của công cụ.

Commit làm nhật ký

Nhật ký rẻ nhất và đáng tin nhất bạn đã có sẵn — đó là git. Chỉ cần làm cho nó dễ đọc.

1. Một commit — một nhiệm vụ. Khi đó git log trùng với danh sách việc đã làm, và hoàn tác một nhiệm vụ chỉ cần một git revert.
2. Trong thông điệp — đã đổi gì và đã kiểm tra thế nào. Không ghi «fix», mà ghi «đã đổi gì, vì sao, kiểm tra bằng lệnh nào».
3. Chỉ commit sau khi kiểm tra xanh. Khi đó mỗi điểm trong lịch sử là một trạng thái làm việc được, và git bisect tìm ra thủ phạm.

fix(payments): làm tròn giảm giá đến đơn vị xu

Giảm giá được tính bằng float, với số tiền 999.99 bị mất một xu.
Chuyển phép tính sang int theo đơn vị xu.
Đã kiểm tra: make test (142 passed), make e2e checkout — ok.
Ngoài phạm vi: làm tròn trong báo cáo, đã ghi vào BACKLOG.md.

Báo cáo của agent: bằng chứng thay vì cảm nhận

Tin nhắn cuối cùng của agent cũng là một artifact của khả năng quan sát, nếu nó có hình thức cố định. Hãy ghi template trong AGENTS.md hoặc CLAUDE.md:

## Báo cáo khi kết thúc nhiệm vụ
- Đã làm gì: danh sách thay đổi (file — nội dung)
- Đã kiểm tra thế nào: lệnh chính xác và kết quả
- Chưa kiểm tra gì và vì sao
- Sai lệch so với thỏa thuận về nhiệm vụ
- Câu hỏi mở cho con người

Quy tắc chính: mỗi khẳng định phải dẫn tới bằng chứng — file và dòng, đầu ra của test, một bản ghi trong nhật ký. «Trông có vẻ ổn» và «tôi nghĩ là ok» không được tính là báo cáo. Mục «chưa kiểm tra gì» đặc biệt có giá trị: nó thẳng thắn cho thấy giới hạn của sự tự tin.

Thỏa thuận trước khi viết code, rubric sau khi làm

Lớp quy trình bắt đầu trước khi làm việc. Một thỏa thuận ngắn về nhiệm vụ (sprint contract) ghi lại phạm vi, tiêu chí nghiệm thu, mục «ngoài phạm vi» và các câu hỏi mở mà con người sẽ quyết định. Mục «ngoài phạm vi» ngăn được một nửa các tranh cãi về kết quả.

Sau khi làm xong, kết quả được đánh giá theo rubric, không theo cảm nhận. Nếu không, hai người review có kinh nghiệm sẽ cho hai kết luận khác nhau, và việc đánh giá trở thành xổ số.

Mỗi tiêu chí chấm theo thang A/B/C/D, và điểm không có liên kết tới bằng chứng là không hợp lệ. Quy tắc quyết định đơn giản: một D hoặc hai C — từ chối, kèm danh sách những gì cần sửa. Chính rubric này cũng có thể được áp dụng bởi một agent kiểm tra riêng.

Cách kiểm tra agent đã làm gì trong một phiên

Nếu không có báo cáo, hoặc không tin báo cáo, hãy đi qua các artifact theo thứ tự sau.

1. Trạng thái cây thư mục: git status — cái gì chưa commit, có file rác nào không.
2. Lịch sử: git log --stat từ đầu phiên — những commit và file nào.
3. Quy mô thay đổi: git diff --stat main...HEAD, sau đó xem đầy đủ diff các file quan trọng.
4. Nhật ký hành động: những lệnh nào đã chạy và các kiểm tra trả về gì.
5. Kiểm tra lại: tự chạy build và test. Tin vào đầu ra của lệnh, không tin vào lời kể lại.

# các lệnh agent đã chạy trong phiên gần nhất
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# những file nào được sửa nhiều nhất
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

Lỗi thường gặp

• Ghi log tất cả. Hàng gigabyte bản ghi chép không ai đọc. Hãy ghi các hành động có tác dụng phụ và kết quả kiểm tra.
• Định dạng tự do. Nếu agent tự quyết định định dạng nhật ký, sẽ không có số liệu tổng hợp. Định dạng do harness quy định.
• Tin báo cáo mà không có đầu ra lệnh. «Test xanh» không kèm đầu ra chỉ là một ý kiến.
• Retry mù quáng. Không biết nguyên nhân lỗi, agent sửa lung tung. Hãy yêu cầu chẩn đoán trước, kèm dẫn chiếu tới log, rồi mới sửa.
• «Để dọn sau.» File debug và thay đổi chưa commit làm phiên kế tiếp bối rối: nó không phân biệt được tạm thời với có chủ ý.

Tổng kết

Khả năng quan sát AI agent được xây từ hai lớp: runtime (nhật ký hành động qua hook, trace, commit có mô tả kiểm tra) và quy trình (thỏa thuận nhiệm vụ trước khi viết code, rubric và báo cáo có dẫn chứng). Khi đó «xong» có cùng một nghĩa ở mọi phiên, và việc kiểm tra công việc của agent chỉ mất vài phút. Chủ đề này được trình bày thực hành trong khóa học về harness engineering, trên một dự án backend thanh toán xuyên suốt.