Perlukah agen AI mencatat progres kerja panjang? Desain heartbeat

Hal paling menegangkan dari tugas AI yang panjang bukan selalu kegagalan. Sering kali justru diamnya.

Seseorang bisa selesai membereskan rumah, belanja, makan, lalu kembali dan AI masih terlihat “sedang bekerja”. Ada dua kemungkinan yang sangat berbeda:

1. AI sedang menjalankan test suite besar dengan serius.
2. AI sudah macet beberapa jam lalu.

Spinner tidak cukup untuk membedakan keduanya. Tidak adanya commit juga bukan bukti berhenti; testing, investigasi, perbandingan, generasi, atau menunggu sistem eksternal bisa lama tanpa artefak baru.^[1]

Karena itu AI yang berjalan lama membutuhkan sesuatu selain kecerdasan: observability.

1. Kesimpulan――jika tugas bisa berlangsung lama, tampilkan posisi saat ini

Agen jangka panjang sebaiknya tidak hanya memberi laporan akhir. Status antara juga harus bisa dibaca.^[1]

Tidak perlu setiap menit berkata “masih hidup”. Yang penting kita bisa mengetahui:

• sedang mengerjakan apa
• apa yang sudah selesai
• apa yang masih tersisa
• apakah sedang testing
• apakah ada blocker
• kapan terakhir liveness dikonfirmasi
• kapan terakhir ada perubahan material

Salah satu contoh konfigurasi praktis adalah memperbarui Heartbeat setelah sekitar 10 menit tanpa artefak terlihat, lalu membaca Heartbeat yang lebih tua dari 20 menit sebagai STALE_UNKNOWN, bukan langsung “berhenti”.^[1]

Diam berarti “belum tahu” sebelum berarti “gagal”.

2. Mengapa riwayat commit saja tidak cukup

Commit Git sangat bagus sebagai bukti perubahan material, tetapi lemah sebagai satu-satunya bukti aktivitas saat ini.

Regression test selama satu jam bisa berjalan sehat tanpa satu commit pun. Sebaliknya, commit file Heartbeat yang tidak penting setiap sepuluh menit hanya membuat histori berisik.^[1]

Pisahkan:

Heartbeat = status sekarang Material change = bukti bahwa kode, kontrak, artefak, atau verifikasi benar-benar berubah

Dengan lastHeartbeatAt dan lastMaterialChangeAt terpisah, kita bisa memahami “30 menit tanpa commit, tetapi TESTING dikonfirmasi 5 menit lalu”.^[1]

Tujuannya bukan lebih banyak commit. Tujuannya adalah membuat diam bisa ditafsirkan.

3. Apa yang minimal perlu dicatat?

Untuk run yang panjang, field berikut sangat berguna:^[1]

• runId
• state: RUNNING / BLOCKED / COMPLETED / STALE_UNKNOWN, dll.
• phase: READING / IMPLEMENTING / TESTING / VERIFYING, dll.
• workingOn
• startedAt
• lastHeartbeatAt
• lastMaterialChangeAt
• branch / baseSha / headSha / PR
• completedMilestones / remainingMilestones
• blockers
• tests
• nextCheckpoint

Dengan begitu tugas enam jam tidak lagi menjadi “kotak hitam enam jam”, tetapi bisa dibaca sebagai:

IMPLEMENTING → TESTING → INTEGRATING → VERIFYING

Kotak hitam yang sangat pintar tetaplah kotak hitam. Setelah beberapa jam, itu mulai bikin gelisah.

4. Saat testing, Heartbeat paling penting

Test panjang terlihat hampir sama dengan agen yang membeku.

Sebelum test panjang, catat:^[1]

• phase = TESTING
• nama test
• cakupan
• angka objektif seperti 84 / 127 jika totalnya tetap
• apakah failure sudah muncul

Hindari persentase khayalan seperti “82% selesai” untuk desain atau debugging. Tidak ada yang benar-benar tahu isi 18% sisanya.

