Desain Multi-Agent Pipeline di Hermes: Pelajaran dari Build Arcapada

Gua pernah ngerasa bangga cuma karena bisa ngejalanin tiga subagent secara paralel. Sampai suatu pagi, step dua gagal karena step satu kirim data yang belum valid, dan step tiga nyangkut di queue selama 4 jam tanpa satu pun log. Baru sadar: masalahnya bukan agent-nya, tapi tidak ada jembatan state yang jelas antar step.

Build Arcapada di Hermes ngajarin gua satu hal: multi-agent pipeline bukan soal nambahin jumlah worker. Itu soal desain state machine yang ngerti kapan harus pause, kapan harus retry, dan kapan harus abort. Kalau step-nya kurang dari empat atau datanya kecil dan linear, satu script tunggal lebih murah dan lebih bisa di-debug. Multi-agent baru worth it kalau ada bottleneck komputasi yang beda per step, atau kalau step-nya butuh model yang berbeda (satu buat parsing, satu buat reasoning, satu buat generation).

Artikel ini bedah pola yang survive di production: STATE.md pattern buat sinkronisasi antar step, cara deteksi silent stall sebelum jadi insiden, dan guard rails minimal yang bikin pipeline tetap jalan bahkan kalau satu agent ngebug.

Kapan Multi-Agent Worth It vs Overkill

Sebelum bangun pipeline, tanya tiga hal: adakah step yang compute-heavy dan step yang I/O-bound? Kalau jawabannya "ya", separasi agen masuk akal. Contoh konkret di Arcapada: step ekstraksi dokumen pakai model vision-heavy, step reasoning pakai model text-only. Kalau semua step pake model yang sama dan datanya kecil, split agen cuma nambah latensi koordinasi tanpa gain berarti.

Overkill biasanya muncul karena FOMO. Sine "canggih" karena ada banyak agent, padahal satu loop sekuen dengan state variable lebih robust. Test sederhana: kalau lo bisa gantikan 3 agent dengan 1 script pake if-else dan masih maintainable, mending script. Complexity biaya: setiap perbatasan antar agent itu tempat bug. Di Arcapada, 70% insiden awal datangnya dari perbatasan, bukan dari dalam agent.

Kapan worth it? Kalau lo punya: (1) step dengan SLA beda-beda (real-time vs batch), (2) kebutuhan scaling independent (step 1 butuh 10x GPU, step 2 cuma butuh CPU), atau (3) failure isolation (kalau step 2 gagal, step 1 dan 3 harusnya bisa jalan lanjut atau abort dengan clean). Arcapada punya ketiganya, makanya desain multi-agent nyimpen waktu operasional.

STATE.md Pattern: Oase di Tengah Gurun Pipeline

Tanpa state management yang eksplisit, setiap agent hanya tahu input dan output dia. Masalahnya: konteks hilang di perbatasan. STATE.md pattern adalah file markdown sederhana yang update di setiap transisi state. Isinya: timestamp terakhir, status step aktif, error terakhir, dan checklist validasi yang lolos.

# STATE.md
last_updated: 2026-05-22T14:30:00Z
active_step: 2-of-4
step_1_status: completed
step_1_output_hash: sha256:abc123...
step_2_status: running
step_2_attempts: 1
last_error: null
pending_actions: [notify_downstream, write_checkpoint]

Kenapa markdown bukan JSON? Karena manusia bisa baca. Di Arcapada, on-call engineer sering perlu scan STATE.md buat quick diagnosis tanpa nge-open dashboard. JSON lebih cepat diparse machine, tapi debug experience kalah jauh. Kompromi: STATE.md buat human-readable snapshot, checkpoint.json buat machine-readable detail. Dua file, dua audience.

Pola ini juga ngebantu idempotency. Kalau step 2 crash di tengah, restart dari checkpoint terakhir bukan ulang dari nol. STATE.md punya field step_2_checkpoint_offset yang nyimpen posisi terakhir yang berhasil diproses. Retry jadi targetted, bukan brute-force.

Silent Stall Pattern: musuh Sunyi yang Bikin Pipeline Mati

Pola paling berbahaya di Arcapada: step downstream paused karena resource limit atau timeout, tapi step upstream tetep jalan dan numpuk data di queue. Dari luar, pipeline "jalan". Dari dalam, throughput turun 80% tanpa satu pun alert critical. Ini yang gua sebut silent stall.

Deteksinya bukan liat CPU atau memory. Itu liat ratio antara input rate dan output rate per step. Kalau step 1 masukin 100 item/menit tapi step 2 cuma keluarin 5 item/menit, queue step 2 numpuk. Numpuk = backlog = silent stall. Implementasi di Hermes: setiap step punya metrik queue_depth yang di-export ke Prometheus. Alert bukan pas queue penuh, tapi pas slope-nya positif selama 5 menit berturut-turut.

