Model bahasa bukan aplikasi. Ia hanya komponen yang menerima prompt dan menghasilkan output. Ketika model dipakai untuk membaca repository, menjalankan test, memanggil API, mengubah file, atau mengambil keputusan bertahap, dibutuhkan lapisan lain yang mengatur semua interaksi tersebut.

Lapisan itulah yang sering disebut AI harness.

Harness bukan sekadar wrapper API. Ia mengatur tool access, loop reasoning, state, permission, observability, retry, dan batas operasi. Tanpa harness, agent AI hanya chatbot yang sesekali bisa memanggil fungsi. Dengan harness yang dirancang benar, model menjadi worker yang dapat menyelesaikan pekerjaan terukur dalam lingkungan yang terkendali.

Apa Itu AI Harness?

AI harness adalah runtime dan kumpulan guardrail yang menghubungkan model AI dengan dunia luar.

Secara sederhana, alurnya seperti ini:

User task
   |
   v
Harness -> model inference
   |             |
   |             v
   |        tool decision
   |             |
   v             v
state, policy, tool executor
   |
   v
result, artifacts, audit trail

Model bertanggung jawab atas interpretasi dan pemilihan langkah. Harness bertanggung jawab atas eksekusi yang aman dan bisa diamati.

Komponen umum sebuah harness:

  • Model adapter — berkomunikasi dengan provider atau model lokal
  • Conversation/state manager — menyimpan konteks dan hasil tool
  • Tool registry — mendefinisikan tool yang tersedia
  • Tool executor — menjalankan command, HTTP call, browser, atau operasi file
  • Policy engine — menentukan tool dan argumen yang diizinkan
  • Approval gate — meminta persetujuan untuk operasi berisiko
  • Memory layer — menyimpan fakta atau hasil yang perlu digunakan kembali
  • Observer — mencatat latency, token, error, biaya, dan artifact
  • Termination controller — menghentikan loop saat selesai atau melewati batas

Pemisahan ini penting karena model tidak boleh menjadi satu-satunya pengendali sistem.

Mengapa Agent Tanpa Harness Cepat Menjadi Masalah?

Prototype biasanya dimulai dengan pola sederhana:

response = client.chat.completions.create(
    model="some-model",
    messages=[{"role": "user", "content": task}],
)
print(response.choices[0].message.content)

Pola ini cukup untuk menghasilkan teks. Ia tidak cukup ketika model perlu bekerja.

Begitu model diberi akses ke shell, masalah baru muncul:

  1. Model dapat menjalankan command di luar scope.
  2. Retry dapat mengulangi operasi yang seharusnya hanya sekali.
  3. Context membengkak setelah banyak tool call.
  4. Tidak jelas apakah hasil sudah diverifikasi atau hanya diklaim selesai.
  5. Error dari tool dapat disalahartikan sebagai keberhasilan.
  6. Credential bisa masuk ke prompt, log, atau output.
  7. Loop dapat berjalan tanpa batas dan menghabiskan biaya.

Harness ada untuk mengubah operasi yang tidak terstruktur menjadi siklus yang memiliki kontrak:

observe -> decide -> authorize -> execute -> verify -> record

Siklus Agent yang Sehat

Harness yang baik tidak hanya memanggil model berulang-ulang. Setiap iterasi harus mempunyai state dan hasil yang jelas.

MAX_STEPS = 20

state = {
    "task": task,
    "messages": [],
    "artifacts": [],
    "step": 0,
}

while state["step"] < MAX_STEPS:
    state["step"] += 1

    decision = model_adapter.decide(state)
    policy.check_decision(decision, state)

    if decision.type == "final":
        verifier.check_final_claims(decision, state)
        return decision.output

    if decision.type != "tool_call":
        raise HarnessError("unsupported decision type")

    result = tool_executor.run(
        name=decision.tool,
        arguments=decision.arguments,
        context=state,
    )
    state["messages"].append(result.to_message())
    state["artifacts"].extend(result.artifacts)

raise HarnessError("agent exceeded step limit")

