Panduan Rekayasa Agent Harness: Menjembatani Kesenjangan antara Model dan Aksi

Bayangkan menjalankan model bahasa besar (LLM) yang sama persis dua kali, namun masing-masing diberi dua harness yang benar-benar berbeda. Satu run menyelesaikan tugas refaktorisasi kompleks dengan rapi. Run kedua berhenti dan gagal total. Modelnya tidak berubah, tetapi perancah di sekitar model itulah yang berubah.

Singkatnya, rekayasa agent harness adalah praktik membangun logika pendukung, akses sistem berkas, memori, dan aturan agar LLM dapat bertindak secara andal. 

Dalam tutorial rekayasa agent harness ini, saya akan mengajarkan Anda cara menyusun setup Python minimal dengan loop Reason and Act (ReAct), tool, dan hook. Anda memerlukan Python 3, pip terpasang di mesin Anda, dan pemahaman dasar tentang cara melakukan panggilan API LLM.

Apa itu Rekayasa Agent Harness?

Rekayasa agent harness adalah praktik membangun infrastruktur, konfigurasi, dan logika eksekusi yang membungkus model bahasa besar, mengubahnya dari generator teks LLM statis menjadi agen AI otonom

Rekayasa agent harness adalah konfigurasi struktural yang mengubah generator teks statis menjadi pekerja otonom. 

Persamaan intinya sederhana: agen = model + harness. Harness mencakup system prompt, definisi tool, workspace sistem berkas, logika orkestrasi, dan hook observabilitas.

Addy Osmani mengkodifikasi konsep ini dalam tulisannya untuk O'Reilly pada April 2026 tentang alur kerja AI. Ia mendefinisikan harness sebagai setiap potongan kode, konfigurasi, dan logika eksekusi yang bukan model itu sendiri: bidang kerja Anda sebagai pengembang, terpisah dari API penyedia. 

Saat pertama kali membangun alur kerja machine learning, saya menyalahkan model setiap kali agen berhalusinasi dependensi Python. Saya belajar dengan susah payah bahwa sebagian besar kegagalan adalah masalah konfigurasi. 

Versi model yang sama persis dengan harness yang lebih baik secara terukur mengungguli dirinya sendiri dengan harness yang buruk.

Tangga rekayasa AI

Kita dapat memecah pengembangan AI menjadi lapisan-lapisan kontrol yang berbeda. 

Rekayasa harness berada tepat di tengah hierarki ini.

• Rekayasa prompt menentukan instruksi teks langsung.
•  Rekayasa konteks mengelola catatan basis data atau skema API persis yang Anda masukkan ke dalam prompt. 
• Rekayasa harness menentukan bagaimana agen benar-benar mengeksekusi skrip pandas atau membaca CSV lokal. 

Mekanisme ratchet: setiap kesalahan menjadi aturan

Pola pikir yang mendefinisikan rekayasa agent harness adalah efek ratchet. 

Saat agen melakukan kesalahan, Anda merekayasa perbaikan agar kesalahan itu tidak pernah terulang. Harness yang baik hanyalah trial and error yang dipadatkan.

Alih-alih membiarkan agen mengulang kesalahan, Anda menambahkan satu baris ke AGENTS.md, menulis hook baru, atau memperketat deskripsi tool. 

Anda tidak serta-merta meraih model baru; alih-alih, Anda membangun korpus yang memungkinkan Anda melacak kegagalan spesifik dan bagaimana Anda mengeraskannya.

Komponen Inti dari Agent Harness AI

Komponen inti agent harness AI adalah sistem berkas, tool, memori, hook, dan sistem manajemen konteks yang memungkinkan model beroperasi. 

Bagian-bagian ini bekerja bersama untuk mengubah panggilan API yang terisolasi menjadi loop umpan balik yang berkelanjutan. Saya ingin memberi Anda peta yang jelas sebelum kita mulai menulis kode.

Sistem berkas dan Git: state yang tahan lama

