Observability ของ AI agent: รู้ได้อย่างไรว่า agent ทำอะไร และควร log อะไร

Observability ของ AI agent คืออะไร

Observability ของ AI agent คือความสามารถที่จะตอบสามคำถามจากหลักฐาน ไม่ใช่จากความจำหรือคำพูดของ agent ได้แก่ มันทำอะไร ทำไมจึงทำแบบนั้น และอะไรยืนยันว่าผลลัพธ์ถูกต้อง ถ้าหลังทำงานยี่สิบนาที agent บอกว่า "เสร็จแล้ว แต่เทสต์สองตัวล้ม น่าจะเป็นเพราะ timing" และเมื่อถามว่าเปลี่ยนไฟล์ไหนบ้างก็ตอบว่า "ขอดูโค้ดก่อน" แสดงว่าไม่มี observability agent ไม่ได้โง่ เพียงแต่ไม่มีอะไรให้มันแสดงหลักฐาน

ปัญหานี้เป็นระบบ agent เดียวกันในหนึ่งสัปดาห์อาจพูดว่า "เสร็จแล้ว" อย่างซื่อตรงสิบครั้ง และแต่ละครั้งอาจหมายถึงสิ่งที่ต่างกัน บางครั้งเทสต์ทั้งหมดผ่าน บางครั้งผ่านแค่ตัวเดียว บางครั้งไม่ได้ตรวจเลย ยิ่งโปรเจกต์มีอายุนาน เซสชันแต่ละครั้งก็ยิ่งมีค่าใช้จ่ายสูง เพราะต้องเริ่มจากการขุดค้น

สองชั้น: runtime และ process

Observability มักถูกสับสนกับ log แต่ log เป็นเพียงครึ่งเดียว

ถ้ามีเพียง runtime จะเห็นว่าอะไรล้ม แต่ไม่รู้ว่าต้องการอะไรตั้งแต่แรก ถ้ามีเพียง process จะรู้ว่าต้องการอะไร แต่ไม่เห็นว่าทำไมจึงไม่สำเร็จ ต้องมีทั้งสองชั้น

ทำไม agent ทำสิ่งนี้เองไม่ได้

การบอก agent ว่า "log ให้ดีขึ้น" ไม่ได้ผล ด้วยเหตุผลสามข้อ

• มันไม่รู้ว่าตัวเองไม่รู้อะไร agent จะไม่ log สัญญาณที่มันไม่ได้คิดว่าสำคัญ
• รูปแบบเปลี่ยนไปเรื่อยๆ เซสชันหนึ่งเขียนละเอียด อีกเซสชันเขียนเป็นบรรทัดเดียว เปรียบเทียบเซสชันหรือนับผลรวมไม่ได้
• กระบวนการปิดด้วย log ไม่ได้ คำตอบของ "ทำไมจึงทำแบบนี้" อยู่ในเอกสารที่เขียนก่อนลงมือ ไม่ได้อยู่ในผลของคำสั่ง

ดังนั้น observability ต้องฝังไว้ในฮาร์เนส คือสภาพแวดล้อมของ agent ได้แก่ เทมเพลต hook สคริปต์ และรูปแบบรายงานที่บังคับ

ควร log อะไรบ้าง: ชุดขั้นต่ำ

บันทึกที่ดีไม่ใช่บทถอดความทุกอย่าง แต่เป็นชุดข้อเท็จจริงที่ใช้สร้างลำดับการทำงานขึ้นมาใหม่และคำนวณสถิติได้

• ตัวระบุ: รหัสเซสชัน รหัสงานหรือฟีเจอร์ โมเดลที่ agent ใช้
• การกระทำที่มีผลข้างเคียง: คำสั่งที่รัน ไฟล์ที่เปลี่ยน การอ่านไฟล์โดยทั่วไปไม่จำเป็นต้องเขียน
• ผลการตรวจ: คำสั่งตรวจอะไร รหัสผลลัพธ์ เทสต์ที่ผ่านและล้มกี่ตัว
• การลองซ้ำ: ขั้นหนึ่งใช้ความพยายามกี่ครั้งและแต่ละครั้งต่างกันอย่างไร
• การใช้ทรัพยากร: โทเคนและเวลา ถ้าเครื่องมือให้ข้อมูลนี้มา
• ผลสุดท้าย: งานถูกรับ ปฏิเสธ หรือทิ้งไป และเพราะเหตุใด

สิ่งที่ไม่ควรเขียนคือความลับ โทเคนการเข้าถึง และข้อมูลส่วนบุคคลจากผลลัพธ์ของคำสั่ง เพราะบันทึกอาจถูกเผยแพร่หรือกลับเข้าไปในบริบทของโมเดลอีกครั้ง

บันทึกการกระทำผ่าน hook ของ Claude Code

