langgraph

1. 專案概覽

LangGraph 是一個低階編排框架，用於建構、執行與管理長時間執行且具備狀態的 AI 代理——它解決了將代理從脆弱的原型推進至具備容錯能力、可迴圈、可分支、可暫停且能從故障中恢復的生產級系統的難題。

2. 背景與定位

LangGraph 由 LangChain 團隊開發，旨在填補簡單提示鏈結函式庫無法滿足的缺口：真實世界中的代理需要重試、自我修正、等待人工核准，並在長時間執行或中斷的執行過程中保存狀態。其核心使命是讓開發者對代理邏輯與狀態擁有精確的低階控制權——而非將一切隱藏在高階的黑盒子背後——同時仍提供生產系統所需的耐久性保證。

在架構上，LangGraph 將代理的工作流程建模為具備狀態的循環有向圖，其靈感來自 Google 的 Pregel 與 Apache Beam，API 風格則受 NetworkX 影響。這使其有別於純線性的管線框架：典型的鏈結執行固定的步驟序列並捨棄中間上下文，而 LangGraph 則維護一個共享且具型別的狀態物件，圖中的每個節點都能讀取與更新該物件，且圖可以自我迴圈以進行反思、重試或反覆運算規劃。截至 2026 年，LangGraph 亦作為 LangChain 自家代理的底層執行執行環境，使其成為 LangChain 生態系中複雜代理工作流程的共同基礎。

3. 功能分類

• 🧩 圖形編排 — 用於定義節點、邊與條件路由的核心 API。代表性範例：StateGraph、條件邊、循環圖、子圖、受 Pregel 啟發的執行模型。目的：將任意複雜的代理控制流程（包含迴圈與分支）以圖形而非固定腳本的形式表達。
• 💾 耐久執行與持久化 — 用於在崩潰中存活並恢復工作的機制。代表性範例：檢查點儲存器、基於執行緒的狀態持久化、任務重試、可恢復的執行。目的：讓代理在故障或重啟後，能精確地從中斷處繼續，而非從頭開始。
• 🧠 記憶系統 — 供代理使用的短期與長期記憶體基元。代表性範例：共享狀態物件、跨對話的長期記憶體存放區、具備記憶感知的檢索。目的：讓代理同時具備當前任務的工作記憶與跨對話的耐久記憶。
• 🧑‍⚖️ 人工介入控制 — 內建的中斷與核准機制。代表性範例：中斷節點、狀態檢查、手動狀態編輯、敏感動作前的核准閘道。目的：讓人類能在代理採取重大行動前，進行審查、暫停或重新導向。
• 🔍 除錯與可觀測性 — 用於視覺化與追蹤代理執行的工具。代表性範例：LangGraph Studio、LangSmith 追蹤整合、從任意檢查點重播執行、分支與重播除錯。目的：讓原本不透明的多步驟代理行為變得可檢查且可重現。
• 🚀 部署基礎設施 — 用於在生產環境中執行代理的工具與服務。代表性範例：LangGraph Platform、可擴展的任務佇列、串流 API、伺服器範本。目的：將代理從本地腳本推進至可擴展且受監控的生產服務。

4. 核心亮點

• 循環圖模型 — 有別於線性管線，LangGraph 的圖可以迴圈回先前的節點，這對於重試邏輯、自我修正以及如 ReAct 或「規劃與執行」等反覆運算推理模式至關重要。
• 耐久執行 — 代理能夠在程序崩潰或中斷中存活，並從中斷處精確恢復，而非從頭重新啟動冗長的任務。
• 首要的人工監督 — 人工介入核准是內建的圖形基元（中斷節點），而非事後附加於框架上的想法。
• 複合記憶模型 — 同時支援短期工作狀態與長期持久化記憶，讓代理能在任務內與跨對話間維持上下文。
• 深度可觀測性 — 與 LangSmith 和 LangGraph Studio 原生整合，提供視覺化圖形檢查、執行追蹤與基於重播的除錯。
• 框架無關的控制 — 作為低階函式庫，LangGraph 不強制採用特定的代理架構；團隊可以在相同的基元上實作 ReAct 風格的代理、多代理系統或完全自訂的控制流程。

5. 依角色的使用情境

• 一般開發者 — 建構需要分支邏輯、重試或多步驟工具使用的自訂對話或任務執行代理，超越簡單提示鏈所能提供的功能。
• DevOps/SRE — 使用 LangGraph Platform 部署與營運長時間執行的代理工作流程，並透過耐久執行與檢查點機制在基礎設施中斷中存活。
• 資料/研究科學家 — 使用 LangGraph Studio 進行視覺化檢查與快速除錯，針對複雜的代理架構（多代理協作、反思迴圈、工具增強推理）進行原型開發與反覆運算。
• 專案經理 — 引入人工介入核准閘道，讓處理敏感或高風險動作的代理在繼續執行前需要簽核，以降低營運風險。

