基于 LangGraph 的 Agent 循环图编排条件边与记忆持久化在构建能够处理复杂长任务的大模型 Agent 系统时传统的链式调用模式如早期的 LangChain Sequential Chain很快就会撞上能力的“天花板”真实世界的任务流绝不是线性的而是充斥着循环重试Cyclic Loops、动态分支路由Conditional Branching以及跨轮次状态记忆更新State Persistence。比如Agent 生成了一段 Python 代码后必须调用解释器执行如果执行报错Agent 必须带着错误堆栈循环回退到代码生成节点重新修复直到单测 100% 通过才能流转至下一步。LangChain 团队推出的LangGraph将 Agent 工作流抽象为一个强类型的有向循环图Directed Cyclic Graph, DCG。通过将图节点Nodes绑定为纯函数式 Agent 推理单元、将条件边Conditional Edges绑定为确定性路由守卫、并结合持久化检查点Checkpointer我们能够构建出具备企业级循环控制与时间旅行调试能力的复杂 Agent 编排系统。LangGraph 循环状态图架构拓扑[用户输入 Task Prompt] │ ▼ ┌──────────────────┐ │ node: plan │ ◄────────────────────────┐ └────────┬─────────┘ │ │ │ ▼ │ ┌──────────────────┐ │ │ node: generate │ ◄──────────┐ │ └────────┬─────────┘ │ │ │ │ (重试修复) │ (重试规划) ▼ │ │ ┌──────────────────┐ │ │ │ node: execute │ ───────────┴─────────────┤ └────────┬─────────┘ │ │ (条件边路由判定) │ ┌────────────────────┼────────────────────┐ │ ▼ (执行报错 3次) ▼ (严重架构错误) ▼ (单测全部通过) │ [路由回 generate] [路由回 plan] └───────┬───────────┘ ▼ ┌──────────────────┐ │ node: summarize │ ── [最终交付] └──────────────────┘核心实现基于 TypeScript 的 LangGraph 状态图与条件边import { StateGraph, END, START, MemorySaver } from langchain/langgraph; import { BaseMessage, HumanMessage, AIMessage } from langchain/core/messages; // 1. 定义全图强类型共享状态接口 (State Annotation) export interface AgentGraphState { messages: BaseMessage[]; codeDraft: string; testError: string | null; retryCount: number; isCompleted: boolean; } // 2. 初始化 LangGraph 状态图定义 const workflow new StateGraphAgentGraphState({ channels: { messages: { value: (prev: BaseMessage[], next: BaseMessage[]) prev.concat(next), default: () [], }, codeDraft: { value: (prev: string, next: string) next ?? prev, default: () , }, testError: { value: (prev: string | null, next: string | null) next, default: () null, }, retryCount: { value: (prev: number, next: number) next, default: () 0, }, isCompleted: { value: (prev: boolean, next: boolean) next, default: () false, }, }, }); // 3. 定义图节点处理函数 (Nodes) async function generateCodeNode(state: AgentGraphState) { console.log( [Node: generateCode] 正在生成/修复代码...); const prompt state.testError ? 上次运行报错: ${state.testError}请修复代码。 : 请编写代码实现目标。; // 模拟大模型调用生成代码 const generatedCode function calculateTotal() { /* fixed logic */ return 100; }; return { codeDraft: generatedCode, messages: [new AIMessage(generatedCode)], }; } async function executeTestNode(state: AgentGraphState) { console.log(⚡ [Node: executeTest] 正在沙箱中运行单元测试...); // 模拟第一次执行失败、第二次执行成功的场景 if (state.retryCount 0) { return { testError: AssertionError: Expected 100 but received 0, retryCount: state.retryCount 1, isCompleted: false, }; } return { testError: null, retryCount: state.retryCount 1, isCompleted: true, }; } // 4. 定义条件边动态路由函数 (Conditional Edge Router) function routeAfterTest(state: AgentGraphState): generate | typeof END { if (state.isCompleted) { console.log(✔ 测试全部通过流转至结束节点); return END; } if (state.retryCount 3) { console.warn( 达到最大重试次数上限强制中断); return END; } console.log( 检测到单测失败条件边触发循环回退至 [generate] 节点); return generate; } // 5. 组装图节点与边拓扑 workflow.addNode(generate, generateCodeNode); workflow.addNode(execute, executeTestNode); // 连线拓扑 workflow.addEdge(START, generate); workflow.addEdge(generate, execute); // 核心添加条件分支循环边 workflow.addConditionalEdges(execute, routeAfterTest, { generate: generate, [END]: END, }); // 6. 挂载持久化检查点存储器 (支持状态序列化与多轮断点恢复) const checkpointer new MemorySaver(); export const appGraph workflow.compile({ checkpointer });前端调用与状态流式监听在前端 Web 客户端中调用编译后的 LangGraph 工作流并实时监听状态图节点的跃迁事件export async function runAgentWorkflow(sessionId: string, userPrompt: string) { const config { configurable: { thread_id: sessionId } }; // 触发有向图流式执行 const stream await appGraph.stream( { messages: [new HumanMessage(userPrompt)], retryCount: 0, isCompleted: false, }, config ); for await (const stepOutput of stream) { const [nodeName, output] Object.entries(stepOutput)[0]; console.log( 状态跃迁至节点: [${nodeName}], output); } }工程落地收益确定性的循环与分支控制彻底摆脱了传统自然语言 Prompt 容易陷入死循环的失控问题重试上限与路由分支在图结构上被代码强行锁死。原生支持断点持久化与时间旅行Time Travel通过checkpointer系统自动保存每一个 Node 执行前后的完整状态快照支持开发者在前端控制台秒级回滚到任意历史步骤重新调试。天然契合可视化编排LangGraph 的图结构可以直接导出为标准 Mermaid 或 JSON 拓扑直接在前端画布上渲染出动态发光的执行节点极大提升了 Agent 系统的可解释性。