Model hanya dapat memproses informasi di dalam jendela konteksnya yang terbatas. Sistem berkas menyediakan workspace yang stabil untuk membaca data, menulis hasil antara, dan berkoordinasi lintas sesi.

Menambahkan version control Git menyediakan jaring pengaman yang diperlukan. Agen dapat melacak progres, membuat branch untuk eksperimen dengan hyperparameter berbeda, dan melakukan rollback kode yang rusak secara otomatis. 

Tool: memberi agen tangan

Loop ReAct beroperasi dalam siklus bernalar, bertindak melalui pemanggilan tool, dan mengamati hasilnya. Deskripsi tool membentuk antarmuka langsung antara model dan lingkungan. Deskripsi yang samar menghasilkan perilaku yang samar.

Bash berfungsi sebagai tool serbaguna yang hebat. Alih-alih membangun fungsi Python spesifik untuk setiap kemungkinan aksi, Bash memungkinkan agen menyusun perintah yang tepat yang dibutuhkannya secara dinamis. Anda harus menyandikan (sandbox) perintah ini dengan cermat untuk mencegah kerusakan sistem.

Memori: AGENTS.md dan injeksi pengetahuan

Agen Anda memerlukan memori spesifik proyek untuk memahami konvensi lokal. File AGENTS.md adalah dokumen markdown datar di root repositori yang dimasukkan ke system prompt di setiap giliran. File ini mendefinisikan tumpukan teknologi Anda, aturan pemformatan, dan tindakan terlarang.

Jaga file ini di bawah 60 baris. Perlakukan seperti checklist pilot, bukan panduan gaya komprehensif. Anda dapat membaca tutorial AGENTS.md lengkap untuk contoh yang lebih mendalam. Anda juga sebaiknya mempertimbangkan tool Model Context Protocol (MCP) untuk pengetahuan pasca-cutoff.

Hook: lapisan penegakan

Hook adalah skrip kecil yang berjalan pada titik-titik tertentu dalam siklus hidup. 

Anda bisa menjalankan hook sebelum pemanggilan tool, setelah pengeditan file, atau sebelum commit Git. Lihat panduan tentang Claude Code Hooks untuk pola hook tingkat lanjut.

Prinsip desain utama untuk hook adalah keberhasilan bersifat senyap, namun kegagalan bersifat verbose. Pemeriksaan tipe yang lolos tidak menghasilkan output. 

Kegagalan menyuntikkan teks error yang tepat kembali ke loop agen untuk koreksi mandiri.

Kompaksi konteks: melawan context rot

Context rot terjadi ketika kepatuhan terhadap instruksi menurun seiring jendela konteks terisi dengan riwayat percakapan yang panjang. Rangka AI agent yang solid harus mengelolanya secara aktif. Baca lebih lanjut tentang jendela konteks untuk memahami batasan ini.

Anda dapat mengurangi konteks dengan merangkum pesan yang lebih lama. Anda dapat memindahkan output tool yang besar ke disk dan hanya menyimpan referensi singkat di prompt. 

Terakhir, Anda dapat mengisolasi sub-tugas yang boros token ke subagen dengan konteksnya sendiri yang segar.

Membangun Agent Harness Minimal di Python

Membangun agent harness AI melibatkan penulisan kode orkestrasi Python yang mengikat loop ReAct, tool, dan hook bersama. 

Pahami hubungan ini sebelum menulis kode apa pun: harness.py adalah agennya, dan Anda menjalankannya sendiri dengan python harness.py seperti skrip lainnya. 

Model adalah API jarak jauh yang tidak pernah melihat file ini; model hanya menerima system prompt, riwayat pesan, dan skema tool yang dikirim skrip Anda.

Setiap potongan di bagian ini adalah bagian dari satu file, harness.py, dan 4 bagian pertama membangunnya dari atas ke bawah. 2 bagian terakhir (hook dan kompaksi) meningkatkannya, dan karena loop dieksekusi segera saat Python mencapainya, definisi fungsinya harus berada di atas loop; setiap bagian memberi tahu Anda tepat di mana kodenya ditempatkan.

