Apa Itu LangGraph? Panduan Membangun Agen AI Stateful

Sebagian besar kode agen dimulai dengan sederhana dan kemudian runtuh karena percobaan ulang yang berulang. Anda menyambungkan LLM, memberikannya beberapa alat, dan saat alur kerja perlu berulang, bercabang, atau berhenti untuk campur tangan manusia, skrip garis lurus itu akan berantakan. LangGraph adalah kerangka kerja yang dibangun untuk mengatasi kekacauan semacam itu: ia memodelkan agen sebagai grafik dengan status bersama, sehingga perulangan dan percabangan menjadi struktur kelas satu alih-alih pernyataan if yang kusut. Panduan ini menjelaskan apa itu LangGraph, masalah yang dipecahkannya, dan di mana pengujian API berperan ketika agen Anda memanggil layanan nyata.

Apa itu LangGraph

LangGraph adalah kerangka kerja orkestrasi tingkat rendah dan runtime untuk membangun agen yang berjalan lama dan memiliki status. Ini dibangun oleh LangChain Inc, tim di balik LangChain, tetapi ini adalah pustaka terpisah dengan fokusnya sendiri. Anda menginstalnya sendiri dengan pip install -U langgraph, dan Anda dapat menggunakannya tanpa ekosistem LangChain lainnya.

Ide intinya sederhana. Anda menjelaskan agen Anda sebagai grafik. Node melakukan pekerjaan (memanggil model, menjalankan alat, mengubah data). Edge memutuskan apa yang berjalan selanjutnya. Objek status bersama mengalir melalui setiap node, dan setiap node dapat membacanya serta menulis kembali ke dalamnya. Karena edge dapat menunjuk ke belakang, grafik dapat berulang. Itulah bagian yang tidak dapat dilakukan dengan baik oleh rantai biasa.

Jika Anda pernah menggunakan abstraksi Chain LangChain yang lebih lama, perbedaannya adalah bentuk alur kontrolnya. Sebuah rantai adalah alur kerja (pipeline): langkah satu, langkah dua, langkah tiga, selesai. Sebuah grafik memungkinkan node memeriksa status saat ini, lalu melompat ke cabang yang berbeda, kembali untuk mencoba lagi, atau menyebar ke beberapa node yang berjalan secara paralel dan menggabungkan hasilnya. Agen nyata membutuhkan itu, karena “berpikir, bertindak, mengamati, berpikir lagi” adalah sebuah perulangan, bukan garis lurus.

Masalah yang dipecahkan LangGraph

Alur kerja agen secara alami bersifat siklis. Agen memanggil alat, melihat hasilnya, memutuskan apakah tugas sudah selesai, dan jika belum, mencoba lagi. Memodelkan hal itu dengan kondisi bersarang akan cepat menjadi tidak terbaca, dan akan semakin buruk setelah Anda menambahkan hal-hal yang benar-benar dibutuhkan agen produksi:

• Perulangan dengan kondisi berhenti.
• Percabangan berdasarkan status.
• Persistensi.
• Human-in-the-loop (Manusia dalam Lingkaran).
• Streaming.

LangGraph mengubah setiap fitur ini menjadi kemampuan bawaan, bukan sesuatu yang Anda buat secara manual. Anda mendapatkan mesin status dengan eksekusi yang tahan lama, sehingga agen dapat berjalan selama menit atau jam dan melanjutkan dari titik terakhir berhenti.

Konsep inti: grafik, status, node, edge

Empat primitif mendukung sebagian besar kerangka kerja ini. Berikut cara kerjanya bersama-sama.

Status (State) adalah objek bertipe yang dibagikan di seluruh eksekusi. Anda mendefinisikan bentuknya dengan skema, seringkali TypedDict, dan LangGraph menggabungkan pembaruan setiap node ke dalamnya. Titik awal yang umum adalah MessagesState, skema bawaan yang menyimpan daftar pesan obrolan yang sedang berjalan.

Node adalah fungsi. Setiap node mengambil status saat ini dan mengembalikan pembaruan parsial. Anda mendaftarkannya dengan add_node().

Edge menghubungkan node. Edge normal dengan add_edge() selalu bergerak dari A ke B. Edge kondisional dengan add_conditional_edges() menjalankan fungsi perutean yang membaca status dan mengembalikan nama node berikutnya, yang merupakan cara Anda mengekspresikan "jika model meminta alat, jalankan; jika tidak, selesaikan."

START dan END adalah penanda khusus untuk di mana eksekusi dimulai dan berhenti.

Berikut adalah bentuk grafik minimal. Ini adalah tingkat pseudokode, tetapi nama API-nya nyata.

from langgraph.graph import StateGraph, START, END, MessagesState

