# Panduan Middleware LangChain create_agent: PII, Limit, Fallback

> LangChain 1.0 mengganti create_react_agent dengan create_agent dan daftar middleware. Panduan ini memigrasikan agent lama, lalu menambahkan redaksi PII, batas tool call, guard periode tutup buku, retry dengan model fallback, dan persetujuan manusia, serta menjelaskan mengapa urutannya penting.

URL: https://www.matthewswong.com/id/blog/langchain-create-agent-middleware-guide/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-10-01
- Updated: 2026-10-01
- Category: AI

> **Key takeaway:** Di LangChain 1.x, create_agent menggantikan create_react_agent, sementara pre_model_hook, post_model_hook, dan penanganan error ToolNode yang lama kini menjadi middleware. Kelas bawaan mencakup redaksi PII, batas panggilan model dan tool, retry, model fallback, dan persetujuan manusia. Urutan penting: hook before berjalan dari pertama ke terakhir, hook after sebaliknya, dan hook wrap bersarang.

Cari cara menambahkan guardrail ke agent LangChain, dan banyak jawaban teratas masih mengimpor create_react_agent dari langgraph.prebuilt lalu memberinya pre_model_hook. Kode itu menggambarkan API sebelum LangChain 1.0. Rilis 1.0.0 yang terbit di PyPI pada 17 Oktober 2025 memindahkan agent ke langchain.agents.create_agent dan menyatukan argumen hook yang tersebar menjadi satu daftar middleware. Menyalin jawaban lama ke proyek sekarang langsung gagal di argumen ToolNode pertama.

Panduan ini membahas middleware langchain create_agent sesuai dokumentasi langchain 1.4.3, rilis PyPI tanggal 28 September 2026, yang membutuhkan Python 3.10 ke atas. Kita memigrasikan agent accounts-payable kecil dari API lama, menjelaskan enam hook beserta urutan eksekusinya, lalu membangun guardrail yang benar-benar dibutuhkan agent ERP: redaksi PII yang juga mencakup hasil tool, batas panggilan, guard periode tutup buku buatan sendiri, retry yang menyerahkan ke model fallback, dan persetujuan manusia di atas ambang nominal. Semua nama kelas dan parameter diambil dari dokumentasi dan source code LangChain.

## Dari create_react_agent ke create_agent: apa yang berubah

Pergantian nama adalah bagian terkecil dari migrasi. create_agent tetap berjalan di runtime LangGraph, jadi persistence, checkpointing, dan interrupt bekerja seperti sebelumnya, tetapi sebagian besar argumen kustomisasi berpindah tempat. Panduan migrasi mencantumkan semua perubahannya; berikut yang merusak kode lama.

| Sebelum 1.0 | LangChain 1.x | Yang perlu diwaspadai |
| --- | --- | --- |
| from langgraph.prebuilt import create_react_agent | from langchain.agents import create_agent | Runtime LangGraph yang sama di bawahnya, jadi checkpointer tetap terpakai |
| prompt= | system_prompt= | Berupa string; prompt dinamis pindah ke middleware @dynamic_prompt |
| pre_model_hook= | Middleware dengan before_model | Bisa ditumpuk; ringkasan percakapan tersedia sebagai SummarizationMiddleware |
| post_model_hook= | Middleware dengan after_model | Persetujuan tool tersedia sebagai HumanInTheLoopMiddleware |
| model= berupa callable yang memilih model | wrap_model_call dengan request.override(model=...) | Model yang sudah di-bind dengan bind_tools ditolak |
| tools=ToolNode(..., handle_tool_errors=...) | tools=[...] ditambah middleware wrap_tool_call | Instance ToolNode tidak lagi diterima |
| State kustom berupa model Pydantic atau dataclass | TypedDict turunan AgentState | Diatur lewat state_schema di agent atau di middleware |
| Node stream bernama agent | Node stream bernama model | Filter yang mencocokkan nama node diam-diam berhenti cocok |
| Dependensi di config configurable | context= saat invoke, context_schema= di create_agent | Bertipe, dan bisa diakses dari middleware lewat runtime.context |

Berikut agent khas sebelum 1.0 beserta padanannya di 1.x. Hook pemangkas riwayat berubah menjadi middleware ringkasan bawaan, dan error handler ToolNode menjadi fungsi wrap_tool_call empat baris.

Dua perubahan mudah terlewat saat review. Chain lama, retriever, API indexing, dan modul hub pindah ke paket terpisah langchain-classic, jadi impor dari langchain.chains membutuhkan paket itu terpasang. Lalu pergantian nama node streaming terjadi tanpa peringatan: kode yang memfilter event dengan node sama dengan agent tetap berjalan, hanya saja tidak menerima apa pun.

