12-Factor Agents: Pola Aplikasi LLM yang Dapat Dipercaya

• 12-Factor Agents adalah panduan terbuka yang merangkum 12 prinsip untuk membuat software berbasis LLM yang cukup andal untuk diberikan kepada pelanggan produksi
• Agen yang baik dipandang bukan sekadar pola “beri kumpulan prompt dan tool lalu ulangi sampai tujuan tercapai”, melainkan lebih dekat ke struktur yang menyisipkan langkah LLM pada titik-titik yang diperlukan di dalam software deterministik
• Loop agen umum membuat LLM menentukan langkah berikutnya sebagai pemanggilan tool JSON terstruktur, lalu kode deterministik mengeksekusinya, menambahkan hasilnya ke context window, dan mengulang sampai selesai
• Banyak builder SaaS memulai cepat dengan framework dan mencapai kualitas 70–80%, tetapi itu belum cukup untuk fitur yang berhadapan langsung dengan pelanggan, sehingga mereka mengalami alur merekayasa balik framework, prompt, dan flow, atau memulai ulang dari awal
• Cara tercepat untuk menghadirkan software AI berkualitas tinggi kepada pelanggan bukanlah mengadopsi seluruh framework agen, melainkan mengintegrasikan konsep pembangunan agen yang kecil dan modular ke produk yang sudah ada

---

Kesadaran Masalah Proyek

• 12-Factor Agents adalah proyek terbuka yang mencoba menerapkan semangat 12 Factor Apps pada prinsip pembangunan aplikasi LLM
• Pertanyaan intinya adalah “prinsip apa yang dapat digunakan untuk membuat software berbasis LLM yang benar-benar cukup baik untuk dipercayakan kepada pelanggan produksi”
• Proyek ini berangkat dari pengalaman mencoba berbagai framework agen dan berdiskusi dengan founder teknis di dalam maupun di luar YC
  • Banyak founder membangun stack sendiri, alih-alih banyak memakai framework untuk agen produksi yang berhadapan dengan pelanggan
  • Banyak produk yang disebut “AI Agent” dipandang bukan sepenuhnya agentic, melainkan sebagian besar berupa kode deterministik yang dipadukan dengan langkah LLM secara tepat

Pandangan Dasar tentang Agen

• Agen yang baik tidak hanya tersusun dari pola “prompt, kumpulan tool, lalu ulangi sampai tujuan tercapai”
• Software dapat dilihat sebagai directed graph (DG), dan inilah alasan program dulu sering direpresentasikan sebagai flowchart
• Sejak sekitar 20 tahun lalu, DAG orchestrator mulai digunakan secara luas
  • Contohnya mencakup Airflow, Prefect, dagster, inggest, dan windmill
  • Mereka mengikuti pola graph yang menambahkan observability, modularitas, retry, dan fitur manajemen
• Janji agen adalah, alih-alih engineer harus mengodekan semua langkah dan pengecualian, mereka cukup menyediakan tujuan dan transisi, lalu LLM menentukan jalur secara real time
  • Pendekatan ini membawa harapan untuk menulis lebih sedikit kode, pulih dari error, dan memungkinkan LLM menemukan solusi baru
  • Namun dalam praktiknya, pendekatan ini dinilai tidak bekerja sebaik yang diharapkan

Model Eksekusi Loop Agen

• Loop agen dasar terdiri dari penilaian LLM → eksekusi tool → penambahan hasil ke konteks → pengulangan
• Alurnya sebagai berikut
  • Konteks awal adalah event pemicu seperti pesan pengguna, eksekusi cron, atau webhook
  • LLM menentukan langkah berikutnya atau apakah proses sudah selesai
  • Langkah berikutnya dikeluarkan sebagai pemanggilan tool dalam bentuk JSON terstruktur
  • Kode deterministik mengeksekusi pemanggilan tool tersebut
  • Hasil eksekusi ditambahkan ke context window
  • Jika langkah berikutnya adalah done, jawaban akhir dikembalikan
• Contoh di README menunjukkan loop yang menentukan langkah berikutnya dengan llm.determine_next_step(context), mengeksekusinya dengan execute_step(next_step), lalu menempelkan hasilnya ke konteks

Mengapa Diperlukan 12 Prinsip

