Harness Handbook: Cara Baru Membuat AI Agent Lebih Mudah Dipahami dan Dikembangkan
Irfan Mulyana
July 24, 2026 12:31 am
.
9 min read
AI agent tidak hanya ditentukan oleh kecanggihan model bahasa yang digunakan. Di baliknya ada agent harness, yaitu sistem yang merakit prompt, mengelola state, memanggil tools, menangani error, dan mengatur alur eksekusi. Bagian inilah yang sering membuat pengembangan agent menjadi rumit.
Sebuah paper terbaru berjudul Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable menawarkan pendekatan baru untuk mengatasi masalah tersebut. Para peneliti dari Tencent HY LLM Frontier dan beberapa universitas memperkenalkan Harness Handbook, dokumentasi berbasis perilaku yang dibuat otomatis dari source code.
Ide utamanya sederhana: developer biasanya memikirkan perubahan dalam bentuk perilaku, sedangkan repository diorganisasi dalam bentuk file, fungsi, dan modul. Harness Handbook menjadi jembatan di antara keduanya.
Apa Itu Agent Harness?
Agent harness adalah lapisan perangkat lunak yang mengubah model bahasa menjadi sistem agent yang dapat bekerja. Model menghasilkan prediksi atau respons, sementara harness menentukan bagaimana model menerima konteks, memilih tools, menyimpan informasi, dan melanjutkan proses hingga tugas selesai.
Komponen harness umumnya meliputi:
- konstruksi system prompt dan user prompt;
- pengelolaan memory, scratchpad, dan state;
- pemilihan serta eksekusi tools;
- parsing hasil model;
- mekanisme retry dan penanganan error;
- kondisi berhenti pada agent loop;
- koordinasi antaragent atau subagent.
Kemampuan sebuah AI agent karena itu tidak dapat dinilai hanya dari foundation model. Dua agent yang memakai model sama bisa memiliki performa berbeda karena desain harness yang berbeda.
Masalah muncul ketika harness terus berkembang. Perubahan API, model, environment, dan kebutuhan produk menuntut developer memperbarui berbagai bagian sistem. Satu perilaku yang terlihat sederhana dapat tersebar di banyak file dan tahapan eksekusi.
Mengapa Memodifikasi Agent Harness Sulit?
Permintaan perubahan biasanya ditulis dalam bahasa perilaku. Contohnya, “tambahkan retry saat tool mengalami timeout” atau “pastikan memory diringkas sebelum context window penuh.” Namun, repository tidak disusun berdasarkan kalimat tersebut.
Implementasi retry mungkin berada di executor, konfigurasi, state manager, logger, dan test. Mekanisme memory bisa tersebar di prompt builder, message store, summarizer, serta loop utama. Developer harus menemukan semua lokasi yang terkait sebelum membuat perubahan.
Paper tersebut menyebut proses ini sebagai behavior localization, yaitu menemukan bagian source code yang secara bersama-sama membentuk perilaku tertentu.
Code search dan repository indexing memang membantu, tetapi keduanya masih bergantung pada kecocokan istilah. Pencarian dapat gagal ketika nama fungsi tidak sama dengan bahasa yang digunakan dalam permintaan. Long-context model juga belum sepenuhnya menyelesaikan masalah karena memasukkan lebih banyak source code tidak otomatis membuat hubungan antarkomponen menjadi jelas.
Mengenal Harness Handbook
Harness Handbook adalah representasi repository yang berorientasi pada perilaku sistem. Handbook ini disintesis secara otomatis melalui kombinasi analisis program statis dan penyusunan struktur dengan bantuan LLM.
Berbeda dari dokumentasi biasa yang mengikuti urutan file, Harness Handbook mengorganisasi pengetahuan berdasarkan cara sistem bekerja. Setiap perilaku dihubungkan kembali ke source code yang mengimplementasikannya.
Strukturnya memiliki tiga tingkat:
| Tingkat | Isi | Tujuan |
|---|---|---|
| Level 1 | Gambaran sistem, arsitektur, dan model eksekusi | Memahami harness secara menyeluruh |
| Level 2 | Tahapan eksekusi serta komponen utama | Menentukan area yang relevan dengan perubahan |
| Level 3 | Perilaku detail beserta fungsi dan lokasi source | Menemukan bagian yang perlu diedit |
Pada level paling detail, sebuah entri dapat mencakup tujuan perilaku, kondisi pemicu, input, langkah pemrosesan, output, state terkait, kasus khusus, fungsi penting, konfigurasi, dan contoh.
Struktur tersebut membuat handbook berfungsi seperti peta perilaku, bukan sekadar daftar simbol dalam repository.
Bagaimana Handbook Dibuat?
Pembuatan Harness Handbook dimulai dari source code yang ada. Sistem melakukan analisis statis untuk memperoleh fakta-fakta seperti fungsi, class, call graph, import, serta hubungan antarbagian program.
Setelah itu, LLM membantu menyusun fakta teknis menjadi dokumentasi berjenjang. Prosesnya secara umum terdiri dari beberapa tahap:
- Menginventarisasi unit kerja dalam repository.
- Mengelompokkan fungsi berdasarkan tahapan eksekusi.
- Membuat ringkasan perilaku untuk file atau unit kode.
- Menyusun hierarki dari gambaran sistem hingga perilaku detail.
- Menautkan setiap penjelasan ke lokasi source code terkait.
Pendekatan ini tetap menggunakan source code sebagai sumber kebenaran. LLM tidak diminta menebak arsitektur dari nol, melainkan menyusun hasil analisis menjadi representasi yang dapat dinavigasi manusia dan coding agent.
Behavior-Guided Progressive Disclosure
Paper tersebut juga memperkenalkan Behavior-Guided Progressive Disclosure atau BGPD. Metode ini membantu coding agent menemukan lokasi perubahan secara bertahap, dari informasi tingkat tinggi menuju detail implementasi.
Alurnya dapat diringkas sebagai berikut:
- Agent menerima permintaan perubahan.
- Agent membaca gambaran sistem dan tahapan eksekusi yang relevan.
- Agent menelusuri perilaku detail serta state yang saling terhubung.
- Handbook mengarahkan agent ke kandidat file dan fungsi.
- Kandidat tersebut diverifikasi terhadap source code terbaru.
- Bukti yang ditemukan digunakan untuk membuat edit plan.
Progressive disclosure mencegah agent membaca seluruh repository sekaligus. Informasi hanya dibuka ketika relevan dengan perilaku yang sedang dicari. Hal ini menghemat token sekaligus mengurangi distraksi dari source code yang tidak berhubungan.
Handbook Tetap Sinkron Setelah Kode Berubah
Dokumentasi otomatis tetap berisiko usang jika source code terus berubah. Karena itu, workflow yang ditawarkan paper ini menyertakan mekanisme resynchronization.
Setelah executor menerapkan edit, sistem memeriksa diff. Jika ada perubahan, handbook diperbarui agar kembali sesuai dengan kondisi repository. Mode representasi yang digunakan sebelumnya dipertahankan supaya struktur dokumentasi tetap konsisten.
Siklus lengkapnya menjadi:
lokalisasi perilaku → pembuatan rencana → eksekusi perubahan → pemeriksaan diff → sinkronisasi handbook.
Mekanisme ini penting karena dokumentasi yang salah bisa lebih berbahaya daripada tidak memiliki dokumentasi sama sekali. Verifikasi kandidat terhadap source code aktual juga tetap dilakukan sebelum rencana edit dibuat.
Hasil Eksperimen
Peneliti menguji metode ini pada permintaan modifikasi realistis dari dua agent harness open source, yaitu Codex dan Terminus-2. Mereka membandingkan pendekatan baseline dengan perencanaan yang dibantu Harness Handbook.
Hasilnya menunjukkan tiga pola utama.
1. Kualitas Rencana Meningkat
Win rate keseluruhan meningkat 10 poin persentase pada Codex dan 18,9 poin pada Terminus-2. Perbaikan terlihat pada tiga aspek penilaian: ketepatan lokasi, pengendalian cakupan perubahan, dan kualitas reasoning.
Manfaatnya tidak hanya muncul pada tugas sederhana. Seluruh perbandingan berdasarkan jenis permintaan menunjukkan keuntungan bagi pendekatan Handbook-Assisted, dengan peningkatan sekitar 16,3 hingga 33,3 poin persentase.
2. Penggunaan Token Menurun
Kualitas yang lebih baik tidak diperoleh dengan memasukkan lebih banyak konteks. Rata-rata token planner justru turun:
| Harness | Baseline | Dengan Handbook | Penurunan |
|---|---|---|---|
| Codex | 0,102 juta token/request | 0,089 juta | 12,7% |
| Terminus-2 | 0,058 juta token/request | 0,053 juta | 8,6% |
Hasil ini memperkuat argumen bahwa konteks yang terstruktur lebih berguna daripada konteks yang sekadar besar.
3. Planner yang Lebih Lemah Menjadi Lebih Akurat
Peneliti juga membandingkan lokasi edit yang diprediksi planner dengan reference plan dari model yang lebih kuat. Semua 24 perbandingan recall, precision, dan F1 pada tingkat file serta simbol meningkat.
Kenaikan F1 berada pada rentang 5 hingga 18,8 poin. Pada Terminus-2, handbook membantu planner mencapai F1 tingkat file hingga 89,3% dan F1 tingkat simbol hingga 89,3%, tergantung model referensi yang digunakan.
Jumlah kegagalan total, yaitu rencana yang tidak memiliki overlap sama sekali dengan referensi, juga turun hingga 25,9 poin pada beberapa kondisi.
Baca juga:
Mengapa Pendekatan Ini Penting?
Agentic coding sering dipandang sebagai persoalan menghasilkan patch. Padahal, sebelum menulis kode, agent harus menjawab pertanyaan yang lebih mendasar: bagian mana yang harus diubah?
Jika lokalisasi salah, kode yang dihasilkan tetap berisiko gagal meskipun sintaksnya benar. Agent mungkin mengubah satu fungsi tetapi melewatkan konfigurasi, state transition, atau jalur error yang terkait.
Harness Handbook memisahkan proses pemahaman dari proses eksekusi. Planner memperoleh peta perilaku yang terhubung ke source code, lalu executor bekerja berdasarkan rencana yang sudah memiliki bukti.
Pendekatan ini relevan untuk repository yang memiliki karakteristik berikut:
- perilaku tersebar di banyak modul;
- nama fungsi tidak selalu menggambarkan kebutuhan produk;
- jalur eksekusi tertentu jarang digunakan;
- banyak state dibagikan antarstage;
- perubahan sering menyentuh lebih dari satu file;
- dokumentasi manual sulit dipertahankan.
Potensi Penerapan di Proyek Nyata
Konsep Harness Handbook tidak harus terbatas pada framework AI agent. Representasi berbasis perilaku dapat diterapkan pada sistem yang memiliki alur kompleks, seperti workflow automation, layanan backend modular, platform plugin, dan pipeline data.
Dalam proyek AI agent, handbook dapat dipakai untuk beberapa kebutuhan:
Onboarding Developer
Developer baru dapat memahami alur agent dari gambaran sistem menuju perilaku spesifik tanpa membaca seluruh repository secara acak.
Perencanaan Perubahan
Sebelum coding dimulai, tim dapat mengidentifikasi file, fungsi, state, dan konfigurasi yang kemungkinan terdampak.
Code Review
Reviewer memperoleh konteks mengenai perilaku yang ingin diubah serta alasan setiap lokasi masuk ke dalam diff.
Pemeliharaan oleh Coding Agent
Coding agent dapat menavigasi repository dengan konteks yang lebih kecil tetapi lebih relevan. Ini berpotensi menurunkan biaya inference dan mengurangi edit yang melenceng dari scope.
Dokumentasi yang Diperbarui Otomatis
Resynchronization membuat dokumentasi dapat mengikuti perubahan source code tanpa seluruh proses harus dilakukan secara manual.
Keterbatasan yang Perlu Diperhatikan
Hasil paper ini menjanjikan, tetapi bukan berarti masalah pemeliharaan repository sudah selesai sepenuhnya.
Pertama, kualitas handbook tetap bergantung pada kemampuan analisis statis dan LLM dalam menyusun fakta. Perilaku dinamis, runtime injection, konfigurasi eksternal, atau efek dari layanan pihak ketiga mungkin tidak seluruhnya terlihat dari source code.
Kedua, eksperimen dilakukan pada dua harness open source. Diperlukan evaluasi lebih luas untuk mengetahui seberapa baik pendekatan ini bekerja pada repository dengan bahasa, ukuran, dan arsitektur berbeda.
Baca juga:
Ketiga, kualitas lokalisasi tidak menjamin patch akhir selalu benar. Testing, review, dan validasi runtime tetap diperlukan. Handbook membantu menunjukkan tempat yang perlu diperiksa, bukan menggantikan seluruh proses rekayasa perangkat lunak.
Keempat, sinkronisasi dokumentasi harus dirancang dengan disiplin. Jika proses pembaruan gagal atau tidak berjalan setelah perubahan tertentu, handbook berpotensi menyajikan informasi yang sudah tertinggal.
Pelajaran Utama untuk Pengembang AI Agent
Ada beberapa pelajaran praktis yang dapat diambil dari penelitian ini.
Pertama, dokumentasi agent sebaiknya menjelaskan perilaku, bukan hanya struktur folder. Daftar file belum tentu menunjukkan bagaimana prompt, state, tools, dan loop saling berinteraksi.
Kedua, context window besar bukan solusi tunggal. Informasi yang dipilih berdasarkan relevansi sering lebih efektif daripada memasukkan seluruh repository.
Ketiga, proses perencanaan perlu memiliki bukti source code. Setiap kandidat edit sebaiknya diverifikasi terhadap implementasi terbaru sebelum executor mulai bekerja.
Keempat, dokumentasi perlu masuk ke dalam lifecycle perubahan. Jika dokumentasi hanya dibuat sekali, nilainya akan cepat menurun pada proyek yang berkembang aktif.
Terakhir, performa coding agent tidak hanya bergantung pada model. Representasi repository, mekanisme retrieval, tool orchestration, dan proses verifikasi sama pentingnya dengan kemampuan generasi kode.
Kesimpulan
Harness Handbook menawarkan cara baru untuk memahami dan memodifikasi sistem AI agent yang kompleks. Alih-alih memaksa developer atau coding agent menerjemahkan permintaan perilaku menjadi lokasi source code secara manual, pendekatan ini membangun peta yang menghubungkan keduanya.
Eksperimen menunjukkan bahwa handbook berbasis perilaku dapat meningkatkan kualitas rencana, menurunkan konsumsi token, dan membantu planner yang lebih lemah mendekati reference plan dari model yang lebih kuat. Keuntungan terbesar terlihat pada perubahan lintas modul, jalur yang jarang dijalankan, dan permintaan yang sulit ditemukan melalui keyword search.
Pesan terpenting dari penelitian ini jelas: tantangan utama dalam mengembangkan agent bukan hanya menghasilkan edit, tetapi menemukan semua lokasi yang benar sebelum edit dilakukan.
Sumber: Ruhan Wang dkk., Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable, arXiv:2607.13285. https://arxiv.org/abs/2607.13285