Harness Engineering untuk AI Agent: Kenapa Prompt Bagus Belum Cukup

Sebuah coding agent menerima prompt yang sangat rinci: reproduksi bug, perbaiki komponen, jalankan test, lalu buka pull request. Ia mengubah kode dengan benar, tetapi test tidak pernah benar-benar dijalankan karena environment tidak bisa boot. Screenshot yang dipakai berasal dari build lama. Pull request tetap dibuat dan statusnya dilaporkan selesai.

Ini bukan kegagalan copywriting prompt. Agent tidak punya lingkungan yang cukup untuk melihat, membuktikan, dan memulihkan pekerjaannya.

Harness engineering adalah pekerjaan merancang shell operasional yang menghubungkan AI agent dengan environment, tools, guardrails, state, feedback, observability, eval, dan proof of completion. Harness membuat intent dapat dieksekusi secara terbatas serta hasilnya dapat diperiksa.

Istilah ini masih emerging, bukan standar formal dengan daftar komponen universal. OpenAI memakai "harness engineering" untuk menjelaskan perubahan kerja saat timnya membangun produk dengan Codex: manusia lebih banyak mendesain environment, scaffolding, dokumentasi, tooling, constraint, dan feedback loop daripada menulis kode langsung. Di artikel ini, definisinya diperluas secara operasional untuk agent di pekerjaan konten, pemasaran, finance, support, dan operasi bisnis.

Kalimat paling praktisnya: prompt menjelaskan pekerjaan; harness membuat pekerjaan itu mungkin, terbatas, terlihat, dan dapat dibuktikan.

Harness bukan wrapper API tipis

Banyak implementasi disebut agent harness padahal isinya hanya fungsi yang mengirim prompt ke model dan meneruskan tool call. Itu orchestrator minimum, belum tentu harness yang siap operasi.

Harness yang matang menangani setidaknya enam tanggung jawab:

1. Environment: tempat agent membaca, menulis, menjalankan, dan mengisolasi pekerjaan.
2. Capability: tools, schema, dokumentasi, dan cara menemukan sumber.
3. Control: permission, policy, approval, budget, timeout, dan sandbox.
4. Feedback: hasil tool, validator, test, linter, reviewer, serta error yang bisa ditindaklanjuti.
5. State and recovery: checkpoint, artifact, idempotency, dan kelanjutan setelah pause atau crash.
6. Proof: evidence yang harus lulus sebelum pekerjaan diberi status selesai.

Loop dan graph dapat berjalan di dalam harness. Prompt dan context dirakit pada setiap model call. Hubungan ini dijelaskan di artikel hub Lima Lapisan Engineering AI Agent. Untuk memisahkan jalur, state, dan approval-nya, lanjutkan ke Graph-Based Agent Workflow. Untuk kontrak instruksi per model call, lihat Prompt Engineering 2026.

Batas istilahnya memang tidak kaku. Sebagian framework memasukkan planning, memory, atau sub-agent ke dalam harness. Sebagian menyebutnya runtime atau agent framework. Nama bukan inti keputusan. Tim perlu memastikan tanggung jawab operasional di atas benar-benar ada dan punya owner.

Kenapa prompt tidak bisa menggantikan harness

Prompt bekerja pada perilaku model. Harness bekerja pada realitas di luar model.

Instruksi "selalu jalankan test" tidak membuat database test tersedia. Instruksi "jangan mengirim email tanpa approval" bukan pengganti permission yang memblokir API kirim. Instruksi "gunakan file terbaru" tidak memperbaiki workspace yang berisi dua build tanpa timestamp. Instruksi "pastikan deploy berhasil" tidak menyediakan health check.

Ada empat kelas masalah yang tidak bisa diselesaikan hanya dengan wording.

Masalah akses

Agent tidak dapat membaca dashboard, file, log, atau documentation yang dibutuhkan. Dari sudut pandang agent, resource yang tidak dapat diakses praktis tidak ada.

Masalah observability

Agent dapat mengeksekusi action, tetapi tidak dapat melihat akibatnya. Tool mengembalikan accepted, lalu agent menyimpulkan outcome sudah terjadi. Padahal job baru masuk antrean.

Masalah enforcement