def call_model(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}

def should_continue(state: MessagesState) -> str:
    last = state["messages"][-1]
    return "tools" if last.tool_calls else END

builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", tool_node)
builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model")   # loop back

graph = builder.compile()

Baris add_edge("tools", "model") adalah siklusnya. Setelah alat berjalan, kontrol kembali ke model, yang dapat memanggil lebih banyak alat atau berhenti. Perulangan itulah seluruh alasan LangGraph ada.

Persistensi dan Human-in-the-loop

Kompilasi grafik dengan checkpointer dan itu akan menyimpan snapshot status setelah setiap langkah. Lewati thread_id dalam konfigurasi, dan LangGraph akan memulihkan checkpoint terbaru untuk thread tersebut pada panggilan berikutnya. Node Anda tidak berubah; runtime menangani penyimpanan dan pemulihan.

from langgraph.checkpoint.memory import InMemorySaver

graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [user_message]}, config)

InMemorySaver baik untuk pengembangan. Untuk sesuatu yang dapat bertahan dari restart, LangGraph menyediakan saver yang didukung basis data (SQLite untuk satu server, Postgres untuk skala multi-instansi). Karena statusnya tahan lama, Anda juga mendapatkan human-in-the-loop hampir secara gratis. Anda dapat menginterupsi grafik pada titik yang dipilih, menampilkan status saat ini agar seseorang dapat memeriksa atau mengedit, lalu melanjutkan dari checkpoint yang tepat itu. Gerbang persetujuan, koreksi manual, dan langkah-langkah "apakah Anda yakin?" semuanya dibangun di atas ini.

Streaming melengkapinya. LangGraph dapat melakukan streaming token model dan pembaruan tingkat node saat eksekusi berlangsung, sehingga antarmuka pengguna dapat menunjukkan agen sedang berpikir alih-alih menatap ikon pemutar.

Bagaimana LangGraph berhubungan dengan LangChain

Ini sering membingungkan orang, jadi mari kita perjelas. LangChain adalah toolkit yang lebih luas: pembungkus model, template prompt, retriever, pemuat dokumen, dan integrasi dengan ratusan penyedia. LangGraph adalah lapisan orkestrasi di bawah bagian agen dari toolkit tersebut.

Anda tidak memerlukan LangChain untuk menggunakan LangGraph. Anda dapat mendefinisikan status, node, dan edge Anda, serta memanggil klien model apa pun yang Anda suka di dalam node. Banyak tim menggabungkan keduanya, karena abstraksi model dan alat LangChain nyaman, dan pembantu create_react_agent bawaan LangGraph (dalam langgraph.prebuilt) memberi Anda agen pemanggil alat yang berfungsi dalam beberapa baris saat Anda tidak memerlukan grafik khusus.

Satu catatan untuk pengguna saat ini: jalur LangGraph v1.0 (stabil sejak akhir 2025) telah menggeser pembantu agen bawaan ke langchain.agents.create_agent, jadi periksa versi yang Anda instal dan referensi resmi untuk jalur impor yang tepat sebelum Anda menyalin cuplikan lama. Membangun agen khusus dari awal juga merupakan keterampilan yang berguna di sini; lihat panduan kami tentang membangun agen AI khusus untuk gambaran yang lebih luas.

Platform dan Studio LangGraph

Pustaka sumber terbuka adalah inti, tetapi dua produk yang berdekatan menjadi penting setelah Anda menyebarkan.

LangGraph Studio adalah IDE agen visual. Ini merender grafik Anda, memungkinkan Anda menjalankannya, dan menunjukkan status di setiap node sehingga Anda dapat melihat eksekusi melangkah melalui node dan edge Anda. Untuk apa pun dengan siklus dan perutean kondisional, melihat jalur yang sebenarnya diambil agen lebih baik daripada membaca baris log.

LangGraph Platform adalah sisi penyebaran terkelola: titik akhir API untuk agen Anda, persistensi bawaan untuk eksekusi jangka panjang, dan opsi hosting yang berkisar dari di-host sendiri hingga sepenuhnya dikelola di cloud. Anda tidak memerlukannya untuk menggunakan pustaka; ini ada ketika Anda menginginkan infrastruktur untuk agen dalam produksi daripada menjalankannya sendiri.

Kapan Menggunakan LangGraph

Gunakan LangGraph ketika agen Anda memiliki alur kontrol yang nyata. Sinyal yang baik:

• Pekerjaannya berupa perulangan, bukan urutan (memanggil alat, memeriksa, mengulang).
• Anda perlu bercabang berdasarkan apa yang diputuskan model.
• Eksekusi bisa lama, dan Anda ingin ia bertahan dari crash dan melanjutkan.
• Manusia harus menyetujui atau mengedit sesuatu di tengah eksekusi.
• Anda mengoordinasikan banyak aktor atau sub-agen yang berbagi status.