Persentase masuk akal hanya jika penyebutnya tetap:

• 84 / 127 tests
• 3 / 5 acceptance gates

“Implementasi 82% selesai” adalah versi AI dari “sudah hampir sampai” dari orang yang mungkin masih di rumah.

5. Baca “apakah berhenti?” secara bertahap

Salah satu kebijakan Heartbeat praktis dapat mengklasifikasikan umur seperti ini:^[1]

Umur Heartbeat	Interpretasi
0–10 menit	CURRENT
10–20 menit	HEARTBEAT_OVERDUE
Lebih dari 20 menit	STALE_UNKNOWN

STALE_UNKNOWN bukan FAILED.

Kemudian periksa berurutan:

1. catatan progres saat ini
2. Check / Status
3. branch / PR
4. commit terbaru
5. inferensi terakhir

Jika Heartbeat lama tetapi kemudian muncul PR atau commit baru, kemungkinan agen terus bekerja dan hanya lupa memperbarui status.

AI juga bisa mengalami: pekerjaan selesai, timesheet lupa diisi.

6. Kesalahan progres yang perlu dihindari

Jangan menumpuk commit Heartbeat di main

Itu mengotori histori, menambah konflik, dan bisa memicu CI/deploy yang tidak perlu. Gunakan surface ringan yang dapat diperbarui seperti Issue comment, Check, Status, atau area ops non-produksi.^[1]

Jangan membuat komentar baru untuk setiap Heartbeat

Satu record yang dapat diperbarui per run jauh lebih mudah dibaca. Komentar baru setiap sepuluh menit berubah menjadi arkeologi.^[1]

Jangan menyamakan diam dengan gagal

Jika Heartbeat hanya basi, gunakan STALE_UNKNOWN. Kegagalan harus didukung bukti kegagalan yang nyata.^[1]

Jangan masukkan rahasia ke log progres

Tidak ada API key, token, password, URL privat, chat privat mentah, data pribadi, atau isi file rahasia.^[1]

Jangan hentikan pekerjaan aman hanya karena kanal observability rusak

Jika API progres gagal, fallback ke sink lain dan lanjutkan pekerjaan independen yang masih aman.^[1]

7. Template praktis

State: RUNNING
Phase: TESTING

Run ID: agent-20260916-long-task
Started: 10:00
Last heartbeat: 14:05
Last material change: 13:42

Branch: feat/long-task
Head SHA: abc1234
PR: #123

Working on:
- regression tests

Completed:
- runtime implementation
- contract update

Remaining:
- regression completion
- merge verification
- production readback

Blockers:
- none

Tests:
- 84 / 127 passed so far
- no failure observed

Next checkpoint:
- finish regression, then integration

Dengan informasi ini, “apakah berhenti?” berubah menjadi “oh, sedang testing”.

Tujuan visibility bukan terutama untuk mendesak AI. Tujuannya menghindari restart, interupsi, dan instruksi ganda akibat manusia tidak tahu keadaan sebenarnya.

8. Ringkasan――rancang kecerdasan dan keterlihatan secara terpisah

Untuk AI jangka panjang, bedakan:^[1]

• tidak ada commit ≠ berhenti
• ada Heartbeat ≠ ada progres material
• Heartbeat basi ≠ gagal
• satu blocker ≠ seluruh sistem berhenti
• diam saat testing ≠ tertidur

Jika AI bisa bekerja enam jam, manusia seharusnya tidak perlu menontonnya enam jam.

Desain yang lebih baik adalah: saat kita kembali mengecek, kita langsung tahu posisinya.

Agen jangka panjang ideal bukan agen yang terus bicara.

Ia bekerja dengan tenang, tetapi saat dilihat, posisinya jelas.

---

1. docs/article-pipeline/agent-work-observability.md — internal operational design for long-running AI progress observability, heartbeat cadence, stale classification, testing visibility, privacy, concurrency, and terminal conditions. Updated 2026-09-15