ใน Claude Code บันทึกการกระทำทำได้สะดวกด้วย hook ซึ่งเป็นคำสั่งที่เครื่องมือเป็นผู้รัน ไม่ใช่โมเดล จึงทำงานเสมอ hook รับ JSON ที่อธิบายเหตุการณ์ เช่น รหัสเซสชัน ชื่อเครื่องมือ และพารามิเตอร์ ตัวอย่างการตั้งค่าใน .claude/settings.json ที่เพิ่มหนึ่งบรรทัดลงในบันทึกหลังทุกการเรียก Bash, Edit หรือ Write:

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

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — หนึ่งบรรทัด JSON ต่อหนึ่งการกระทำ
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

รูปแบบ JSONL (หนึ่ง record JSON ต่อหนึ่งบรรทัด) สะดวกเพราะกรองด้วย jq ได้ง่าย และนำเข้าระบบวิเคราะห์ใดก็ได้ นอกจากนี้ Claude Code เก็บประวัติเซสชันฉบับเต็มไว้ในเครื่องที่ไดเรกทอรี ~/.claude/projects/ ซึ่งเปิดดูได้เมื่อต้องการดูเหตุผลและผลลัพธ์ทั้งหมด แต่สำหรับสถิติ บันทึกของคุณเองที่กระชับกว่าใช้งานสะดวกกว่า

Trace: หนึ่ง trace ต่อเซสชัน และ span ต่อหนึ่งงาน

เมื่อมี agent หลายตัวหรือทำงานตามตาราง บันทึกข้อความอย่างเดียวไม่พอ ต้องการข้อมูลรวม ตรงนี้เครื่องมือ distributed tracing ทั่วไปและมาตรฐาน OpenTelemetry มีประโยชน์

• Trace คือหนึ่งเซสชันของ agent
• Span คือหนึ่งงานภายในเซสชัน
• Span ซ้อนกัน คือขั้นตอนการตรวจสอบ เช่น build เทสต์ และ e2e

แอตทริบิวต์ขั้นต่ำของ span ได้แก่ รหัสฟีเจอร์และเซสชัน โมเดล ผลการตรวจ โทเคน และจำนวนการลองซ้ำ ข้อมูลเหล่านี้อ่านได้ใน Jaeger, Grafana Tempo, Honeycomb และตอบคำถามที่มองไม่เห็นในเซสชันเดียว เช่น งานประเภทไหนต้องลองซ้ำบ่อย agent ใช้โทเคนไปกับอะไรมากที่สุด หรือหลังการเปลี่ยนแปลงฮาร์เนสครั้งไหนอัตราการยอมรับงานลดลง Claude Code มีการส่งออกเมตริกและเหตุการณ์ผ่าน OpenTelemetry ในตัว ซึ่งเปิดใช้ด้วยตัวแปรสภาพแวดล้อม รายละเอียดดูในเอกสารของเครื่องมือ

Commit เป็นบันทึกงาน

บันทึกงานที่ถูกที่สุดและเชื่อถือได้ที่สุดคือ git ที่คุณมีอยู่แล้ว เพียงต้องทำให้อ่านได้

1. หนึ่ง commit ต่อหนึ่งงาน เพื่อให้ git log ตรงกับรายการงานที่ทำ และการย้อนงานหนึ่งงานทำได้ด้วย git revert เพียงครั้งเดียว
2. ข้อความบอกว่าเปลี่ยนอะไรและตรวจอย่างไร ไม่ใช่ "fix" แต่เป็น "เปลี่ยนอะไร ทำไม ตรวจด้วยคำสั่งอะไร"
3. commit เฉพาะหลังการตรวจผ่าน ทำให้ทุกจุดในประวัติคือสถานะที่ใช้งานได้ และ git bisect หาต้นเหตุได้

fix(payments): ปัดเศษส่วนลดเป็นสตางค์

ส่วนลดถูกคำนวณด้วย float ที่ยอด 999.99 สตางค์หายไป
เปลี่ยนการคำนวณเป็นจำนวนเต็มในหน่วยสตางค์
ตรวจแล้ว: make test (142 passed), make e2e checkout — ผ่าน
นอกขอบเขต: การปัดเศษในรายงาน บันทึกไว้ใน BACKLOG.md

รายงานของ agent: หลักฐานแทนความรู้สึก

ข้อความสุดท้ายของ agent ก็เป็นสิ่งประกอบของ observability ได้ ถ้ามีรูปแบบคงที่ ควรกำหนดเทมเพลตไว้ใน AGENTS.md หรือ CLAUDE.md:

## รายงานเมื่อจบงาน
- ทำอะไรไปแล้ว: รายการการเปลี่ยนแปลง (ไฟล์ — สาระ)
- ตรวจอย่างไร: คำสั่งที่แน่นอนและผลลัพธ์
- อะไรที่ยังไม่ได้ตรวจ และเพราะอะไร
- ส่วนที่เบี่ยงจากข้อตกลงงาน
- คำถามที่ยังเปิดอยู่ถึงคน