## Cara middleware langchain create_agent dieksekusi

Middleware punya dua jenis hook. Hook bergaya node, yaitu before_agent, before_model, after_model, dan after_agent, berjalan di titik tetap dan mengembalikan dict yang digabung ke state. Hook bergaya wrap, yaitu wrap_model_call dan wrap_tool_call, menerima request dan handler, lalu memutuskan apakah handler dipanggil nol kali, sekali, atau berkali-kali. Dengan tiga middleware dalam daftar, satu giliran model berjalan seperti ini:

1. before_agent berjalan sekali per invocation, dari middleware pertama ke terakhir.
2. before_model berjalan sebelum setiap panggilan model, juga dari pertama ke terakhir.
3. wrap_model_call bersarang seperti pemanggilan fungsi: middleware pertama membungkus yang kedua, yang membungkus yang ketiga, yang membungkus model.
4. after_model berjalan terbalik, dari middleware terakhir ke pertama, setelah model membalas.
5. after_agent berjalan sekali di akhir, juga dari terakhir ke pertama.

Hook bergaya node juga bisa mengakhiri run lebih awal dengan mengembalikan jump_to bernilai end, tools, atau model, asalkan hook tersebut mendeklarasikan targetnya lewat can_jump_to. Begitulah middleware limit bawaan menghentikan loop tanpa melempar exception. Middleware kustom juga bisa mendeklarasikan state_schema untuk menambah field sendiri ke state agent, misalnya counter yang dibaca before_model dan dinaikkan after_model.

> Pakai decorator seperti @before_model dan @wrap_tool_call untuk satu hook tanpa konfigurasi, dan buat subclass AgentMiddleware ketika satu concern butuh beberapa hook, pengaturan saat init, atau versi sync dan async sekaligus. Setiap hook kelas punya kembaran async berawalan a, misalnya abefore_model, dan agent yang dipanggil dengan ainvoke membutuhkannya.

## Redaksi PII yang juga mencakup hasil tool

PIIMiddleware menerima tipe PII, strategi, dan tiga flag cakupan. Tipe bawaannya adalah email, credit_card, ip, mac_address, dan url, dan nama lain pun bisa dipakai bila Anda menyediakan detector berupa string regex, pola yang sudah dikompilasi, atau fungsi. Strateginya adalah block yang melempar PIIDetectionError, redact yang mengganti nilai dengan placeholder REDACTED sesuai nama tipenya, mask yang menyisakan karakter terakhir, dan hash yang mengganti nilai dengan hash deterministik.

Bayangkan agent helpdesk ERP untuk sebuah distributor di Indonesia. Pelanggan menempelkan NIK, nomor induk kependudukan 16 digit, ke chat, dan tool pencarian vendor mengembalikan email kontak langsung dari master data. Tipe kustom nik dengan strategi mask menangani kasus pertama; apply_to_tool_results menangani kasus kedua, yang paling sering terlewat. Hash adalah pilihan yang lebih baik bila model tetap perlu membedakan dua orang tanpa melihat nomor keduanya.

> Secara default hanya input pengguna yang dipindai. apply_to_output dan apply_to_tool_results sama-sama False, jadi tanpa diubah, tool yang mengembalikan data pelanggan mengirim setiap identitas di dalamnya ke penyedia model apa adanya. Aktifkan flag tersebut untuk setiap tipe yang bisa muncul di data tool Anda, dan ingat bahwa detector regex hanyalah filter, bukan program kepatuhan.

## Batas tool call dan batas panggilan model

Dua kelas bawaan menghentikan agent yang berputar-putar. ModelCallLimitMiddleware membatasi jumlah round-trip ke model, dan ToolCallLimitMiddleware membatasi tool call secara global atau untuk satu tool tertentu. Keduanya menerima run_limit, yang direset setiap pesan pengguna, dan thread_limit, yang menghitung sepanjang percakapan sehingga butuh checkpointer untuk menyimpan hitungannya.

- continue, default untuk batas tool: panggilan yang melewati batas dijawab dengan ToolMessage error dan model memutuskan cara menyelesaikan. Cocok untuk lookup yang murah.
- error: middleware melempar ToolCallLimitExceededError dan run berhenti. Cocok untuk tool yang punya efek samping, ketika Anda menginginkan alert, bukan negosiasi.
- end: run langsung berhenti dengan ToolMessage dan pesan AI terakhir. Ini hanya berfungsi saat membatasi satu tool dan melempar NotImplementedError bila ada tool call lain yang masih tertunda.

