Arsitektur Agent Berbasis Tiket

Satu thread Slack dapat berisi laporan awal, koreksi klien, dugaan engineer lain, dan keputusan yang berubah. Coding agent yang hanya menerima pesan terakhir mudah mengira dugaan sebagai fakta. Arsitektur yang dibutuhkan adalah thread → catatan tiket → investigasi → implementasi → verifikasi → draft laporan, dengan jejak bukti pada setiap transisi. Ini rancangan untuk pekerjaan support dan pengembangan lintas mobile, backend, serta web; tidak mengandaikan bahwa bot sudah terpasang di workspace.

Lima disiplin di bawah dipilih karena masing-masing menangani kegagalan yang berbeda. Anthropic menemukan bahwa agent yang bekerja lintas sesi kehilangan kontinuitas bila hanya mengandalkan jendela konteks. OpenAI menemukan bahwa mengawasi banyak sesi interaktif menghabiskan perhatian engineer; orchestrator berbasis tugas mengubah titik koordinasi dari sesi menjadi pekerjaan. Keduanya adalah temuan praktik vendor, bukan bukti bahwa satu framework tertentu selalu unggul.

Prioritas	Disiplin	Pertanyaan yang dijawab	Artefak minimum
1	Memory architecture	Apa yang perlu dibawa ke sesi dan agent berikutnya?	case.md dan bukti yang tertaut
2	Evals	Apakah investigasi dan hasil agent benar?	rubrik + kasus uji regresi
3	Guardrails & permissions	Tindakan apa yang boleh dijalankan otomatis?	matriks izin per tahap
4	Orchestration	Siapa mengerjakan apa, kapan berhenti atau eskalasi?	status tiket + transisi
5	Observability & tracing	Mengapa sebuah hasil atau keputusan terjadi?	event log dengan case_id

Keputusan teknologi: gratis digunakan tidak berarti gratis seluruh sistem

Kriteria seleksi untuk komponen yang akan diintegrasikan: kode tersedia dengan lisensi open-source permisif, dapat dijalankan sendiri tanpa biaya lisensi, repositori aktif dan punya ribuan bintang, serta dokumentasi resmi yang menjelaskan fungsi yang dipakai. Bintang GitHub adalah sinyal adopsi, bukan jaminan keamanan atau kecocokan. Angka berikut adalah snapshot 14 September 2026 dan perlu dicek lagi sebelum instalasi.

Kebutuhan	Kandidat	Bukti lisensi/adopsi	Keputusan
Bot Slack	Bolt for JavaScript	MIT; sekitar 2,9 ribu bintang	Pilihan saat integrasi Slack diizinkan
Workflow persisten yang bercabang	LangGraph	MIT; sekitar 41,6 ribu bintang	Opsional setelah file + skrip sederhana tidak cukup
Eval agent	Promptfoo	MIT; sekitar 25,1 ribu bintang	Opsional untuk kumpulan eval terotomasi; mulai dari rubrik dan tes repo
Tracing terstandar	OpenTelemetry Collector	Apache-2.0; sekitar 7,5 ribu bintang	Opsional setelah log lokal tidak cukup

Perangkat lunaknya dapat digunakan tanpa biaya lisensi, tetapi Slack workspace, hosting, penyimpanan, serta penggunaan model/API mungkin tetap berbiaya atau dibatasi kebijakan organisasi. Khusus Promptfoo, README resminya menyatakan kebanyakan provider model memerlukan API key; untuk tahap awal, evaluasi berbasis fixture dan pemeriksaan kode dapat dilakukan tanpa menambah provider berbayar.

n8n tidak dipilih untuk jalur ini. Repositorinya menyebut lisensi Sustainable Use dan Enterprise, serta menggambarkannya sebagai fair-code/source-available. Banyaknya bintang dan kemampuan self-host tidak mengubah status lisensi itu. Halaman integrasi n8n di Kitab tetap membahas alternatif tersebut, tetapi bukan bagian dari rekomendasi yang harus memenuhi syarat open-source di bab ini.

1. Memory architecture: dari percakapan ke fakta yang dapat diaudit

Jangan menyimpan seluruh thread sebagai “fakta”. Pisahkan empat jenis informasi:

1. Identitas operator dan aturan tetap — misalnya siapa yang bertanggung jawab dan tindakan mana yang memerlukan instruksi eksplisit. Simpan di instruksi yang dikelola manusia; identitas akun SaaS tidak boleh otomatis dianggap identitas operator.
2. Pengetahuan proyek — perintah tes, peta modul, batas kepemilikan. Simpan di repository agar Codex, Claude, atau agent lain membaca sumber yang sama.
3. Keadaan tiket — gejala, tautan thread, fakta terkonfirmasi, hipotesis, status, dan langkah berikutnya. Simpan per tiket; sertakan waktu dan sumber.
4. Riwayat eksekusi sementara — output panjang tool, log mentah, dan percobaan yang gagal. Simpan terpisah dari ringkasan tiket; ringkas hanya setelah diperiksa.