Contoh ini belum production-ready, tetapi menunjukkan pembagian tanggung jawab. Model memilih tindakan; policy memeriksa; executor menjalankan; verifier menguji klaim; state menyimpan bukti.

Tool Registry: Kontrak Sebelum Eksekusi

Tool sebaiknya didefinisikan dengan schema yang eksplisit, bukan diberikan sebagai fungsi Python mentah.

tools = {
    "read_file": {
        "description": "Read a text file inside the workspace",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string"},
                "start_line": {"type": "integer", "minimum": 1},
            },
            "required": ["path"],
            "additionalProperties": False,
        },
        "risk": "low",
    },
    "run_tests": {
        "description": "Run the repository test command",
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string"},
            },
            "required": ["command"],
            "additionalProperties": False,
        },
        "risk": "medium",
    },
}

Schema memberi tiga manfaat:

  • Model tahu bentuk input yang valid.
  • Harness dapat memvalidasi sebelum menjalankan.
  • Policy dapat mengklasifikasikan risiko per tool.

Jangan memberikan tool bernama execute_anything jika sebenarnya kebutuhan hanya membaca file dan menjalankan test. Permission yang terlalu luas sulit diamankan dengan prompt.

Sandbox dan Batas File System

Tool read_file bukan berarti model boleh membaca seluruh mesin. Harness harus menentukan workspace dan menolak path traversal.

from pathlib import Path

WORKSPACE = Path("/srv/agent/workspace").resolve()

def safe_path(raw_path: str) -> Path:
    candidate = (WORKSPACE / raw_path).resolve()
    if candidate != WORKSPACE and WORKSPACE not in candidate.parents:
        raise PermissionError("path outside workspace")
    return candidate

Untuk command execution, pembatasan string saja tidak cukup. rm -rf dapat disamarkan, dan command yang tampak aman dapat memanggil shell lain.

Lapisan yang lebih aman:

  • Container ephemeral per task
  • User Linux non-root
  • Read-only filesystem untuk bagian yang tidak perlu ditulis
  • Workspace terpisah per job
  • Network egress deny-by-default
  • CPU, memory, process, dan disk quota
  • Timeout per command
  • Allowlist executable untuk operasi sensitif

Sandbox mengurangi blast radius. Ia tidak membuat tool yang salah menjadi aman secara otomatis.

Approval Gate untuk Operasi Berisiko

Tidak semua tool perlu approval. Membaca file di workspace biasanya low risk. Menghapus data, mengirim email, melakukan deploy, atau mengubah firewall membutuhkan kontrol berbeda.

Contoh policy sederhana:

RISK_POLICY = {
    "read_file": "low",
    "run_tests": "medium",
    "git_commit": "medium",
    "deploy_production": "high",
    "delete_database": "critical",
}

def authorize(tool_name, actor):
    risk = RISK_POLICY[tool_name]

    if risk in {"high", "critical"} and not actor.approved:
        raise ApprovalRequired(tool_name)

Approval harus mengikat ke operasi yang spesifik: tool, argumen, target environment, dan waktu kedaluwarsa. Persetujuan generik seperti "izinkan agent melakukan apa saja" menghilangkan nilai kontrol.

Untuk workflow otomatis tanpa manusia, gantikan approval dengan policy deterministik dan environment terbatas. Jangan menyamakan unattended execution dengan tanpa guardrail.

State, Context, dan Checkpoint

Model tidak memiliki memori kerja yang stabil di luar context yang dikirimkan. Harness harus mengelola state secara eksplisit.

State minimal biasanya mencakup:

  • Task asli
  • Tujuan dan acceptance criteria
  • Langkah yang sudah dilakukan
  • Tool result yang relevan
  • File atau artifact yang dibuat
  • Error yang sudah diperbaiki
  • Verifikasi yang sudah lolos
  • Batas waktu dan budget

Simpan checkpoint setelah operasi penting. Jika proses mati setelah build selesai tetapi sebelum deployment, harness dapat melanjutkan dari state terakhir tanpa mengulang build atau mengirim request kedua.

Gunakan idempotency key untuk operasi eksternal yang dapat mengubah state:

result = payment_api.create(
    order_id=order_id,
    idempotency_key=f"agent-task-{task_id}-payment",
)