Aturan hanya berupa kalimat. Tool tetap bisa dipanggil dengan tenant yang salah, nominal di atas batas, atau recipient eksternal. Model mungkin patuh pada banyak kasus, tetapi policy penting seharusnya ditegakkan oleh aplikasi.

Masalah verification

Tidak ada gate mekanis yang membedakan output meyakinkan dari output benar. Agent menulis "semua test lulus" karena ia melihat ringkasan parsial atau tidak memahami exit code.

Maka ketika agent gagal, pertanyaan engineering yang lebih baik bukan "prompt apa yang lebih keras?" Pertanyaannya: capability, signal, constraint, atau proof apa yang hilang dari environment?

Pelajaran dari eksperimen OpenAI: bedakan laporan kasus dan prinsip

Artikel OpenAI tentang harness engineering melaporkan eksperimen internal membangun produk software dengan kode, test, CI, dokumentasi, observability, dan tooling yang ditulis Codex. Mereka menyebut skala serta throughput tertentu. Angka tersebut adalah fakta tentang eksperimen yang mereka laporkan, bukan benchmark universal untuk perusahaan lain.

Yang lebih berguna adalah mekanismenya.

Pertama, mereka membuat aplikasi legible bagi agent. Setiap worktree dapat menjalankan instance sendiri. Browser dapat dikendalikan. DOM snapshot, screenshot, log, metric, dan trace tersedia di environment yang dapat dibaca Codex. Dengan begitu, agent tidak hanya menulis patch; ia bisa mereproduksi dan memeriksa perilaku.

Kedua, mereka memperlakukan repository knowledge sebagai system of record. File instruksi utama dipakai sebagai peta, bukan ensiklopedia. Dokumentasi lebih dalam disusun dan ditautkan. Ini sejalan dengan progressive disclosure: berikan entry point kecil, lalu sediakan jalur menemukan detail saat diperlukan.

Ketiga, invariant penting ditegakkan secara mekanis melalui linter dan structural test. Dokumentasi memberi arah; code mencegah pelanggaran yang bisa dideteksi.

Keempat, feedback berulang diubah menjadi aset sistem. Review comment, bug, dan drift tidak berhenti sebagai percakapan. Rule yang stabil dipromosikan menjadi dokumentasi, test, tool, atau linter.

Pattern industri yang dapat diambil: reliability agent bertambah ketika lingkungan dapat diamati dan aturan dapat dieksekusi. Rekomendasi Rama Digital: ambil mekanismenya, jangan menyalin skala, tool, atau merge philosophy tanpa menilai risiko sendiri.

Komponen 1: environment yang terisolasi dan dapat direproduksi

Agent membutuhkan ruang kerja dengan boundary yang eksplisit. Untuk coding, bentuknya dapat berupa worktree, container, dependency lock, database test, dan service lokal. Untuk konten, bentuknya dapat berupa folder draft, corpus sumber, template, validator markdown, serta preview. Untuk campaign, bentuknya dapat berupa akun sandbox, data read-only, dan tool draft tanpa publish permission.

Environment minimum menjawab:

• resource mana yang boleh dibaca dan ditulis;
• versi dependency, data, dan konfigurasi apa yang aktif;
• apakah dua run dapat saling mengganggu;
• cara membersihkan artifact sementara;
• cara mereproduksi kondisi awal;
• data sensitif apa yang harus di-redact atau tidak pernah masuk context.

Isolasi bukan hanya security. Ia juga mencegah bukti palsu. Jika dua agent menulis ke folder yang sama, validator dapat membaca artifact milik run lain dan meloloskan pekerjaan yang salah.

Gunakan identifier per task dan namespace per tenant. Beri setiap artifact owner, run ID, timestamp, dan status. Untuk operasi eksternal, pisahkan credential read, draft, dan write bila platform memungkinkan.

Komponen 2: tool yang jelas, sempit, dan dapat diprediksi

Tool adalah kontrak antara model dan lingkungan. Panduan function calling OpenAI menjelaskan function tool melalui nama, deskripsi, dan JSON schema, lalu aplikasi mengeksekusi tool call serta mengembalikan output ke model.

Schema yang valid saja belum cukup. Tool perlu dirancang agar pilihan dan efeknya jelas.

Bandingkan dua desain:

manage_campaign(action, payload)

versus:

