結論先說
- LangGraph 的核心思想只有一句話:把智能體工作流寫成一張「共享狀態(State)在函數節點(Node)之間順着邊(Edge)循環流轉」的有向圖。
- Python 安裝需要拆成「核心圖引擎 + 模型集成包」兩部分:先裝
langgraph,再按你手裏的密鑰裝langchain-openai、langchain-anthropic或本地langchain-ollama。 - 關於「中文文檔」的避坑提醒:官方唯一實時維護的主文檔在
docs.langchain.com(英文)。看第三方中文搬運教學時,凡是還在教舊版MessageGraph而不用StateGraph+START/END的,說明版本已經落後,照抄容易報棄用警告。 - 寫第一個帶工具的圖只需四個固定積木:
MessagesState(存對話)、模型調用節點、ToolNode(跑工具)和tools_condition(判斷繼續循環還是結束)。

圖:本站根據 LangGraph 官方文檔 Graph API 整理的示意圖
本文根據 LangChain / LangGraph 官方文檔與langchain-ai/langgraph官方 GitHub 倉庫整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 LangChain 官方網站。
適用於誰
- 搜「python 安裝 langgraph」「langgraph 中文 文檔」「langgraph 入門教學」的人;
- 想擺脫黑盒框架封裝,用清晰的圖節點與條件邊自己控制智能體每一步流轉的 Python 開發者;
- 在網上搜到過時教學(還在用廢棄類或跑不通導入語句),需要一份對齊新版
StateGraph標準寫法的最小可運行模板的人。
如果你還不確定項目該選代碼級狀態圖還是選現成引擎,可先對比 /guides/claude-agent-sdk-vs-langchain-how-to-choose 與 /guides/multi-agent-what-is-when-to-use。
一、Python 環境準備與安裝命令
建議使用 Python 3.10 及以上版本,並在獨立的虛擬環境裏安裝,避免和全局舊版 langchain 包產生依賴衝突:
bash
mkdir lg-demo && cd lg-demo
python -m venv .venv
# macOS / Linux 激活:
source .venv/bin/activate
# Windows PowerShell 激活:
# .venv\Scripts\Activate.ps1
pip install -U langgraph langchain-core langchain-openai
如果你使用的是 Claude 官方 API Key,把最後一行的 langchain-openai 換成 langchain-anthropic 即可。接着在終端設定好對應的環境變量(例如 OPENAI_API_KEY 或 ANTHROPIC_API_KEY)。
二、動手前先讀懂四個核心原語
在敲代碼之前,先把 LangGraph 圖裏的四個角色對上號,後面多複雜的編排(見 /guides/multi-agent-orchestration-patterns)都是這四樣東西的排列組合:
- 狀態(
State):整張圖流轉時唯一傳遞的字典數據結構。對於聊天與工具智能體,官方內置了開箱即用的MessagesState,裏面自帶一個配好了add_messages追加規則的messages列表; - 節點(
Node):就是一個普通的 Python 函數——輸入是當前State,輸出是「這一步新增或修改的字典字段」(而不是整份舊狀態); - 普通邊(
add_edge):無條件從節點 A 走到節點 B,例如工具跑完後固定回到大模型節點彙報結果; - 條件邊(
add_conditional_edges):相當於圖裏的紅綠燈。檢查大模型上一句回覆裏有沒有發起工具調用(tool_calls),有就拐去工具節點執行,沒有就直接走向終點END。