Penyiapan akun dan struktur proyek

Untuk membangunnya, Anda memerlukan akun developer dengan penyedia pilihan Anda. Langganan konsumen standar (seperti ChatGPT Plus atau Claude Pro) tidak memberikan akses API.

1. Penyiapan Anthropic/OpenAI: Daftar di konsol developer penyedia dan atur profil penagihan pay-as-you-go. Hasilkan kunci API dan ekspor ke lingkungan lokal Anda sebagai ANTHROPIC_API_KEY (atau OPENAI_API_KEY).
2. Alternatif lokal: Jika Anda ingin sepenuhnya menghindari biaya API, Anda dapat menjalankan Ollama secara lokal. Ollama mengekspos endpoint lokal yang dapat Anda kueri tanpa kunci API.

Untuk contoh ini, kita akan menggunakan Anthropic, jadi pastikan untuk memasang paket Python Anthropic menggunakan pip install anthropic.  

Selanjutnya, buat kerangka proyek. Penamaan setiap file sejak awal itu penting: loop kita akan membaca AGENTS.md saat startup, jadi file itu harus ada sebelum loop berjalan.

agent-harness/
├── AGENTS.md        # Project memory (we write this first)
├── harness.py       # The ReAct loop, tools, and hooks
└── workspace/       # The only directory the agent may touch

Direktori workspace/ adalah sandbox si agen. Semua yang dibaca, ditulis, atau dieksekusi agen terjadi di dalamnya, tidak pernah di root proyek Anda.

Menulis AGENTS.md dan menyuntikkannya ke system prompt

Kita menulis AGENTS.md sebelum loop karena loop bergantung padanya. 

Buat file di root proyek Anda dan sertakan detail tumpukan spesifik Anda dan batasan arsitektural:

# Project Context
Stack: Python 3.11, Pytest
Workspace: All commands run inside the workspace/ directory.

# Rules
1. Never use rm -rf. Use standard rm with specific file names.
2. Never write tests inside the main application file.
3. When you finish the task, reply with a plain-text summary and no tool call.

Loop kita akan memperlakukan "model merespons tanpa meminta tool" sebagai sinyal tugas-selesai, jadi kita beri tahu model secara eksplisit cara memberi sinyal penyelesaian. 

Aturan yang merujuk mekanisme loop Anda sendiri adalah kunci rekayasa harness. File memori dan kode orkestrasi dirancang bersama.

Sekarang mulai harness.py dengan membuat file ini sebagai system prompt dan menyiapkan workspace:

import subprocess
from pathlib import Path

import anthropic

client = anthropic.Anthropic()

WORKSPACE = Path("workspace")
WORKSPACE.mkdir(exist_ok=True)

# Project memory: AGENTS.md lands in the system prompt on every turn
system_prompt = Path("AGENTS.md").read_text()

Karena SDK mengirim system_prompt di setiap panggilan API, aturan dalam AGENTS.md disuntikkan ulang di setiap giliran. Model tidak dapat "melupakan" aturan-aturan itu seperti ia melupakan instruksi di tengah percakapan.

Mendefinisikan tool: memberi loop tangan

Kita mendefinisikan 2 tool: run_bash untuk eksekusi serbaguna dan write_file untuk membuat file. 

Tool kedua mungkin terlihat redundan karena Bash dapat menulis file dengan heredoc, tetapi write_file khusus memberi kita event edit yang bersih yang bisa dipicu oleh hook pasca-edit nanti. 

Keputusan desain harness seperti ini selalu tentang apa yang ingin Anda observasi dan egakkan.

Deskripsi tool adalah antarmuka, dan kualitasnya secara langsung mengendalikan perilaku agen:

• Samar: "Menjalankan bash." Agen akan menggunakannya untuk segala hal, termasuk menulis file Python multi-baris melalui heredoc rapuh dengan escaping yang rusak.
• Spesifik: "Jalankan perintah bash di dalam direktori workspace/. Gunakan untuk menampilkan daftar file, menjalankan skrip, dan menjalankan tes. Jangan gunakan untuk membuat file Python; gunakan write_file sebagai gantinya." Agen merutekan pekerjaan ke tool yang tepat tanpa prompting tambahan.