• Saat membangun HumanLayer, penulis berbicara dengan setidaknya 100 builder SaaS, yang umumnya adalah founder teknis yang ingin membuat produk mereka yang sudah ada menjadi lebih agentic
• Perjalanan yang umum adalah sebagai berikut
  • Memutuskan untuk membuat agen
  • Menentukan desain produk, pemetaan UX, dan masalah yang akan diselesaikan
  • Memilih framework tertentu agar dapat bergerak cepat
  • Mencapai tingkat kualitas 70–80%
  • Menyadari bahwa kualitas 80% tidak cukup untuk sebagian besar fitur yang berhadapan langsung dengan pelanggan
  • Untuk melampaui 80%, mereka harus merekayasa balik framework, prompt, flow, dan sebagainya
  • Pada akhirnya memulai ulang dari awal
• Kritik ini tidak dimaksudkan untuk menyerang framework atau pembuat framework, dan disebutkan bahwa framework telah mempercepat ekosistem AI
• MCP tidak dibahas, dan meski contoh utamanya memakai TypeScript, prinsipnya disebut dapat diterapkan juga di Python atau bahasa lain

12 Factor

• Meski LLM terus menjadi lebih kuat, teknik engineering inti untuk membuat software berbasis LLM lebih dapat dipercaya, skalabel, dan mudah dipelihara tetap dianggap akan bertahan
• Ke-12 factor tersebut adalah sebagai berikut
  • Factor 1: Natural Language to Tool Calls: mengubah bahasa alami menjadi pemanggilan tool
  • Factor 2: Own your prompts: miliki prompt Anda sendiri
  • Factor 3: Own your context window: miliki context window Anda sendiri
  • Factor 4: Tools are just structured outputs: tool hanyalah output terstruktur
  • Factor 5: Unify execution state and business state: satukan state eksekusi dan state bisnis
  • Factor 6: Launch/Pause/Resume with simple APIs: mulai, jeda, dan lanjutkan dengan API sederhana
  • Factor 7: Contact humans with tool calls: hubungi manusia dengan pemanggilan tool
  • Factor 8: Own your control flow: miliki control flow Anda sendiri
  • Factor 9: Compact Errors into Context Window: padatkan error ke dalam context window
  • Factor 10: Small, Focused Agents: agen yang kecil dan terfokus
  • Factor 11: Trigger from anywhere, meet users where they are: picu dari mana saja dan temui pengguna di tempat mereka berada
  • Factor 12: Make your agent a stateless reducer: jadikan agen Anda reducer tanpa state
• Sebagai saran tambahan, disertakan Factor 13: Pre-fetch all the context you might need

Cara Penerapan dan Materi Terkait

• Mengadopsi seluruh framework hingga pada dasarnya menjadi penulisan ulang greenfield dinilai bisa kontraproduktif
• Prinsip inti yang membuat agen menjadi baik mungkin sebagian besar bisa diperoleh dengan mengadopsi framework, tetapi jalan untuk cepat menghadirkan software AI berkualitas tinggi kepada pelanggan adalah mengintegrasikan konsep yang lebih kecil dan modular ke produk yang sudah ada
• Konsep modular ini disebut dapat didefinisikan dan diterapkan bahkan oleh software engineer berpengalaman yang tidak memiliki latar belakang AI
• Materi terkait yang ditautkan mencakup Building Effective Agents dari Anthropic, Prompts are Functions, Library patterns: Why frameworks are evil, dan The Wrong Abstraction
• Konten dan gambar disediakan dengan lisensi CC BY-SA 4.0, sedangkan kode dengan lisensi Apache 2.0

[GN⁺]

Komentar Hacker News

• Poin-poin dalam tulisan ini bagus sekali. Saya juga punya daftar pelajaran yang saya rangkum setelah mencobanya sendiri selama beberapa tahun: https://mg.dev/lessons-learned-building-ai-agents/
  Kalau sekarang, hal terbesar yang akan saya tambahkan adalah: miliki sendiri planning loop pada level paling rendah. Perencanaan dinamis boleh saja, tetapi Anda perlu memiliki sendiri loop observasi-orientasi-keputusan-aksi (OODA), serta heuristik untuk menilai apakah solusi sedang berkonvergensi (misalnya scoring) atau kondisi untuk keluar (misalnya jumlah iterasi maksimum)
  Selain itu, patut juga dipertimbangkan untuk memasukkan workflow engine. Daripada membuat model mempertahankan dan menjalankan workflow implisit selama beberapa turn, lebih baik model membuat spesifikasi workflow yang akan dijalankan di engine tersebut, lalu pada tiap langkah memanggil model lagi bila diperlukan

  • Panduan ini bagus, dan saya khususnya setuju dengan pandangan bahwa “antarmuka chat itu bodoh”. UI berbasis AI masih punya jalan yang sangat panjang

