LangGraph 入門教學:Python 安裝、核心概念與跑通第一個狀態圖智能體

面向搜「python 安裝 langgraph」和「langgraph 中文 文檔」的初學者:本文按 LangChain 官方最新 Graph API 規範,講清安裝步驟、State/Node/Edge 四大概念,並從零寫出第一個帶工具調用循環的 StateGraph。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

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

LangGraph 四個核心概念對照表

圖:本站根據 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。

Python 安裝並跑通第一個圖四步

圖:本站根據 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=...) 傳入的對象即可。

相關教學

參考資料

  • LangChain / LangGraph 官方文檔 — https://docs.langchain.com/
  • langchain-ai/langgraph 官方 GitHub 倉庫 — https://github.com/langchain-ai/langgraph

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  5. 05

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  6. 06

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  4. 04

    A2A 協議是什麼、怎麼用:Agent2Agent 智能體互聯規範、名片發現與 Python 接入流程

    A2A(Agent2Agent)是由 Google 發起並移交 Linux 基金會託管的開放智能體通信協議,用來讓不同團隊、不同框架開發的獨立智能體跨網絡互相派單協作。本文按官方規範講清 Agent Card、Task 狀態機與 Python SDK 接入步驟。

    Gemini其他 AI 工具0
  5. 05

    AutoGen 現在怎麼樣了?微軟官方演進路線與 Microsoft Agent Framework 入門

    搜 AutoGen 新教學常被 0.2、0.4、社區分支和 Semantic Kernel 繞暈。按微軟官方文檔,微軟已將 AutoGen 與 Semantic Kernel 兩支團隊合併推出統一的開源框架 Microsoft Agent Framework。本文講清現狀與 Python 快速上手。

    ChatGPT其他 AI 工具0
  6. 06

    CrewAI 多輪對話與記憶怎麼配:memory=True 三層記憶、人工介入與 Flows 狀態持久化

    剛用上 CrewAI 的人常疑惑 kickoff 跑完就結束,怎麼做多輪連續對話與跨次記憶。本文按官方文檔拆解 memory=True 的短期/長期/實體三層記憶、嵌入模型配置,以及用 Flows 狀態流和 @persist 搭建多輪會話的實戰寫法。

    其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~