圖:本站根據 LangGraph 官方 Quickstart 文檔 整理的示意圖
三、完整代碼:從零跑通第一個工具調用圖
新建 first_graph.py,粘貼下面這段不到 50 行的標準 Graph API 代碼。它定義了一個簡單的單位換算工具,並構建「模型思考 → 調工具 → 再思考 → 輸出最終答案」的完整閉環:
python
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import ToolNode, tools_condition
# 1. 定義一個帶清晰類型註解和文檔註釋的工具函數
@tool
def convert_celsius_to_fahrenheit(celsius: float) -> float:
"""將攝氏溫度換算為華氏溫度。"""
return celsius * 9 / 5 + 32
tools = [convert_celsius_to_fahrenheit]
# 2. 初始化大模型並綁定工具表
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0).bind_tools(tools)
# 3. 定義大模型推理節點:接收當前消息歷史,返回新生成的回覆
def chatbot_node(state: MessagesState):
response = llm.invoke(state["messages"])
return {"messages": [response]}
# 4. 組裝狀態圖
builder = StateGraph(MessagesState)
builder.add_node("chatbot", chatbot_node)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "chatbot")
# 如果模型發起了工具調用就去 tools 節點,否則跳向 END 結束
builder.add_conditional_edges("chatbot", tools_condition)
builder.add_edge("tools", "chatbot")
# 5. 編譯並運行
graph = builder.compile()
if __name__ == "__main__":
result = graph.invoke({
"messages": [("user", "今天室溫 25 攝氏度,換算成華氏度是多少?")]
})
for msg in result["messages"]:
msg.pretty_print()
運行 python first_graph.py,你會依次看到四條消息軌跡:人類提問 → 模型發出 convert_celsius_to_fahrenheit(celsius=25.0) 工具請求 → ToolNode 算出 77.0 返回 → 模型彙總輸出最終中文答覆。
四、加三行代碼開啟多輪對話記憶
上面的 graph.invoke 預設是無狀態的——第二次調用 invoke 時它不記得上一句聊了什麼。想在本地開啟多輪會話記憶,只需引入內置的內存檢查點儲存器 InMemorySaver 並傳入 thread_id:
python
from langgraph.checkpoint.memory import InMemorySaver
memory = InMemorySaver()
graph_with_memory = builder.compile(checkpointer=memory)
config = {"configurable": {"thread_id": "demo-user-1"}}
graph_with_memory.invoke({"messages": [("user", "我叫小周,住在北京")]}, config)
res = graph_with_memory.invoke({"messages": [("user", "剛才說我叫什麼?")]}, config)
print(res["messages"][-1].content)
如果團隊希望不寫 Python 代碼、直接通過拖拽畫布先驗證節點流程,也可以對比無代碼工作流工具 /guides/dify-how-to-use-cloud-getting-started;日常藉助網頁端 ChatGPT 或 Claude 輔助閱讀官方英文源碼文檔時,個人帳號訂閱說明可參考 /chongzhi/chatgpt-plus。
常見問題
Q:安裝時報錯找不到 langgraph.prebuilt 或版本衝突怎麼辦?
多半是因為舊項目環境裏殘留了很老版本的 langchain-core。新建乾淨的 .venv 虛擬環境,執行 pip install -U langgraph langchain-core 統一升到最新穩定版即可解決。
Q:什麼時候用高層快捷函數、什麼時候手寫 StateGraph?
如果只是做標準「單模型 + 一組工具」循環,用官方預置封裝幾行就能跑起來;但一旦你需要在圖裏插入自定義業務字段(比如記錄重試次數、審批狀態)或編排多個不同職責的節點,上面這種顯式手寫 StateGraph 的方式最直觀、最好改。
Q:InMemorySaver 能直接用在正式生產環境嗎?
不能。內存儲存器只活在當前 Python 進程裏,服務一重啟所有歷史對話就清空了。生產上線時應切換到官方提供的持久化檢查點包(例如基於 PostgreSQL 或 SQLite 的儲存器),節點代碼完全不用改,只替換 compile(checkpointer=...) 傳入的對象即可。
相關教學
- /guides/claude-agent-sdk-vs-langchain-how-to-choose:Claude Agent SDK 與 LangChain / LangGraph 怎麼選
- /guides/multi-agent-orchestration-patterns:多 Agent 四大編排拓撲詳解
- /guides/multi-agent-what-is-when-to-use:多智能體適用場景判斷標準
- /guides/dify-how-to-use-cloud-getting-started:Dify 可視化工作流快速入門
參考資料
- LangChain / LangGraph 官方文檔 — https://docs.langchain.com/
langchain-ai/langgraph官方 GitHub 倉庫 — https://github.com/langchain-ai/langgraph
0 條評論
還沒有評論,來搶沙發~