get_campaign_metrics(account_id, start_date, end_date)
create_campaign_draft(account_id, brief)
request_campaign_publish_approval(draft_id)
publish_approved_campaign(approval_id)

Tool generik memberi fleksibilitas tinggi, tetapi menyembunyikan authority dan memperluas ruang kesalahan. Tool sempit membuat permission, eval, log, dan approval lebih mudah.

Karakter tool yang layak diberikan ke agent:

• nama menggambarkan satu capability;
• deskripsi menjelaskan kapan tool dipakai dan kapan tidak;
• parameter memiliki tipe, enum, format, dan required field yang tepat;
• output ringkas tetapi memuat status, identifier, dan error category;
• efek samping terdokumentasi;
• retry semantics jelas;
• hasil sensitif di-redact;
• ada dry-run atau draft mode bila relevan;
• error membantu langkah perbaikan, bukan hanya failed.

Anthropic dalam panduan effective context engineering mengingatkan bahwa tool set yang terlalu bengkak menciptakan keputusan ambigu. Tool definition juga masuk ke context; terlalu banyak schema memakan attention dan membuat pemilihan lebih sulit.

Rekomendasi Rama Digital: berikan minimum viable tool set per node atau per workflow. Capability yang jarang dipakai dapat ditemukan atau dimuat just-in-time. Jangan memberi seluruh tool organisasi ke satu agent serbaguna.

Komponen 3: knowledge map dan progressive disclosure

Manual raksasa terlihat lengkap, tetapi buruk sebagai context default. Ia cepat basi, memakan context, dan membuat aturan penting tenggelam.

Harness sebaiknya memberi map, bukan dump. Entry point menjelaskan struktur, source of truth, ownership, naming, dan jalur menuju detail. Agent kemudian mengambil dokumentasi yang relevan saat dibutuhkan.

Contoh struktur untuk content operation:

AGENT_MAP.md
policies/
 publishing.md
 claims-and-sources.md
brands/
 rama-digital.md
workflows/
 article-draft.md
 article-review.md
schemas/
 article-metadata.json
runtime/
 task-<id>/

File map tidak perlu memuat seluruh policy. Ia harus mengatakan file mana yang berwenang dan bagaimana memilihnya. Setiap dokumen penting perlu owner, status, versi, dan tanggal review.

Untuk pemisahan informasi sementara, posisi workflow, dan pengetahuan lintas waktu, gunakan kerangka Context vs State vs Memory. Harness harus menyediakan jalur retrieval; context builder tetap memilih apa yang masuk ke panggilan model sekarang.

Kesalahan umum adalah menyimpan keputusan di chat lalu berasumsi agent berikutnya akan tahu. Jika keputusan perlu mengatur kerja berikutnya, pindahkan ke source of truth yang dapat ditemukan dan dikontrol.

Komponen 4: guardrails sebagai code, bukan harapan

Guardrail yang kritis perlu berada di boundary yang tidak dapat dilewati model.

Contohnya:

• filter tenant diterapkan server-side;
• path write dibatasi ke workspace task;
• nominal di atas threshold memerlukan approval token;
• tool publish menolak draft tanpa status approved;
• query database memakai allowlist;
• payload eksternal divalidasi schema;
• domain recipient dibatasi;
• secret tidak pernah dikembalikan pada tool output;
• tool destructive menggunakan confirmation dan audit log.

Prompt tetap menyebut policy agar agent dapat merencanakan dengan benar. Namun enforcement tidak bergantung pada kepatuhan generatif.

Prinsip ini juga berlaku untuk data. Agent yang mengetahui suatu informasi tidak otomatis memiliki authority. Artikel Arsitektur Agentic Second Brain: Layer, Alur, dan Guardrail membahas pemisahan memory, action, dan governance.

Gunakan risk tier. Read-only lookup berisiko rendah dapat otomatis. Draft internal mungkin cukup dengan validation. Write eksternal, finansial, destructive, atau privacy-sensitive perlu policy dan human approval yang lebih ketat.

Komponen 5: observability yang dapat dipakai agent dan operator

Log untuk manusia belum tentu berguna bagi agent. Dump ribuan baris tanpa struktur hanya memindahkan noise ke context.

Observability harness perlu menyajikan signal pada dua level.

Level operator mencakup trace lintas node, model dan prompt version, token atau cost, latency, tool call, state transition, approval, serta artifact. Operator memakainya untuk audit dan incident response.