Melanjutkan di file harness.py kita, kini kita dapat mendefinisikan skema tool pada baris berikut:

TOOLS = [
    {
        "name": "run_bash",
        "description": (
            "Run a bash command inside the workspace/ directory and return "
            "its stdout, stderr, and exit code. Use it to list files, run "
            "scripts, and run tests. Do not use it to create Python files; "
            "use write_file instead."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "The bash command to run."}
            },
            "required": ["command"],
        },
    },
    {
        "name": "write_file",
        "description": (
            "Create or overwrite a file inside the workspace/ directory. "
            "Provide a path relative to workspace/ and the full file content."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Path relative to workspace/."},
                "content": {"type": "string", "description": "Full file content."},
            },
            "required": ["path", "content"],
        },
    },
]

Blok berikut ini mendefinisikan fungsi Python aktual yang akan mengeksekusi perintah-perintah tersebut. 

Perhatikan fitur keamanan berikut yang telah dibangun: timeout keras agar perintah yang macet tidak menggantungkan harness, exit code disertakan dalam setiap hasil sehingga agen dapat membedakan keberhasilan dari kegagalan, dan pemeriksaan path sehingga write_file() tidak keluar dari sandbox.

def run_bash(command: str) -> str:
    result = subprocess.run(
        command,
        shell=True,
        capture_output=True,
        text=True,
        cwd=WORKSPACE,
        timeout=60,
    )
    output = (result.stdout + result.stderr).strip()
    return f"exit code: {result.returncode}\n{output or '(no output)'}"


def write_file(path: str, content: str) -> str:
    target = (WORKSPACE / path).resolve()
    if WORKSPACE.resolve() not in target.parents:
        return "Error: path escapes the workspace/ directory."
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text(content)
    return f"Wrote {len(content)} characters to {path}."


TOOL_EXECUTORS = {"run_bash": run_bash, "write_file": write_file}

or '(no output)' fallback ini bukan kosmetik. 

Perintah seperti touch data.csv berhasil tanpa output, dan mengembalikan string kosong tidak memberi model apa pun untuk diamati. 

Selalu beri agen sinyal eksplisit, bahkan untuk keheningan.

Loop agen ReAct

Inti dari harness kita adalah loop for Python standar dengan batas iterasi. 

Setiap putaran memanggil API, memeriksa apakah model meminta tool, mengeksekusi setiap tool yang diminta, dan memberi umpan balik hasilnya sebagai satu pesan. 

Blok ini berada di bagian bawah harness.py, karena mulai dieksekusi saat Python mencapainya.

	messages = [
	    {
	        "role": "user",
	        "content": "Create a fizzbuzz.py script in the workspace, "
	                   "then run it to verify the output.",
	    }
	]

	MAX_STEPS = 15

	for step in range(MAX_STEPS):
	    print(f"--- Iteration {step + 1} ---")

	    response = client.messages.create(
	        model="claude-sonnet-5",
	        max_tokens=2000,
	        system=system_prompt,
	        messages=messages,
	        tools=TOOLS,
	    )

	    # Append the model's turn to the history
	    messages.append({"role": "assistant", "content": response.content})

	    # Stop condition: the model answered without requesting a tool
	    if response.stop_reason != "tool_use":
	        final_text = "".join(b.text for b in response.content if b.type == "text")
	        print(f"Task complete: {final_text}")
	        break

	    # Execute EVERY tool call in this turn, collecting the results
	    tool_results = []
	    for block in response.content:
	        if block.type != "tool_use":
	            continue
	        print(f"Agent calling {block.name}: {block.input}")
	        output = TOOL_EXECUTORS[block.name](**block.input)
	        tool_results.append(
	            {"type": "tool_result", "tool_use_id": block.id, "content": output}
	        )

	    # All tool results for one assistant turn go back in ONE user message
	    messages.append({"role": "user", "content": tool_results})
	else:
	    print("Stopped: hit the maximum iteration cap without finishing.")