Lewati itu ketika panggilan model tunggal atau rantai linier pendek sudah cukup. Sebuah grafik adalah overhead yang tidak Anda perlukan untuk "meringkas teks ini." Simpan struktur itu untuk alur kerja yang benar-benar bercabang dan berulang.

Di mana Pengujian dan Mocking API Berperan

Inilah bagian yang sering menyulitkan tim dalam pengembangan. Agen LangGraph hanya dapat diandalkan sejauh API yang dipanggilnya, dan ia memanggil banyak API: titik akhir LLM, ditambah setiap API alat (pencarian, CRM, backend Anda sendiri). LangGraph mengorkestrasi panggilan-panggilan tersebut; ia tidak mengujinya. Itu adalah pekerjaan terpisah, dan di situlah Apidog berperan.

Dua masalah muncul dengan cepat. Pertama, memanggil API langsung di setiap eksekusi pengujian menghabiskan token dan memicu batas laju. Anda dapat membuat mock API yang diandalkan agen sehingga titik akhir alat mengembalikan respons yang deterministik dan instan saat Anda mengulang logika grafik. Mock titik akhir LLM dengan cara yang sama dan Anda berhenti membayar token hanya untuk menguji perutean.

Kedua, node Anda mengasumsikan bentuk respons. Jika API suatu alat secara diam-diam mengubah nama bidang, edge kondisional Anda membaca hal yang salah dan agen akan berulang atau macet. Menetapkan kontrak tersebut dengan assertion API menangkap perubahan sebelum mencapai grafik Anda. Dan karena agen mengelola kunci di lingkungan staging dan produksi, mengelolanya dalam lingkungan menjaga rahasia agar tidak masuk ke kode node Anda. Jika Anda menginginkan alur kerja lengkap yang berfokus pada agen, alat uji Apidog untuk agen AI membahasnya secara menyeluruh. Perlu diperjelas, tidak ada bagian ini yang mengorkestrasi agen; Apidog menguji dan membuat mock API di bawahnya.

Pertanyaan yang sering diajukan

Apakah LangGraph pengganti LangChain? Tidak. LangGraph adalah runtime orkestrasi; LangChain adalah seperangkat komponen dan integrasi yang lebih luas. Keduanya adalah pustaka terpisah dari tim yang sama, dan Anda dapat menjalankan LangGraph tanpa LangChain atau menggunakannya bersama. LangGraph menangani alur kontrol siklis yang memiliki status yang sulit ditangani oleh rantai biasa.

Apakah saya perlu tahu LangChain untuk memulai dengan LangGraph? Tidak. Anda dapat mendefinisikan StateGraph, menambahkan node dan edge, dan memanggil klien model apa pun di dalam node. Pembungkus model LangChain memang nyaman, tetapi opsional. Mulailah dengan primitif grafik inti dan tambahkan sisanya hanya jika Anda membutuhkannya.

Bagaimana LangGraph mengingat sesuatu antar panggilan? Melalui checkpointer. Kompilasi grafik Anda dengan checkpointer dan teruskan thread_id, dan LangGraph akan menyimpan snapshot status setelah setiap langkah, kemudian memulihkannya pada panggilan berikutnya untuk thread tersebut. Begitulah cara Anda mendapatkan memori percakapan dan pemulihan dari crash tanpa mengubah logika node Anda.

Bagaimana cara menguji API yang dipanggil agen saya? Uji dan mock secara terpisah dari grafik. Mock titik akhir LLM dan alat agar eksekusi cepat dan gratis selama pengembangan, dan pastikan bentuk respons agar bidang yang berubah tidak merusak node. Panduan kami tentang menguji API ChatGPT mencakup autentikasi, streaming, dan panggilan alat, yang merupakan antarmuka tepat yang diandalkan agen.

Penutup

LangGraph memberi Anda struktur yang hilang untuk agen yang melakukan perulangan, bercabang, bertahan, dan berhenti untuk campur tangan manusia. Modelkan alur kerja sebagai grafik dengan status bersama, andalkan checkpointer untuk memori dan pemulihan, dan gunakan Studio serta Platform saat Anda siap untuk melakukan debug dan penyebaran. Kerangka kerja ini menangani orkestrasi. API yang dipanggil agen Anda masih memerlukan jaring pengaman sendiri, jadi buat mock dan uji di Apidog untuk menjaga pengembangan tetap murah dan kontrak alat Anda jujur. Unduh Apidog untuk membuat mock titik akhir dan memastikan responsnya sebelum agen Anda memanggilnya secara nyata.