Retry tanpa idempotency adalah sumber duplikasi yang sering tidak terlihat saat testing.

Context Management dan Compaction

Context window bukan database. Memasukkan seluruh log, file, dan hasil tool ke setiap request akan menaikkan biaya serta menurunkan kualitas keputusan.

Praktik yang lebih sehat:

  1. Simpan hasil lengkap sebagai artifact.
  2. Buat ringkasan terstruktur untuk context model.
  3. Pertahankan error terakhir dan bukti yang relevan.
  4. Buang output duplikat.
  5. Gunakan retrieval saat informasi lama dibutuhkan.

Contoh state ringkas:

{
  "goal": "memperbaiki test login",
  "files_changed": ["src/auth.ts", "tests/auth.test.ts"],
  "tests": {
    "command": "npm test -- auth",
    "status": "failed",
    "last_error": "expected 401, received 500"
  },
  "next_action": "inspect error mapping in auth handler"
}

Ringkasan yang baik bukan sekadar memotong teks. Ia mempertahankan fakta yang memengaruhi keputusan berikutnya.

Verifikasi: Jangan Percaya Klaim Model

Model bisa mengatakan "test sudah lulus" meskipun tidak pernah menjalankan test. Harness harus memisahkan claim dari evidence.

def verify_test_result(result):
    if result.exit_code != 0:
        return False
    if result.timed_out:
        return False
    return result.exit_code == 0

Untuk deployment, verifikasi minimal tidak berhenti di exit code command:

  • Health endpoint mengembalikan status yang benar
  • Versi artifact yang berjalan sesuai commit atau digest
  • Log tidak menunjukkan crash loop
  • Database migration selesai
  • Smoke test critical path lolos
  • Rollback target tersedia

Agent boleh menyarankan bahwa pekerjaan selesai. Harness hanya boleh menandainya selesai setelah acceptance criteria memiliki bukti.

Observability dan Audit Trail

Tanpa observability, agent sulit di-debug karena kegagalan bisa terjadi di model, policy, tool, network, atau aplikasi target.

Catat minimal:

  • task_id dan run_id
  • Model dan provider
  • Input/output token atau estimasi biaya
  • Nama tool dan argumen yang sudah disanitasi
  • Durasi setiap langkah
  • Exit code dan error class
  • Approval decision
  • Artifact path atau checksum
  • Final verification result

Jangan mencatat access token, password, cookie, atau payload sensitif secara mentah. Redaction harus dilakukan sebelum log ditulis, bukan ketika log ditampilkan.

Struktur event yang berguna:

{
  "event": "tool.completed",
  "runId": "run_123",
  "taskId": "task_456",
  "tool": "run_tests",
  "durationMs": 1842,
  "exitCode": 0,
  "artifact": "artifacts/run_123/test.log",
  "timestamp": "2026-08-14T12:00:00Z"
}

Audit trail juga penting untuk menjawab pertanyaan: perubahan apa yang dilakukan agent, berdasarkan input apa, dengan izin siapa, dan diverifikasi bagaimana?

Retry, Timeout, dan Circuit Breaker

Retry tidak boleh menjadi respons default untuk semua error. Bedakan error transient dari error permanen.

  • Timeout network atau HTTP 503 mungkin layak di-retry.
  • HTTP 400 karena schema salah tidak akan selesai dengan retry.
  • Permission denied perlu perubahan authorization, bukan pengulangan.
  • Command yang menghasilkan side effect perlu idempotency sebelum retry.

Gunakan exponential backoff dengan batas percobaan dan total deadline. Circuit breaker mencegah agent terus menekan service yang sedang gagal.

TRANSIENT = {"timeout", "connection_reset", "http_502", "http_503"}

for attempt in range(3):
    try:
        return call_service()
    except ServiceError as error:
        if error.kind not in TRANSIENT or attempt == 2:
            raise
        sleep_seconds = min(30, 2 ** attempt)
        time.sleep(sleep_seconds)

Retry loop harus menjadi bagian policy harness, bukan keputusan bebas model.

Evaluasi AI Harness