Dua detail dalam loop ini mencegah crash nyata. 

Pertama, satu giliran model dapat memuat beberapa pemanggilan tool, dan API Anthropic mengharuskan semua hasilnya kembali dalam satu pesan user. 

Kedua, konstruksi for/else melaporkan saat agen mencapai batas iterasi, sehingga run yang macet gagal dengan bising alih-alih berakhir dalam keheningan.

Struktur eksplisit ini memungkinkan Anda melihat tepat di mana model berhenti berpikir, di mana Python mengambil alih untuk menjalankan perintah, dan bagaimana output masuk kembali ke loop.

Menambahkan hook pasca-edit

Hook menangkap kesalahan sebelum berkembang menjadi masalah struktural yang lebih besar. 

Dalam harness kita, hook adalah fungsi yang memeriksa pemanggilan tool yang selesai dan mengembalikan teks tambahan untuk ditambahkan ke hasil tool. 

Keberhasilan mengembalikan string kosong; kegagalan mengembalikan laporan yang verbose.

Tambahkan fungsi ini ke harness.py di atas loop ReAct, di samping executor tool. Loop mulai berjalan saat Python mencapainya, jadi semua yang dipanggil harus sudah didefinisikan.

def post_edit_hook(tool_name: str, tool_input: dict) -> str:
    """Run pytest after any edit to a Python file. Silent on success."""
    edited_python = (
        tool_name == "write_file" and tool_input.get("path", "").endswith(".py")
    )
    if not edited_python:
        return ""

    tests = subprocess.run(
        ["pytest", "--tb=short", "-q"],
        capture_output=True,
        text=True,
        cwd=WORKSPACE,
        timeout=120,
    )
    # Exit code 5 means "no tests collected", which is fine for our purposes
    if tests.returncode in (0, 5):
        return ""
    return f"\n\n[HOOK] pytest failed after this edit:\n{tests.stdout}"

Menghubungkannya ke dalam loop adalah perubahan satu baris di dalam blok eksekusi tool:

output = TOOL_EXECUTORS[block.name](**block.input)
output += post_edit_hook(block.name, block.input)  # hooks run after every tool call

Tanpa hook, agen menulis file yang rusak, melihat Wrote 412 characters to fizzbuzz.py, dan dengan percaya diri lanjut. 

Dengan hook, hasil tool yang sama membawa traceback pytest yang tepat. Pada iterasi berikutnya, agen membaca error tersebut dan memperbaiki bug sendiri, tanpa prompting tambahan.

Kompaksi konteks dasar

Untuk melawan context rot, pantau panjang daftar messages Anda dan rangkum giliran terlama saat daftar menjadi terlalu panjang. 

Ada satu jebakan: Anda tidak dapat memotong riwayat pada titik sembarang, karena blok tool_use asisten dan pesan tool_result pasangannya harus tetap bersama. Memisahkan pasangan menghasilkan error API seketika.

Fungsi kompaksi kita memindahkan titik potong maju hingga mendarat pada batas yang aman. Bangun ini di atas harness.py:

COMPACTION_THRESHOLD = 20
KEEP_RECENT = 6


def is_tool_result(message: dict) -> bool:
    return (
        message["role"] == "user"
        and isinstance(message["content"], list)
        and any(
            isinstance(b, dict) and b.get("type") == "tool_result"
            for b in message["content"]
        )
    )


def compact(messages: list) -> list:
    if len(messages) <= COMPACTION_THRESHOLD:
        return messages

    # Never orphan a tool_result from its tool_use: slide the cut forward
    cut = len(messages) - KEEP_RECENT
    while cut < len(messages) and is_tool_result(messages[cut]):
        cut += 1

    old, recent = messages[1:cut], messages[cut:]
    transcript = "\n".join(f"{m['role']}: {str(m['content'])[:500]}" for m in old)

    summary = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=500,
        messages=[{
            "role": "user",
            "content": "Summarize this agent transcript. Preserve the task, "
                       "decisions made, files created, and any unresolved "
                       f"errors:\n\n{transcript}",
        }],
    )

    return [
        messages[0],  # always keep the original task verbatim
        {
            "role": "user",
            "content": f"[Earlier progress, summarized by the harness]\n"
                       f"{summary.content[0].text}",
        },
        *recent,
    ]