Level agent mencakup hasil yang ringkas dan dapat ditindaklanjuti: error category, lokasi failure, expected versus actual, identifier, dan saran recovery yang aman. Agent tidak perlu melihat secret atau seluruh raw log.

Untuk coding agent, signal dapat berupa test failure terfilter, browser console, screenshot, DOM snapshot, metric, dan trace. Untuk content agent, signal dapat berupa broken link, duplicate H1, claim tanpa source, metadata terlalu panjang, atau preview yang gagal render. Untuk campaign agent, signal dapat berupa account mismatch, missing conversion event, currency mismatch, dan approval status.

Observability juga harus membedakan request accepted dari outcome verified. API 202 Accepted berarti pekerjaan diterima, bukan selesai. Harness perlu polling yang dibatasi, webhook, atau reconciliation job untuk memeriksa status akhir.

Komponen 6: feedback dan eval sebagai mesin perbaikan

Model bersifat variabel. Test deterministic tetap penting, tetapi tidak cukup untuk semua perilaku generatif. OpenAI evaluation best practices menyarankan eval-driven development, task-specific eval, logging, automation, dan continuous evaluation. Mereka juga membedakan area evaluasi untuk instruction following, functional correctness, tool selection, argument precision, dan handoff.

Harness perlu menghubungkan perubahan dengan gate yang sesuai:

• unit test untuk function dan validator;
• schema validation untuk payload;
• executable eval untuk code atau query;
• golden cases untuk classification dan extraction;
• pairwise atau rubric untuk output editorial;
• adversarial cases untuk prompt injection dan scope leak;
• human review untuk judgement bernilai tinggi;
• regression suite dari insiden production.

Jangan meminta model "review pekerjaanmu" lalu menganggap self-review sebagai bukti independen. Self-review dapat membantu menemukan masalah, tetapi acceptance harus datang dari validator, environment, atau reviewer dengan kriteria eksplisit.

Feedback yang berulang perlu dipromosikan ke sistem. Jika agent tiga kali salah memilih field tanggal, perbaiki schema, contoh, tool description, atau validator. Jangan menumpuk satu paragraf teguran lagi di system prompt tanpa tes.

Komponen 7: checkpoint, recovery, dan idempotency

Agent dapat berjalan lama dan memanggil sistem eksternal. Crash, timeout, rate limit, atau approval delay adalah kondisi normal, bukan edge case eksotis.

Checkpoint minimum menyimpan:

• task ID dan owner;
• workflow version;
• node atau langkah aktif;
• input yang sudah divalidasi;
• artifact yang sudah dibuat;
• tool call serta statusnya;
• idempotency key;
• retry count;
• blocker;
• approval pending dan masa berlakunya.

Pemulihan tidak boleh hanya memutar ulang seluruh chat. Harness perlu membaca state dan memeriksa environment. Apakah invoice sudah dibuat? Apakah email sudah terkirim? Apakah pull request sudah ada? Baru setelah itu ia memutuskan resume, reconcile, atau escalate.

Framework seperti LangGraph mendokumentasikan durable execution dan persistence. Fitur framework membantu, tetapi schema state dan semantics action tetap menjadi tanggung jawab implementasi.

Gunakan idempotency key untuk API yang mendukungnya. Untuk sistem yang tidak mendukung, simpan external identifier dan buat reconciliation check. Retry buta pada side effect adalah salah satu failure mode paling mahal karena output ganda dapat terlihat sah.

Komponen 8: proof of completion

Harness yang baik tidak menerima kalimat "sudah selesai" sebagai status final. Ia memerlukan postcondition.

Contoh proof per pekerjaan:

Pekerjaan	Klaim lemah	Proof yang lebih kuat
Membuat artikel	"Draft sudah dibuat"	File ada, dapat dibaca, H1 satu, metadata valid, link check selesai
Memperbaiki bug	"Kode sudah diperbaiki"	Reproduksi failure, test baru gagal sebelum patch, test lulus setelah patch, build bersih
Mengirim laporan	"Laporan terkirim"	Delivery ID, recipient cocok, status provider delivered atau accepted dengan follow-up
Memperbarui CRM	"Record di-update"	Read-back record menunjukkan field dan version yang diharapkan
Deploy	"Deploy sukses"	Release ID aktif, health check lulus, smoke test jalur kritis berhasil