Perbaiki pola ini dengan backpressure eksplisit. Step 2 harus bisa "ngomong" ke step 1 kalau dia kewalahan. Di Arcapada, step 2 kirim sinyal pause_upstream kalau queue depth dia lewat threshold. Step 1 ngepause fetch, bukan nge-stop, cuma nahan. Begitu step 2 ngehandle beberapa item, sinyal resume_upstream dikirim. Ini lebih robust daripada drop data karena buffer penuh.

Guard Rails di Setiap Step: Buffer Check & Duplicate Guard

Setiap step di Arcapada punya dua guard wajib. Pertama, buffer check: validasi ukuran payload masuk. Kalau payload melebihi limit, reject dengan error spesifik, bukan crash. Kedua, duplicate guard: hash input sebelum proses. Kalau hash udah ada di set sudah-diproses, skip. Ini nyimpen dari reprocessing saat retry.

Guard rails bukan opsional. Di Arcapada, satu minggu awal ada bug di step 3 yang bikin dia proses item dua kali karena retry tanpa idempotency key. Dampaknya: data ganda di downstream, 3 jam buat cleaning. Setelah duplicate guard kepasang, problem class itu hilang total.

Implementasi simple:

def guard_check(input_data: dict) -> bool:
    # Buffer check
    if len(input_data["payload"]) > MAX_PAYLOAD_BYTES:
        raise PayloadTooLargeError(f"Size {len(input_data['payload'])} > {MAX_PAYLOAD_BYTES}")

    # Duplicate guard
    input_hash = hashlib.sha256(json.dumps(input_data, sort_keys=True).encode()).hexdigest()
    if input_hash in processed_set:
        return False  # Skip, sudah diproses

    return True

Setiap guard gagal harus log dengan context: step berapa, input hash apa, error apa. Ini yang bikin post-mortem cepat. Tanpa context, lo cuma tau "ada error", bukan "step 2 gagal di input #4523 karena payload corrupt di field X".

Monitoring Pipeline Sehat Tanpa Cek Manual Tiap Hari

Monitoring yang baik bikin lo bisa tidur. Di Arcapada, dashboard Grafana punya 3 panel utama: (1) throughput per step, (2) queue depth per perbatasan, (3) error rate per step. Alert hanya untuk anomali, bukan nilai absolut. Kalau throughput turun 30% dari baseline 7 hari, alert. Bukan pas throughput di bawah 100 item/menit (nol-slash threshold).

Pola penting: setiap step punya "health signal" yang eksplisit. Bukan cuma "nggak error", tapi "proses item terakhir dalam X menit". Kalau step 2 terakhir ngirim output 10 menit lalu tapi step 1 tetep ngepush data, health signal step 2 merah. Ini deteksi silent stall yang lebih awal daripada nunggu queue penuh.

SOP incident juga bagian dari monitoring. Di Arcapada, ada dokumen runbook per step: apa yang terjadi kalau step 3 gagal, apa yang perlu dicek, urutan recovery. Tanpa runbook, on-call baru ngerasa "tunggu dulu step apa yang macet?" saat insiden. Dengan runbook, mereka langsung tau: "step 3 stuck, cek STATE.md, liat last_error, retry dari checkpoint". Waktu mean-time-to-recovery turun dari 45 menit ke 12 menit setelah runbook kepasang.

Insight & Implikasi: Arsitektur Pipeline Bukan Aset Statis

Pelajaran terbesar dari Arcapada: pipeline bukan dibangun sekali terus. Evolusinya konstan. Step yang tadinya simple tiba-tiba kompleks karena data berubah. Step yang tadinya batch tiba-tiba perlu real-time. Arsitektur yang kaku mati dalam 6 bulan.

Implikasi buat tim yang mau bangun pipeline multi-agent: mulai dengan 2 step, bukan 5. Tambah step baru setelah step awal stabil. Setiap step baru bawa guard rails dan STATE.md update pattern dari awal, bukan retrofit. Retrofit selalu lebih mahal daripada desain awal yang benar.

Juga: jangan anggap "semua step harus paralel". Kadang satu step memang harus sequential karena dependensi data. Di Arcapada, step 2 ke step 3 memang harus tunggu, tapi step 1 dan step 4 bisa paralel. Desain dependensi, bukan desain jumlah agen.

Penutup

Gambar arsitektur pipeline lo sekarang. Bukan diagram bagus, tapi diagram yang jujur: tunjukkan perbatasan antar step, tunjukkan di mana data numpuk, tunjukkan di mana lo skip validasi karena "sekarang aman". Identifikasi single point of failure di diagram itu. Biasanya ada satu step yang kalau mati, semua mati. Tempatkan guard rails paling kuat di step itu, dan pastikan STATE.md cover perbatasan tersebut. Pipeline sehat bukan yang nggak pernah gagal, tapi yang gagal dengan cara yang bisa lo repair dalam hitungan menit, bukan hari.