Tambahkan satu baris di bagian atas loop ReAct, sebelum panggilan API:

messages = compact(messages)

Kita menggunakan model yang lebih kecil dan lebih murah untuk ringkasan karena kompaksi sering berjalan dan membutuhkan kecepatan. 

Kita juga menyimpan pesan tugas asli secara verbatim alih-alih mempercayakan ringkasan untuk mempertahankannya.

Harness sekarang sudah lengkap. 

Sebelum melanjutkan, periksa bahwa harness.py Anda dibaca dalam urutan ini dari atas ke bawah:

1. Import, client, WORKSPACE, dan system_prompt
2. Daftar skema TOOLS
3. Executor: run_bash(), write_file(), dan TOOL_EXECUTORS
4. Hook: post_edit_hook()
5. Kode kompaksi: COMPACTION_THRESHOLD, KEEP_RECENT, is_tool_result(), dan compact()
6. Loop ReAct, selalu terakhir

Untuk memberi gambaran tentang seperti apa loop API final setelah kita menambahkan bagian hook dan kompaksi, berikut loop yang sudah jadi secara utuh:

messages = [
    {
        "role": "user",
        "content": "Create a fizzbuzz.py script in the workspace, "
                   "then run it to verify the output.",
    }
]

MAX_STEPS = 15

for step in range(MAX_STEPS):
    print(f"--- Iteration {step + 1} ---")

    # Compaction: summarize old turns before they rot the context
    messages = compact(messages)

    # The API call: model, memory, history, and tools travel together
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=2000,
        system=system_prompt,   # AGENTS.md text, re-injected every turn
        messages=messages,      # the full (possibly compacted) history
        tools=TOOLS,            # the schemas from the tools section
    )

    # Append the model's turn to the history
    messages.append({"role": "assistant", "content": response.content})

    # Stop condition: the model answered without requesting a tool
    if response.stop_reason != "tool_use":
        final_text = "".join(b.text for b in response.content if b.type == "text")
        print(f"Task complete: {final_text}")
        break

    # Execute EVERY tool call in this turn, collecting the results
    tool_results = []
    for block in response.content:
        if block.type != "tool_use":
            continue
        print(f"Agent calling {block.name}: {block.input}")
        output = TOOL_EXECUTORS[block.name](**block.input)
        output += post_edit_hook(block.name, block.input)  # hooks run after every tool call
        tool_results.append(
            {"type": "tool_result", "tool_use_id": block.id, "content": output}
        )

    # All tool results for one assistant turn go back in ONE user message
    messages.append({"role": "user", "content": tool_results})
else:
    print("Stopped: hit the maximum iteration cap without finishing.")

Sekarang jalankan agen dari root proyek python harness.py.

Skrip mengirim tugas dari daftar messages ke API. 

Harness melakukan pekerjaan dan Anda akan melihat setiap iterasi tercetak di terminal:

--- Iteration 1 ---
Agent calling write_file: {'path': 'fizzbuzz.py', 'content': 'def fizz(n):...'}
--- Iteration 2 ---
Agent calling run_bash: {'command': 'python fizzbuzz.py'}
--- Iteration 3 ---
Task complete: fizzbuzz.py is written and prints the correct sequence.

Program keluar ketika model menjawab tanpa pemanggilan tool, atau ketika batas 15 iterasi terlewati. 

Untuk memberi agen tugas yang berbeda, ubah string content dalam daftar messages awal; harness produksi akan membacanya dari input() atau argumen baris perintah sebagai gantinya.

Meningkatkan Agent Harness Anda: Ratchet dalam Aksi