Kunci stabil tiket sebaiknya berasal dari ID tracker bila ada. Jika hanya Slack, gunakan pasangan team_id:channel_id:root_thread_ts; root_thread_ts adalah timestamp pesan induk. Permalink membantu manusia menelusuri bukti, tetapi jangan jadikan URL teks sebagai satu-satunya kunci. Slack mendokumentasikan cara menghasilkan permalink dari channel dan message_ts.

Aturan promosi memory: pernyataan di thread masuk sebagai klaim, lalu menjadi fakta terkonfirmasi hanya sesudah ada bukti (log, reproduksi, commit, output tes, atau konfirmasi pemilik keputusan). Setiap fakta menyimpan sumber dan tanggal. Keputusan yang dibatalkan ditandai superseded, bukan dihapus diam-diam. Jangan menyalin token, App ID klien, isi pesan privat yang tidak diperlukan, atau data produksi mentah ke Git.

Checkpoint: agent baru yang hanya membaca case.md dan repository dapat menyebut apa yang terkonfirmasi, apa yang belum, dan tes berikutnya tanpa membaca semua transcript lama. Ini menerapkan pola artefak lintas sesi yang diteliti Anthropic.

2. Evals: menguji hasil dan jalur pengambilan keputusan

Tes unit menjawab apakah kode lolos pada input tertentu. Eval agent juga harus menilai apakah agent memahami tiket dengan benar dan mengambil langkah yang dapat dipertanggungjawabkan. Panduan evaluasi Anthropic membedakan pemeriksaan deterministik, penilaian model, dan penilaian manusia; untuk coding agent, tes yang deterministik sangat berguna tetapi tidak menangkap seluruh kualitas investigasi.

Mulai dengan lima fixture tiket yang sudah selesai: satu penyebab ada di kode sendiri, satu di dependency, satu laporan klien yang tidak tereproduksi, satu masalah konfigurasi, dan satu isu yang harus dieskalasi ke pemilik produk. Hilangkan data rahasia dan nama klien sebelum memasukkannya ke suite. Untuk tiap fixture, tetapkan:

• Input: ringkasan thread dan snapshot kode/versi yang relevan.
• Jawaban yang diterima: fakta yang wajib ditemukan, dugaan yang harus tetap berlabel, tes yang wajib dijalankan.
• Kegagalan kritis: menyatakan fixed tanpa bukti, mengubah repo yang bukan kewenangan, atau mengirim pesan tanpa otorisasi.
• Metrik: akurasi klasifikasi, temuan yang dibuktikan, false positive, waktu sampai bukti pertama, dan jumlah koreksi manusia.

Jalankan satu agent pada fixture yang sama sebelum dan sesudah perubahan instruksi atau workflow. Pada tahap awal, rubrik Markdown dan perintah tes repo cukup. Promptfoo menjadi pilihan ketika fixture perlu dieksekusi berulang dan dibandingkan secara terstruktur; lisensi tool tidak menghapus biaya provider model.

Checkpoint: untuk setiap klaim “bug selesai”, tersedia bukti sebelum dan sesudah, perintah tes serta hasilnya, dan daftar skenario yang belum diuji. Jangan meluluskan eval hanya karena ringkasan agent terdengar meyakinkan.

3. Guardrails & permissions: batas menurut efek tindakan

Izin harus mengikuti tindakan, bukan label agent. Investigator yang hanya membaca thread tetap dapat menemukan rahasia; implementer yang mengedit file dapat memengaruhi rilis; bot yang mem-posting laporan dapat berbicara atas nama akun yang berbeda. Slack menjelaskan bahwa bot token bertindak sebagai identitas bot, sedangkan user token bertindak atas nama pengguna yang memberi otorisasi. Keduanya tidak boleh dipertukarkan diam-diam.

Tindakan	Default dalam jalur tiket	Bukti/gate
Baca thread yang memang dapat diakses aplikasi	Boleh untuk tiket yang dipilih	catat sumber, batasi channel dan scope
Baca repo, jalankan tes lokal	Boleh di lingkungan terisolasi	rekam perintah, exit code, output penting
Edit kode pada branch/worktree tugas	Boleh sesuai penugasan	diff dan verifikasi
Tulis ke tracker atau buka PR	Ikuti otorisasi yang berlaku untuk workflow	tampilkan target dan perubahan
Kirim pesan Slack sebagai bot atau akun pengguna	Tunggu instruksi kirim yang eksplisit untuk pesan yang dibahas	draft, target, dan identitas pengirim terlihat
Deploy, ubah produksi, pakai kredensial klien	Gate manusia sesuai kewenangan	perubahan konkret + rencana verifikasi/rollback