Setiap batas berdiri sendiri, jadi menumpuk batas global dengan batas per tool adalah hal biasa. ModelCallLimitMiddleware hanya punya end dan error sebagai exit behavior, dengan default end yang mengakhiri giliran secara wajar tanpa melempar exception.

## Menulis guard sendiri dengan wrap_tool_call

Kelas bawaan menangani risiko umum; aturan bisnis butuh middleware sendiri. Fungsi wrap_tool_call melihat nama tool dan argumennya sebelum eksekusi dan bisa mengembalikan ToolMessage tanpa memanggil handler, artinya tool tidak pernah berjalan. Di sini agent ditolak saat mencoba memposting jurnal bertanggal di periode fiskal yang sudah ditutup, dengan tanggal tutup buku dikirim lewat runtime context yang bertipe.

Tulis pesan penolakan untuk model, bukan untuk log. Pesan yang menyebut aturannya dan langkah berikutnya, yaitu minta tanggal di periode yang masih terbuka, membuat model bisa pulih di giliran yang sama, sedangkan string error polos cenderung memicu panggilan yang sama lagi. Karena pengecekan ini berjalan di Python tanpa panggilan model, ia tidak menambah latensi dan tidak bisa dibujuk untuk mengubah keputusannya.

## Retry dan model fallback, dengan urutan yang benar

ModelRetryMiddleware mengulang panggilan model yang gagal dengan exponential backoff; secara default ia melakukan dua retry setelah percobaan pertama, mulai dari satu detik lalu berlipat dua, dengan jitter. ModelFallbackMiddleware menangkap exception dari model utama lalu memanggil rantai di dalamnya lagi dengan setiap model fallback secara bergiliran, dan melempar ulang error terakhir bila semuanya gagal. ToolRetryMiddleware melakukan hal yang sama untuk tool dan bisa dibatasi ke tool dan tipe exception tertentu.

Karena hook wrap bersarang, middleware yang ditulis pertama adalah lapisan terluar. Dengan fallback ditulis sebelum retry, setiap model, baik utama maupun fallback, mendapat jatah retry penuh sebelum fallback berpindah, dan biasanya itulah perilaku yang diinginkan untuk error rate limit yang sementara.

> ModelRetryMiddleware secara default memakai on_failure continue, yang mengubah error terakhir menjadi AIMessage alih-alih melemparnya. ModelFallbackMiddleware hanya bereaksi terhadap exception, jadi dengan pengaturan default fallback tidak pernah aktif dan pengguna malah membaca pesan error. Set on_failure ke error untuk setiap retry yang berada di dalam fallback.

## Persetujuan manusia untuk tool call bernilai besar

HumanInTheLoopMiddleware menjeda run setelah model mengusulkan tool call dan sebelum tool dieksekusi. Setiap entri di interrupt_on memetakan nama tool ke True, False, atau konfigurasi berisi allowed_decisions yang dipilih dari approve, edit, reject, dan respond. Sejak langchain 1.3.3, konfigurasi juga bisa menerima predikat when, sehingga hanya panggilan yang memenuhi syarat yang dijeda. Persetujuan membutuhkan checkpointer dan thread_id, karena state yang dijeda harus bertahan sampai ada yang menjawab.

Keputusan reject menerima message yang dikembalikan ke model sebagai hasil tool. Buat pesannya tegas tentang langkah berikutnya, yaitu batalkan, tanya pengguna, atau coba jalur lain, karena teks default hanya menyebut bahwa tool tidak dijalankan. Jangan pakai respond untuk menolak tool yang punya efek samping: dokumentasi memperingatkan bahwa teksnya diperlakukan sebagai hasil tool yang sukses.

Keputusan berupa list dengan satu entri per aksi yang dijeda, dengan urutan yang sama seperti action_requests. Tiga usulan posting sekaligus berarti butuh tiga keputusan, dan jumlah yang tidak cocok akan melempar ValueError alih-alih menebak.

## Menyusun stack: urutan adalah perilaku

Saat semuanya digabung, daftar middleware bukanlah himpunan; urutannya menentukan siapa melihat apa lebih dulu. Tabel berikut merangkum posisi setiap bagian di contoh di bawah dan alasannya.

| Middleware | Hook | Alasan posisinya |
| --- | --- | --- |
| Entri PIIMiddleware | before_model, after_model | Paling awal di daftar, jadi input sudah dibersihkan sebelum hook lain atau model melihatnya |
| ModelFallbackMiddleware | wrap_model_call | Ditulis sebelum retry, jadi menjadi pembungkus terluar dan baru bertindak setelah retry habis |
| ModelRetryMiddleware | wrap_model_call | Di dalam fallback, dengan on_failure error agar fallback bisa melihat kegagalannya |
| closed_period_guard | wrap_tool_call | Berjalan saat eksekusi, setelah persetujuan, sebagai pengecekan deterministik terakhir sebelum ERP |
| ToolCallLimitMiddleware untuk posting | after_model | Ditulis setelah middleware persetujuan, jadi after_model-nya berjalan lebih dulu dan run yang melewati batas berhenti sebelum ada yang diminta menyetujui |