• Saya penasaran bagaimana library seperti DSPY cocok dengan factor-2: https://dspy.ai/, https://github.com/humanlayer/12-factor-agents/blob/main/con...
  Saat membaca, saya melihat ada bagian tentang membuat prompt dengan BAML. Secara pribadi, menulis prompt secara manual untuk mengekstrak informasi terstruktur dari data tak terstruktur tidaklah mudah, dan sejauh ini pengalaman saya dengan DSPY cukup baik
  Jika memakai prompt mentah BAML, saya penasaran bagaimana Anda melihat cara memakai prompt mentah DSPY: https://dspy.ai/tutorials/observability/#using-inspect_histo...

  • Menarik, tetapi untuk bagian ini saya lebih sejalan dengan posisi Boundary (YC W23). Jika menginginkan performa mutakhir, Anda harus bisa membuka kotaknya dan memperbaiki bagian dalamnya sendiri
    Saya tidak sepenuhnya setuju dengan tulisan https://www.chrismdp.com/beyond-prompting/, tetapi perbandingan kartu punch → assembly → C → bahasa tingkat tinggi cukup berguna dalam konteks ini
    Kita belum tahu kapan abstraksi yang tepat akan muncul, dan menurut saya LangChain maupun DSPY belum menjadi “bahasa pemrograman C”-nya AI. Suatu saat mungkin saja
    Untuk sekarang, saya akan memakai workbench level rendah yang memungkinkan saya memeriksa token, mengubah urutan token khusus seperti system/user/JSON, dan cepat menyesuaikan diri dengan keanehan model baru tanpa terikat sambil menunggu dukungan library

• Ada tulisan lama yang kurang dikenal tentang pola framework yang terus terasa relevan sepanjang karier saya, dan menurut saya juga berlaku di sini: https://tomasp.net/blog/2015/library-frameworks/
  Karena alasan-alasan yang dijelaskan dalam tulisan itu dan lebih dari itu, terutama di masa ketika semuanya berubah cepat seperti sekarang, LLM lebih baik digunakan seperti library daripada framework. Namun framework lebih seksi, lebih mudah dijual, dan mengarah ke lock-in serta layanan tambahan, sehingga lebih banyak dipromosikan

  • Analogi ini sangat bagus. Paket wisata seperti membeli framework: transportasi, hotel, makanan, dan aktivitas disesuaikan dengan kerangka yang disediakan framework. Sebaliknya, perjalanan mandiri seperti menggabungkan berbagai library: Anda harus menyusun sendiri tiket pesawat, akomodasi, dan jadwal; lebih merepotkan, tetapi Anda bisa mengendalikannya sesuai keinginan
  • Bagus. Akan saya tambahkan ke bagian tautan

• Saya membuat “framework agen AI” sendiri, SecAI, berbasis actor model, state machine, dan aspect-oriented programming, dan baru saja merilisnya: https://github.com/pancsta/secai
  Saya khususnya suka nomor 5, “satukan execution state dan business state”, serta nomor 8, “miliki sendiri control flow”. Inti SecAI adalah library control flow berbasis graf; bukan DAG, melainkan multigraf, dan pemanggilan LLM ditanamkan di node graf
  Flow diperkuat dengan negosiasi, pembatalan, dan relasi yang memiliki state, sehingga berperilaku lebih organik. Ini juga mencakup tool pengembangan khusus (dbg, repl, svg) yang sering absen di framework lain, pemrograman dengan asumsi kegagalan, kemampuan memeriksa setiap langkah secara rinci, ekspor data otomatis (metrik, trace, log, SQL), serta integrasi sederhana (bash)
  Demo teknis pertama juga sudah dirilis, menampilkan tool pengembangan melalui implementasi referensi deepresearch yang di-port dari AtomicAgents: https://youtu.be/0VJzO1S-gV0
  Tombol Send/Stop pada dasarnya adalah “Factor 6. mulai/jeda/lanjutkan dengan API sederhana”, dan ada juga transparansi jaringan sehingga bisa diskalakan

  • Saya setuju bahwa tool pengembangan khusus sering absen di framework lain. Dari pengalaman saya sendiri, PydanticAI menyelesaikan debugging agen dengan Logfire dengan sangat baik, dan jauh lebih mudah serta efektif dibanding framework dan library lain yang saya uji: https://ai.pydantic.dev/logfire/#pydantic-logfire
  • Saya suka UI terminal dan integrasi OTel-nya. Penasaran sekarang dipakai untuk pekerjaan seperti apa