Ratchet adalah proses berkelanjutan mendiagnosis kegagalan agen dan memperbarui harness Anda untuk mencegahnya. 

Sebuah harness meningkat secara ketat melalui paparan kasus tepi dunia nyata.

Mari kita lalui satu siklus kegagalan dan perbaikan lengkap berdasarkan proyek optimasi rute nyata. 

Bayangkan agen Anda terus mengimpor library routing internal yang usang bernama legacy_route_math alih-alih versi yang diperbarui. 

Agen menulis skrip, tes gagal, dan ia terjebak dalam loop mencoba memperbaiki sintaks alih-alih mengganti library.

Diagnosisnya di sini lugas. 

Agen sederhana saja tidak tahu library itu usang. Ini adalah aturan yang hilang, bukan kegagalan jaringan saraf yang mendasarinya.

Perbaikan 1 memperbarui lapisan memori, tambahkan satu aturan ini ke AGENTS.md:

# Rules
1. Never use rm -rf. Use standard rm with specific file names.
2. Never write tests inside the main application file.
3. When you finish the task, reply with a plain-text summary and no tool call.
4. Do not import legacy_route_math; it is deprecated. Use routes_v2 instead.

Perbaikan 2 menambahkan hook penegakan permanen. 

Aturan adalah nasihat bagi agen, hook adalah perintah. Perbaikan ini hanya beberapa baris dan dapat ditambahkan di samping post_edit_hook(), selama berada sebelum loop ReAct.

def deprecated_import_hook(tool_name: str, tool_input: dict) -> str:
    if tool_name != "write_file":
        return ""
    if "import legacy_route_math" in tool_input.get("content", ""):
        return (
            "\n\n[HOOK] Blocked pattern: legacy_route_math is deprecated. "
            "Rewrite this file using routes_v2 instead."
        )
    return ""

Daftarkan di samping hook pytest dalam blok eksekusi tool:

output += post_edit_hook(block.name, block.input)
output += deprecated_import_hook(block.name, block.input)

Beginilah tampilan koreksi mandiri di transkrip setelah kedua perbaikan diterapkan. 

Agen menulis file, hook menyala, dan pada giliran berikutnya memperbaiki import tanpa manusia di dalam loop:

--- Iteration 3 ---
Agent calling write_file: {'path': 'optimizer.py', ...}
  [HOOK] Blocked pattern: legacy_route_math is deprecated...
--- Iteration 4 ---
Agent calling write_file: {'path': 'optimizer.py', ...}   # now imports routes_v2
--- Iteration 5 ---
Task complete: Rewrote optimizer.py using routes_v2 and verified the tests pass.

Ini penting karena terkait kembali ke context rot. Sesi yang sangat panjang dengan konteks yang menurun pada akhirnya akan mengabaikan aturan memori. 

Aturan AGENTS.md mencegah kesalahan sebagian besar waktu, dan hook menjamin saat aturan terlewat, kesalahan tersebut tidak menimbulkan kerusakan. 

Setiap kegagalan yang Anda diagnosis seharusnya membuat Anda mengajukan 2 pertanyaan: aturan apa yang hilang, dan pemeriksaan apa yang akan menangkapnya bagaimanapun juga?

Praktik Terbaik untuk Rekayasa Agent Harness

Praktik terbaik untuk rekayasa agent harness berfokus pada menjaga konfigurasi tetap ramping dan mendesain untuk peningkatan model di masa depan. 

Tujuannya adalah membangun perancah yang menopang model tanpa membebaninya. 

Saya telah memetik beberapa pelajaran berat saat membangun berbagai keterampilan agen dan arsitektur.

Jaga AGENTS.md tetap singkat dan berdasarkan pengalaman

Targetkan maksimum 60 baris untuk file konteks Anda. 

Setiap aturan harus ditelusuri kembali ke kegagalan nyata yang didokumentasikan yang Anda alami. Jika Anda tidak dapat mengingat insiden untuk aturan itu, maka layak untuk dihapus.