Satu trade-off masih terlihat di sini. Guard periode tutup buku baru berjalan saat tool dieksekusi, yaitu setelah reviewer menyetujui panggilan, sehingga reviewer bisa menyetujui entri yang kemudian ditolak guard. Untuk kasus yang jarang hal ini masih wajar, dan penolakannya tetap sampai ke model; bila mulai sering terjadi, jalankan pengecekan tanggal yang sama di predikat when juga, agar posting ke periode tertutup tidak pernah masuk antrean persetujuan.

Aturan yang perlu dibawa dari LangChain 1.x: agent kini terdiri dari model, daftar tool, dan daftar middleware yang berurutan, dan urutan itu adalah bagian dari desain. Gunakan kelas bawaan untuk PII, batas, retry, fallback, dan persetujuan, tulis guard wrap_tool_call untuk aturan bisnis, dan periksa setiap default on_failure dan exit_behavior sebelum memercayai stack Anda.

## Sumber

- Dokumentasi LangChain: panduan migrasi LangChain v1
- Dokumentasi LangChain: middleware kustom, hook, urutan eksekusi, dan jump
- Dokumentasi LangChain: referensi middleware bawaan
- Dokumentasi LangChain: middleware human-in-the-loop
- PyPI: paket langchain, riwayat rilis, dan kebutuhan versi Python

## Source links

- https://docs.langchain.com/oss/python/migrate/langchain-v1
- https://docs.langchain.com/oss/python/langchain/middleware/custom
- https://docs.langchain.com/oss/python/langchain/middleware/built-in
- https://docs.langchain.com/oss/python/langchain/human-in-the-loop
- https://pypi.org/project/langchain/

## FAQ

### Apa pengganti create_react_agent di LangChain 1.0?

LangChain 1.0 merekomendasikan langchain.agents.create_agent sebagai pengganti langgraph.prebuilt.create_react_agent. Fungsi ini tetap berjalan di runtime LangGraph, tetapi argumen prompt berganti nama menjadi system_prompt, dan pre_model_hook, post_model_hook, serta penanganan error ToolNode digantikan middleware yang diberikan lewat daftar middleware.

### Bagaimana urutan eksekusi middleware LangChain create_agent?

Hook before_agent dan before_model berjalan dari middleware pertama di daftar sampai yang terakhir. Hook after_model dan after_agent berjalan terbalik, dari terakhir ke pertama. wrap_model_call dan wrap_tool_call bersarang seperti pemanggilan fungsi, jadi middleware yang ditulis pertama menjadi pembungkus terluar.

### Apakah PIIMiddleware meredaksi hasil tool secara default?

Tidak. PIIMiddleware secara default hanya memeriksa input pengguna, sedangkan apply_to_output dan apply_to_tool_results sama-sama bernilai False. Bila tool mengembalikan data pelanggan, set apply_to_tool_results=True untuk setiap tipe PII yang bisa muncul di data itu, atau nilainya sampai ke model tanpa diubah.

### Mengapa ModelFallbackMiddleware tidak berpindah model saat digabung dengan ModelRetryMiddleware?

ModelRetryMiddleware secara default memakai on_failure='continue', yang mengubah error terakhir menjadi AIMessage alih-alih melemparnya. Middleware fallback hanya bereaksi terhadap exception, jadi ia tidak pernah melihat kegagalannya. Set on_failure='error' pada retry dan tulis fallback sebelum retry agar fallback menjadi pembungkus terluar.

### Bagaimana mewajibkan persetujuan manusia hanya untuk transaksi besar di agent LangChain?

Gunakan HumanInTheLoopMiddleware dengan entri interrupt_on untuk tool tersebut dan tambahkan predikat when yang mengembalikan True hanya bila argumennya melewati ambang Anda. Opsi when membutuhkan langchain 1.3.3 atau lebih baru. Agent juga butuh checkpointer dan thread_id agar run yang dijeda bisa dilanjutkan dengan Command yang membawa keputusannya.

---

- HTML version: https://www.matthewswong.com/id/blog/langchain-create-agent-middleware-guide/
- English: https://www.matthewswong.com/en/blog/langchain-create-agent-middleware-guide/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