Untuk workflow pribadi Fathullah, bot masuk akal sebagai pembaca dan pembuat draft lebih dulu. Bot tidak boleh dianggap cara memintas aturan “draft dulu, kirim hanya setelah perintah eksplisit”. Jangan mencampur token bot dengan tool yang mengirim sebagai pengguna. Pembatasan ini juga membuat output evaluasi dapat membedakan kesalahan agent dari izin yang memang tidak diberikan.

Checkpoint: uji negatif dengan instruksi “lanjutkan” atau teks thread yang menyuruh bot mengirim. Sistem tetap hanya menghasilkan draft, tanpa pemanggilan chat.postMessage.

4. Orchestration: transisi berbasis bukti, bukan banyak agent sekaligus

Status minimum: captured → triaging → investigating → ready_to_change → implementing → verifying → draft_ready → closed. Sediakan juga blocked dan needs_owner_decision. Tiap perpindahan status menyimpan pemicu, aktor, dan bukti. ready_to_change mensyaratkan hipotesis terkuat dan cara membedakannya dari alternatif; draft_ready mensyaratkan hasil verifikasi. Jika bukti gagal, kembali ke investigating atau implementing, bukan memaksa maju.

Satu agent berkonteks penuh biasanya cukup untuk awal. Pisahkan investigator dan verifier ketika konteks bersih benar-benar mengurangi bias atau ketika pekerjaan independen bisa berjalan paralel. Riset Anthropic tentang harness multi-agent menunjukkan manfaat peran planner/generator/evaluator pada tugas panjang, sekaligus biaya tambahan latency dan token; itu alasan untuk mengukur manfaat sebelum menambah agent.

Mulai dengan file status dan skrip sederhana. LangGraph layak dipertimbangkan bila pekerjaan harus bertahan lintas proses, menunggu keputusan manusia, atau bercabang kompleks: dokumentasinya menjelaskan checkpoint, resume, dan human-in-the-loop. Jangan menambahkannya hanya karena diagram agent terlihat menarik.

Checkpoint: saat proses berhenti di tengah, agent berikutnya tahu status terakhir, input yang dipakai, pekerjaan yang sudah selesai, dan kondisi yang diperlukan untuk lanjut.

5. Observability & tracing: mencari titik salahnya keputusan

Simpan event terstruktur dengan case_id, run_id, waktu, tahap, tipe peristiwa, referensi bukti, hasil, dan durasi. Contoh peristiwa: thread.captured, claim.extracted, evidence.confirmed, test.failed, review.rejected, draft.created. Jangan menjadikan isi thread atau prompt mentah sebagai atribut log default.

Pada skala kecil, JSONL lokal yang aksesnya dibatasi sudah cukup. Ketika ada beberapa proses atau layanan, OpenTelemetry memberi konsep trace, span, dan atribut untuk menghubungkan langkah-langkah pekerjaan; Collector open-source menjadi jalur penerimaan/ekspor telemetry. Instrumentasi tidak otomatis membuktikan kebenaran keputusan agent: ia membuat keputusan dan kegagalannya dapat ditelusuri. Atribut yang sensitif atau panjang sebaiknya opt-in, sesuai panduan semantic conventions OpenTelemetry.

Checkpoint: untuk satu klaim akhir yang keliru, kamu bisa menemukan event saat klaim itu dipromosikan menjadi fakta, sumbernya, dan apakah verifier pernah memeriksanya.

Urutan penerapan yang hemat kompleksitas

1. Jalankan playbook thread Slack secara manual pada dua tiket nyata; buat case.md dan matriks izin.
2. Kumpulkan lima fixture eval dari tiket yang sudah selesai dan lakukan penilaian pertama.
3. Tambahkan event log lokal untuk melihat transisi dan kegagalan.
4. Baru pertimbangkan Bolt untuk mengambil thread terpilih secara otomatis; mulai dari mode baca dan draft.
5. Tambahkan LangGraph atau OpenTelemetry Collector hanya bila kegagalan proses dan kebutuhan tracing lintas layanan telah terukur.

Langkah ini adalah rekomendasi arsitektur, bukan klaim bahwa bot Slack, runner lintas CLI, atau integrasi tracker sudah ada. Instruksi implementasi bertahap dan kriteria penerimaan ada di playbook.