Disiplin ini penting karena AGENTS.md dibayar di setiap giliran. 

Panduan gaya 300 baris membuat Anda mengeluarkan token di setiap panggilan API dan mengencerkan aturan yang penting, karena model lebih baik mengikuti 10 aturan tajam daripada 80 aturan samar. 

Menambahkan cap tanggal bahkan dapat membantu praktik berikutnya yang saya rekomendasikan.

Rancang untuk keusangan

Harness perlu direkayasa ulang secara konstan seiring model dasar meningkatkan kemampuan alaminya. 

Bangun komponen Anda sehingga dapat dengan mudah dilucuti.

Pola hook dalam tutorial ini secara sengaja modular karena alasan ini. 

Setiap hook adalah fungsi terpisah yang kemudian ditambahkan hanya dengan satu baris. Jika Anda men-deprecate hook tersebut, Anda tinggal menghapus satu baris di loop. 

Tidak ada hal lain di loop yang berubah. 

Bandingkan dengan logika validasi yang ditenun langsung ke loop ReAct Anda, di mana menghapus pemeriksaan usang berarti menguji ulang seluruh jalur orkestrasi.

Apa yang hari ini terasa seperti tongkat penyangga yang diperlukan akan menjadi beban yang tidak perlu pada kuartal depan. 

Saat model baru dirilis, jalankan ulang kasus kegagalan lama Anda dengan setiap hook dinonaktifkan satu per satu, dan perlakukan setiap hook yang tidak lagi menangkap apa pun sebagai kandidat untuk dihapus. 

Lihat Claude Code Best Practices untuk lebih banyak tips arsitektur.

Mulai sederhana dan lapiskan kompleksitas

Loop ReAct sederhana dengan sistem berkas dan satu tool Bash sudah sangat praktis. 

Tahan keinginan untuk secara pre-emptive membangun sistem graf kompleks menggunakan framework berat. Ratchet hanya bekerja ke satu arah, dari kegagalan yang teramati ke perbaikan yang ditargetkan. Perbaikan spekulatif membalikkan arahnya.

Tambahkan hook kustom hanya setelah Anda melihat kegagalan tepat yang membenarkannya. Untuk lebih lanjut tentang penataan sistem dasar, lihat panduan ini tentang agen LLM.

Log setiap tindakan agen

Anda tidak dapat melakukan ratchet atas sesuatu yang tidak dapat Anda lihat. 

Loop kita sudah mencetak setiap pemanggilan tool, dan itu adalah observabilitas minimum yang layak: saat sebuah run gagal, transkrip yang tercetak adalah bahan diagnosis Anda.

Seiring harness Anda matang, tulis riwayat pesan penuh setiap sesi ke file JSON ber-stempel waktu di akhir run. 

Transkrip gagal menjadi suite regresi Anda; setelah setiap perubahan harness, putar ulang tugas gagal lama dan konfirmasikan perbaikannya tetap berlaku. 

Ini adalah padanan suite tes bagi engineer harness, dan membedakan harness yang meningkat dari yang sekadar berubah.

Penutup

Rekayasa agent harness adalah realitas praktis untuk membuat model AI melakukan pekerjaan yang berguna. 

Kesenjangan antara apa yang secara teoretis dapat dilakukan model saat ini dan apa yang sebenarnya Anda lihat di produksi sebagian besar adalah kesenjangan harness.

Disiplin ini bukan tentang mempelajari framework tertentu. 

Agent harness AI yang tepat untuk basis kode Anda sepenuhnya dibentuk oleh riwayat kegagalan unik Anda, dibangun secara bertahap melalui metode ratchet.

Siap mempraktikkan konsep-konsep ini? 

Lihat jalur keterampilan AI Agent Fundamentals dari DataCamp untuk terus membangun sistem siap produksi. Anda juga dapat menjelajahi Tutorial Claude Agent SDK untuk lebih banyak contoh kode praktik langsung. 

Anda juga mungkin ingin melihat jalur keterampilan AI for Software Engineering.