Bukti harus dekat dengan outcome. Linter bersih tidak membuktikan business rule benar. Screenshot UI tidak membuktikan database konsisten. Pilih gate sesuai risiko.

Di Rama Digital, kami merekomendasikan status berjenjang: prepared, validated, approved, executed, verified. Ini lebih informatif daripada satu boolean done.

Workflow Rama Digital: harness untuk draft artikel

Ambil kasus pembuatan artikel berbasis sumber primer. Outcome-nya bukan "model menghasilkan teks", tetapi draft editorial yang siap direview tanpa dipublikasikan.

Environment

Setiap task mendapat folder terpisah. Agent hanya boleh menulis file Markdown dan metadata yang ditentukan. Tidak ada credential publish. Corpus sumber dan existing article dapat dibaca, tetapi source of truth URL diperiksa ulang.

Tool set

Tool minimal: read existing style sample, fetch public source, write draft, inspect file, count heading, count words, validate JSON, dan check public link. Tool deploy serta image generation tidak tersedia.

Context policy

Node riset melihat brief, daftar sumber wajib, existing internal links, dan policy klaim. Node drafting melihat research notes terkurasi, tone guide, title, dan outline. Node validation melihat file final serta acceptance criteria, bukan seluruh histori riset.

Guardrail

Path allowlist menolak write di luar folder task. Link ke sumber sekunder tidak boleh dipakai untuk menguatkan klaim vendor jika docs primer tersedia. Tidak ada statistik tanpa attribution. Artikel tetap draft.

Feedback loop

Validator memeriksa satu H1, rentang kata, placeholder, link, meta, dan repetisi. Failure dikembalikan dalam format terstruktur. Revisi maksimal dibatasi dan harus menargetkan failure tertentu.

Proof

Pekerjaan dianggap selesai ketika semua file ada, format valid, lint editorial lulus, link check tercatat, dan word count masuk target. Agent melaporkan hasil pemeriksaan, bukan sekadar menyebut draft lengkap.

Pola ini dapat diterapkan pada model discovery sampai workflow consolidation: mulai dari capability yang nyata, lalu bentuk workflow dan harness sesuai kebutuhan, bukan sebaliknya.

Failure modes harness yang sering disalahdiagnosis

Tool terlalu generik

run_command atau manage_everything memang cepat untuk prototipe. Di production, blast radius, audit, dan eval menjadi buruk. Ganti dengan capability sempit atau bungkus operasi berisiko.

Tool overlap

Agent melihat search_docs, query_knowledge, find_file, dan browse_repo tanpa boundary jelas. Ia membuang step untuk mencoba semuanya. Gabungkan fungsi atau tulis decision rule yang dapat diuji.

Dokumentasi tidak punya authority

Tiga file menjelaskan prosedur berbeda. Retrieval memilih yang paling mirip, bukan paling sah. Tambahkan owner, versi, status, dan canonical pointer. Arsipkan rule lama.

Error tidak actionable

Tool hanya mengembalikan 400 bad request. Agent mengulang dengan tebakan baru. Berikan field yang gagal, format yang diharapkan, dan kategori retryable atau permanent.

Agent dapat menulis tetapi tidak dapat membaca kembali

Tanpa read-back, agent tidak dapat memverifikasi serialisasi, propagation, atau permission. Setiap critical write perlu verification path yang independen.

Approval hanya ada di UI, tidak di runtime

Operator melihat tombol approval, tetapi tool write tetap dapat dipanggil langsung. Approval harus menghasilkan capability atau token yang benar-benar diperiksa server-side.

Shared workspace

Artifact lintas run bercampur. Test lulus terhadap file lama. Gunakan namespace, cleanup, dan run manifest.

Secret masuk log atau context

Tool mengembalikan header atau connection string mentah. Terapkan redaction di boundary, bukan meminta model untuk tidak mengulang secret.

Completion tanpa proof

Agent menyamakan "tool dipanggil" dengan "outcome terjadi". Tambahkan postcondition dan status pending_verification bila sistem eksternal bersifat asynchronous.

Harness terlalu besar sejak hari pertama

