Skip to content

LLM › Agent › LangGraph

LangGraph Agent 工作流程 (LangGraph Agent Workflows) ​

LangGraph 把 agent 寫成一張狀態圖:節點 (node) 是步驟,邊 (edge) 是轉移,狀態 (state) 在節點間傳遞。價值不在「更自主」,而在流程明確:看得到走了哪條路、在哪裡停、哪一步需要人工核准。

核心概念 ​

元件意義例子
State在節點間傳遞的資料(常是 message 列表 + 自訂欄位)MessagesState:對話與工具結果
Node一個步驟(函式),讀 state、回傳要更新的欄位呼叫模型、執行工具、驗證輸出
Edge固定轉移tools → model
Conditional edge依 state 決定下一個節點模型要求工具 → tools;否則 → END
START / END流程的起點與終點—
Checkpointer每步保存 state對話記憶、中斷後恢復、人工核准

許多 agent 失敗其實是狀態設計失敗:該傳下去的資訊沒傳,後面的步驟就無法正確判斷。

最小的 tool-using agent ​

text
START → model ──(有 tool_calls)──→ tools ──→ model ……
              └─(沒有 tool_calls)──→ END
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
from langgraph.checkpoint.memory import MemorySaver

@tool
def lookup_gene(symbol: str) -> str:
    """以 HGNC 符號查詢人類基因的官方名稱與 NCBI Gene ID。"""
    ...

tools = [lookup_gene]
llm = ChatOpenAI(model=MODEL, temperature=0).bind_tools(tools)

def call_model(state: MessagesState):
    return {"messages": [llm.invoke(state["messages"])]}   # 回傳的 messages 會被附加到 state

g = StateGraph(MessagesState)
g.add_node("model", call_model)
g.add_node("tools", ToolNode(tools))                       # 執行模型要求的工具,結果寫回 messages
g.add_edge(START, "model")
g.add_conditional_edges("model", tools_condition)          # 有 tool_calls → "tools",否則 → END
g.add_edge("tools", "model")
app = g.compile(checkpointer=MemorySaver())

config = {"configurable": {"thread_id": "user-42"}, "recursion_limit": 10}   # thread_id 區分對話;限制步數
for state in app.stream({"messages": [("user", "TP53 的官方名稱?")]}, config, stream_mode="values"):
    state["messages"][-1].pretty_print()                    # 逐步看到模型輸出與工具呼叫
設計理由
模型節點與工具節點分開推理錯誤與工具錯誤不會混在一起
工具使用是路由決策可以解釋 agent 為什麼行動,而不只是看到答案
recursion_limit明確的停止條件,避免無限迴圈
thread_id + checkpointer同一對話延續狀態;不同使用者互不干擾

人工核准 (Human-in-the-Loop) ​

python
app = g.compile(checkpointer=MemorySaver(), interrupt_before=["tools"])   # 執行工具前暫停

app.invoke({"messages": [("user", "把這 20 筆樣本標記為 QC failed")]}, config)
pending = app.get_state(config).values["messages"][-1].tool_calls      # 檢視模型想執行什麼
# 人確認後繼續;不同意則用 app.update_state(...) 修改或取消
app.invoke(None, config)

只對有副作用的工具暫停即可(把唯讀工具和寫入工具分在不同節點);較新版本也可在節點內用 interrupt() 做更細的控制。

串流與可觀測性 ​

可觀察用途
節點轉移看流程走了哪條路
模型中間輸出檢查推理是否合理
工具呼叫與參數確認選對工具、參數正確
每步延遲找出慢的步驟

stream_mode="values" 每步輸出完整 state;"updates" 只輸出變更部分;"messages" 逐 token 串流。搭配 LangSmith 等 tracing 工具可視覺化整條路徑。

對話歷史管理 ​

策略取捨
保留全部連貫,但 token 成本與雜訊增加
截斷(保留最近 N 則)便宜,可能遺失早期約定;注意不要把 tool call 與對應結果拆開
摘要舊訊息折衷,但多一個轉換步驟且可能失真

單一 agent 還是多 agent ​

圖的結構解讀
一個模型節點 + 工具有狀態的單一 agent
多個專職節點、固定順序多步驟工作流程(不一定是 agent)
多個 agent 節點 + 路由多 agent 系統

先用圖把流程控制理清楚;只有在專業分工確實帶來價值時才增加 agent。

檢查清單 ​

問題對應
State 裡傳遞了哪些資訊?是否足夠?核心概念
哪些節點推理、哪些節點執行工具?最小的 agent
什麼條件走工具路徑?什麼條件結束?conditional edge、recursion_limit
哪些動作需要人工核准?人工核准
能否看到每一步的輸入、輸出與延遲?串流與可觀測性