กฎหลักคือทุกข้อความต้องอ้างถึงหลักฐาน ได้แก่ ไฟล์และบรรทัด ผลของเทสต์ หรือรายการในบันทึก "ดูดีอยู่" และ "น่าจะโอเค" ไม่นับเป็นรายงาน ข้อ "อะไรที่ยังไม่ได้ตรวจ" มีค่ามาก เพราะแสดงขอบเขตของความมั่นใจอย่างซื่อตรง

ข้อตกลงก่อนเขียนโค้ด และ rubric หลังทำงาน

ชั้น process เริ่มก่อนลงมือทำ ข้อตกลงงานสั้นๆ (sprint contract) ระบุขอบเขต เกณฑ์ตรวจรับ ส่วน "นอกขอบเขต" และคำถามที่คนต้องตัดสิน ส่วน "นอกขอบเขต" ช่วยป้องกันการโต้เถียงเรื่องผลลัพธ์ได้ครึ่งหนึ่ง

หลังทำงาน ผลลัพธ์ควรถูกประเมินตาม rubric ไม่ใช่ตามความรู้สึก มิฉะนั้นผู้ตรวจสองคนที่มีประสบการณ์จะให้คำตัดสินต่างกัน และการประเมินจะกลายเป็นการสุ่ม

แต่ละมิติให้คะแนนเป็น A/B/C/D และคะแนนที่ไม่มีการอ้างอิงใช้ไม่ได้ กฎตัดสินง่ายๆ คือ D หนึ่งตัวหรือ C สองตัวให้ปฏิเสธพร้อมรายการที่ต้องแก้ ผู้ตรวจที่เป็น agent อีกตัวก็ใช้ rubric เดียวกันนี้ได้

วิธีไล่ดูว่า agent ทำอะไรในเซสชัน

ถ้าไม่มีรายงาน หรือไม่เชื่อรายงาน ให้ไล่ดูหลักฐานตามลำดับนี้

1. สถานะของ working tree: git status ดูว่ามีอะไรที่ยังไม่ commit และมีไฟล์ขยะหรือไม่
2. ประวัติ: git log --stat ตั้งแต่ต้นเซสชัน ดูว่ามี commit และไฟล์อะไรบ้าง
3. ขนาดของการเปลี่ยนแปลง: git diff --stat main...HEAD แล้วดู diff เต็มของไฟล์สำคัญ
4. บันทึกการกระทำ: มีคำสั่งอะไรถูกรันและการตรวจคืนผลอะไร
5. ตรวจซ้ำ: รัน build และเทสต์ด้วยตัวคุณเอง เชื่อผลของคำสั่ง ไม่ใช่คำเล่าของ agent

# คำสั่งที่ agent รันในเซสชันล่าสุด
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# ไฟล์ที่ถูกแก้บ่อยที่สุด
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

ความผิดพลาดที่พบบ่อย

• log ทุกอย่าง บทถอดความเป็นกิกะไบต์ไม่มีใครอ่าน ให้เขียนเฉพาะการกระทำที่มีผลข้างเคียงและผลการตรวจ
• รูปแบบอิสระ ถ้าให้ agent กำหนดรูปแบบ log เอง จะไม่มีสถิติรวม รูปแบบต้องกำหนดโดยฮาร์เนส
• เชื่อรายงานโดยไม่ดูผลคำสั่ง "เทสต์ผ่านหมด" โดยไม่มีผลลัพธ์ เป็นเพียงความเห็น
• ลองซ้ำแบบไม่มีเป้าหมาย ถ้าไม่รู้สาเหตุของความล้มเหลว agent จะแก้มั่วในหลายจุด ให้ต้องการการวินิจฉัยพร้อมลิงก์ไปยัง log ก่อน แล้วค่อยแก้
• "เดี๋ยวค่อยเก็บ" ไฟล์ดีบักและการเปลี่ยนแปลงที่ยังไม่ commit ทำให้เซสชันถัดไปสับสน เพราะแยกไม่ออกว่าอะไรชั่วคราวและอะไรตั้งใจ

สรุป

Observability ของ AI agent ประกอบจากสองชั้น ได้แก่ runtime (บันทึกการกระทำผ่าน hook, trace และ commit ที่อธิบายผลการตรวจ) และ process (ข้อตกลงงานก่อนเขียนโค้ด, rubric และรายงานที่มีหลักฐาน) เมื่อทำได้ คำว่า "เสร็จ" จะมีความหมายเดียวกันทุกเซสชัน และการไล่ดูงานของ agent ใช้เวลาไม่กี่นาที หัวข้อนี้เราอธิบายพร้อมการลงมือทำจริงในคอร์สเกี่ยวกับ harness engineering ผ่านโปรเจกต์ตัวอย่างแบ็กเอนด์ระบบชำระเงิน