Tim membangun platform agent umum sebelum satu workflow stabil. Hasilnya banyak abstraction, sedikit bukti. Mulai dari harness minimum untuk satu pekerjaan; ekstrak primitive setelah pola berulang.

Maturity model tanpa angka palsu

Tidak perlu memberi skor presisi yang tidak punya dasar. Gunakan level keputusan berikut.

Level 0: chat-assisted

Model memberi saran. Manusia menyalin hasil ke sistem. Risiko action rendah, tetapi trace dan repeatability terbatas.

Level 1: read and draft

Agent dapat membaca sumber dan membuat artifact di workspace terisolasi. Tidak ada external write. Validator dasar tersedia.

Level 2: bounded tool use

Agent memakai tool sempit dengan schema, permission, log, budget, dan retry policy. Hasil selalu dibaca kembali.

Level 3: approved execution

External write tersedia hanya setelah policy check dan human approval. Checkpoint serta recovery diuji.

Level 4: bounded autonomy

Agent boleh mengeksekusi kelas action tertentu secara otomatis karena eval, monitoring, reconciliation, dan incident process sudah matang. Action berisiko tinggi tetap punya gate.

Naik level per workflow, bukan per organisasi. Agent reporting mungkin berada di Level 4, sedangkan pembayaran tetap Level 1 atau 3.

Checklist desain harness

Environment

• Apakah setiap task dan tenant terisolasi?
• Dapatkah kondisi awal direproduksi?
• Apakah version dan dependency terkunci?
• Apakah artifact memiliki run ID dan owner?

Tools

• Apakah setiap tool punya satu fungsi yang jelas?
• Apakah schema, side effect, dan retry semantics eksplisit?
• Apakah output ringkas, terstruktur, dan di-redact?
• Apakah tool set minimum untuk pekerjaan itu?

Knowledge

• Apakah ada map menuju source of truth?
• Apakah dokumen punya owner, versi, dan status?
• Apakah progressive disclosure lebih dipilih daripada context dump?
• Apakah rule lama ditandai superseded?

Guardrails

• Apakah tenant, path, nominal, dan recipient dibatasi di code?
• Apakah credential mengikuti least privilege?
• Apakah destructive dan external write membutuhkan approval nyata?
• Apakah untrusted content dipisahkan dari instruction?

Feedback dan proof

• Apakah test, linter, eval, dan preview tersedia bagi agent?
• Apakah error menunjuk penyebab dan recovery?
• Apakah completion memiliki postcondition yang dapat diperiksa?
• Apakah self-review dibedakan dari independent verification?

Recovery

• Apakah checkpoint menyimpan posisi dan external identifiers?
• Apakah retry dapat menyebabkan side effect ganda?
• Apakah reconciliation dijalankan sebelum mengulang write?
• Apakah pause dan crash sudah disimulasikan?

Keputusan operasional 30 hari

Minggu pertama: pilih satu workflow berulang dengan output jelas. Petakan source, tools, risk, approval, dan proof. Rekam baseline manual.

Minggu kedua: bangun environment terisolasi, tool read/draft yang sempit, serta validator deterministic. Jangan aktifkan external write.

Minggu ketiga: tambahkan trace, eval cases dari pekerjaan nyata, checkpoint, dan failure injection. Putuskan proses saat sebelum dan sesudah side effect untuk menguji recovery.

Minggu keempat: aktifkan satu approved write dengan permission server-side dan read-back verification. Review semua failure, lalu pilih apakah perbaikannya berada di prompt, context, tool, guardrail, loop, atau graph.

Jika workflow belum stabil pada read/draft, menambah autonomy hanya mempercepat kesalahan.

Harness yang baik membuat agent lebih mudah diawasi

Tujuan harness bukan membebaskan agent dari manusia. Tujuannya memindahkan perhatian manusia ke keputusan yang memang membutuhkan judgement.

Prompt bagus membantu model memahami intent. Harness bagus memastikan agent bekerja di tempat yang benar, memakai kemampuan yang tepat, tidak melewati batas, menerima feedback yang berguna, dan menunjukkan bukti sebelum menyatakan selesai.

Ketika sebuah agent tersendat, jangan langsung meminta model "coba lagi lebih teliti". Periksa environment. Sering kali capability yang hilang, feedback yang kabur, atau gate yang belum ada lebih menentukan daripada satu paragraf instruksi tambahan.