• Satu tambahan lagi: Anda perlu merencanakan biaya saat skala membesar
  Sistem seperti ini tidak murah ketika skala membesar, jadi jika suatu pekerjaan bisa ditangani oleh komponen deterministik, sebaiknya coba jalur itu lebih dulu. Ini bukan hanya mengurangi halusinasi dan latensi, tetapi juga bisa membuat perbedaan besar pada laba akhir

  • Saya rasa memang begitu. Pola yang paling sering dipakai orang tampaknya adalah “mulai dengan cara yang lambat dan mahal tetapi minim upaya pengembangan, lalu secara bertahap memperbaikinya setelah menemukan bottleneck kecepatan, kualitas, atau biaya yang layak diinvestasikan”

• Agar tiap prinsip lebih mudah diikuti, akan bagus jika ada narasi yang konsisten yang melintasi berbagai factor. Misalnya terus memakai contoh sistem yang mendekati dunia nyata, sehingga lebih mudah dipahami

  • Masukan yang bagus. Saya penasaran jenis use case seperti apa yang cocok
    Saya ingin terus mengembangkannya secara terbuka bersama komunitas

• Bagus sekali. Sekitar 80% sudah saya pelajari dengan susah payah, dan 20% sisanya tampaknya layak dibaca
  Secara pribadi, saya berhasil dengan kombinasi LangGraph + skema pydantic. Saya juga penasaran alat apa yang berguna bagi orang lain

  • Ungkapan “80% sudah saya pelajari dengan susah payah” menarik, karena judul kerja lain untuk tulisan ini adalah Agents the Hard Way, mengikuti semangat https://github.com/kelseyhightower/kubernetes-the-hard-way

• Tulisan ini muncul tepat saat saya membutuhkannya
  Saya sedang bereksperimen dengan ide sandbox audiovisual. Mirip vvvv, tetapi jauh lebih sederhana dan hanya memiliki fitur minimum: https://kfs.mkj.lt/#audiovisllm, https://vvvv.org/
  Idenya adalah menyisipkan LM atau “node” jaringan saraf lokal sederhana yang menangani tugas tertentu dan output-nya sangat dibatasi. Karena itu contoh seperti “question -> answer: float” terasa sangat menarik. Dalam kasus saya, sebagian pertanyaannya bisa cukup abstrak, tetapi pipeline multi-tahap juga menarik

  • Output bertipe dari LLM adalah faktor pengubah permainan

• Saya belum membacanya secara rinci, tetapi saya ingin memakai kode deterministik sebanyak mungkin dan memanfaatkan LLM sesedikit mungkin
  Dengan begitu, menurut saya, hasilnya lebih dapat diprediksi, biaya operasional lebih rendah, dan menjadi sinyal bahwa orang lain tidak mudah menyalin aplikasi yang sama dengan cepat. Alih-alih memakai begitu saja perekat berbasis buzzword untuk menghubungkan LLM dengan sistem lain, saya cenderung membuat alat sendiri
  Jika kondisi seperti ini tidak terpenuhi atau tidak diperlukan, menurut saya seseorang bisa membuat solusi yang sama dalam sekejap dengan vibe coding. Kontrol harus dipertahankan. Saya siap “mati di bukit” soal kontrol ini. Bukan berarti saya tidak kagum pada LLM; justru sebaliknya

  • Kontrol itu bagus, begitu juga determinisme. Tujuan utamanya adalah meyakinkan agar “jangan menyerahkan terlalu banyak kontrol”, tetapi tujuan sekundernya adalah menunjukkan “di titik-titik inilah sebagian kontrol boleh dilepas”