6. 開始使用

找到所需內容 — 瀏覽官方文件與 API 參考，取得關於圖形、狀態、持久化與部署的指南：

https://langchain-ai.github.io/langgraph/

安裝與整合 — 透過 pip 將 LangGraph 新增至 Python 專案（亦提供 JavaScript/TypeScript 版本 LangGraph.js）：

pip install -U langgraph

貢獻 — Fork 此儲存庫，閱讀貢獻指南，並建立 pull request：

git clone https://github.com/langchain-ai/langgraph.git

7. 專案結構（選用）

langgraph/
├── .github/     # CI 工作流程與儲存庫設定
├── docs/        # 官方文件網站的文件原始碼
├── examples/    # 範例代理實作與使用模式
└── libs/        # 核心函式庫套件（圖形引擎、檢查點儲存器、預建元件）

• libs/ 包含核心編排引擎以及支撐耐久執行的檢查點儲存器/持久化實作。
• examples/ 是在自行撰寫前查看可用代理圖的最快方式。
• docs/ 反映已發布的文件網站，是尋找最新 API 變更的好去處。

8. 相關生態系

• LangChain — 提供 LangGraph 代理通常會編排的元件函式庫（模型、工具、檢索器）；截至 2026 年，LangChain 自家的代理亦執行於 LangGraph 執行環境之上。
• LangSmith — 用於追蹤、除錯與監控 LangGraph 代理執行的可觀測性與評估平台。
• LangGraph Platform — 用於在生產環境中部署與擴展 LangGraph 代理的託管基礎設施。
• LangGraph Studio — 用於檢查圖形結構、逐步執行與從檢查點重播執行的視覺化除錯工具。
• Deep Agents — 建構於 LangGraph 之上的高階代理建構層，適合需要更多開箱即用支架的團隊。
• LangGraph.js — 供在 Python 生態系外建構代理的團隊使用的 JavaScript/TypeScript 對應版本。

9. 授權條款

• ✅ 採用 MIT 授權條款，可免費使用、修改與散布，包含用於商業與專有產品。
• ✅ 明確授予再授權與銷售軟體副本的許可。
• ❌ 不提供任何保證；作者對因使用軟體而產生的損害不負責任。
• ℹ️ 任何實質上的程式碼副本或重新散布均須包含 MIT 授權條款文本與版權聲明。

10. 常見問題

問：使用 LangGraph 需要搭配 LangChain 嗎？
答：不需要。LangGraph 是獨立的低階編排函式庫，儘管它與 LangChain 元件自然整合，且截至 2026 年，它也是 LangChain 自家代理執行環境的基礎。

問：LangGraph 與簡單的提示鏈有何不同？
答：提示鏈執行固定的線性步驟序列。LangGraph 將工作流程建模為具備共享狀態的循環圖，因此代理可以迴圈、分支、重試並暫停以等待人工輸入。

問：LangGraph 代理能在崩潰或重啟中存活嗎？
答：可以。透過其檢查點儲存器與持久化機制，LangGraph 支援耐久執行，允許代理從上次儲存的狀態恢復，而非從頭開始。

問：有視覺化的方式來除錯代理圖嗎？
答：有，LangGraph Studio 提供視覺化介面，可檢查圖形結構、檢視每個節點的狀態，並從任意檢查點重播執行。

問：LangGraph 在 Python 之外有提供其他版本嗎？
答：有，LangGraph.js 為 JavaScript 與 TypeScript 專案提供同等功能。

11. 快速連結

• 儲存庫：https://github.com/langchain-ai/langgraph
• 官方文件：https://langchain-ai.github.io/langgraph/
• 貢獻指南：https://github.com/langchain-ai/langgraph/blob/main/CONTRIBUTING.md
• 社群/討論區：https://github.com/langchain-ai/langgraph/discussions

12. 總結

LangGraph 為全球開發團隊提供了一個耐久且可檢查的基礎，用於建構超越簡單線性提示鏈的代理——開箱即用地支援迴圈、分支、人工監督與崩潰恢復。它最適合需要生產級可靠性與對代理行為進行細粒度控制的開發者與團隊，從原型開發新代理架構的個人工程師，到在面對客戶的產品中大規模營運代理的組織皆適用。