Evaluasi harness tidak cukup dengan bertanya apakah output terdengar bagus. Ukur perilaku end-to-end.

Metrik yang berguna:

  • Task completion rate
  • Verification pass rate
  • Tool-call accuracy
  • Invalid tool-call rate
  • Human approval rate
  • Mean steps per task
  • Retry rate
  • Cost per successful task
  • Time to completion
  • Policy violation attempts
  • Regression rate setelah perubahan prompt atau model

Buat dataset task yang representatif: task normal, input ambigu, permission denied, service timeout, data rusak, dan permintaan berbahaya. Harness yang hanya diuji pada jalur sukses akan terlihat bagus sampai dipakai di lingkungan nyata.

Framework, Platform, atau Bangun Sendiri?

Ada tiga pendekatan umum.

Pendekatan Kelebihan Biaya dan risiko
Framework agent Tool calling, memory, dan workflow lebih cepat dibuat Abstraksi bisa menyembunyikan retry, state, dan permission
Platform managed Operasional model dan scaling lebih ringan Lock-in, biaya usage, kontrol data lebih terbatas
Harness internal Kontrol penuh atas policy, audit, dan environment Biaya engineering dan maintenance lebih besar

Pilih framework ketika kebutuhan masih eksploratif dan tool berisiko rendah. Pertimbangkan harness internal ketika agent menyentuh production, data sensitif, deployment, atau workflow yang harus diaudit.

Tidak semua sistem perlu autonomous agent. Untuk pekerjaan deterministik, pipeline biasa sering lebih murah, mudah diuji, dan lebih dapat diprediksi.

Kesalahan yang Sering Terjadi

  1. Menjadikan system prompt sebagai security boundary — prompt dapat salah dipahami atau dipengaruhi input. Enforcement harus berada di executor.
  2. Memberikan shell root tanpa sandbox — satu keputusan buruk dapat menjadi insiden penuh.
  3. Tidak punya termination condition — loop tidak berhenti dan biaya terus berjalan.
  4. Menyimpan semua context tanpa struktur — model kehilangan sinyal penting di antara log.
  5. Menganggap output sebagai bukti — klaim selesai bukan verifikasi.
  6. Retry semua error — bug permanen berubah menjadi banjir request.
  7. Tidak memisahkan dev dan production — pengujian agent menyentuh resource nyata.
  8. Tidak menguji prompt injection dari tool output — file, issue, dan halaman web bisa berisi instruksi berbahaya.
  9. Mencampur credential dengan context — secret seharusnya di-inject secara terbatas oleh executor.

Checklist Sebelum Produksi

  • [ ] Setiap tool memiliki schema dan permission yang jelas
  • [ ] Workspace dan network memiliki batas eksplisit
  • [ ] Process berjalan sebagai non-root
  • [ ] Ada timeout, step limit, dan budget limit
  • [ ] High-risk operation memiliki approval atau policy deterministik
  • [ ] Retry hanya berlaku untuk error transient
  • [ ] Operasi eksternal memakai idempotency key
  • [ ] Secret di-redact dari prompt, output, dan log
  • [ ] Semua perubahan menghasilkan artifact atau audit event
  • [ ] Final claim diverifikasi dengan command atau health check nyata
  • [ ] Ada kill switch dan rollback path
  • [ ] Evaluasi mencakup jalur gagal dan prompt injection

Kesimpulan Praktis

AI harness adalah lapisan kontrol antara kemampuan model dan dampak nyata di sistem. Nilainya bukan pada membuat model lebih pintar, tetapi membuat tindakan model dapat dibatasi, diulang dengan aman, diamati, dan diverifikasi.

Untuk memulai, bangun harness kecil dengan empat fondasi: tool schema, sandbox, state checkpoint, dan verifikasi. Tambahkan approval, audit, budget, dan evaluasi sebelum memberikan akses ke production.

Jika pekerjaan dapat diselesaikan oleh script atau pipeline deterministik, gunakan itu. Agent layak dipakai ketika interpretasi, eksplorasi, dan pemilihan langkah memang membutuhkan model — tetapi eksekusi akhirnya tetap harus dikendalikan oleh harness.