LangChain 与 LangGraph：从一个会说话的模型，到一个敢交给别人用的 Agent

你大概已经能让模型说话了：拿到 API key，装个 SDK，几行代码就有了回复。你可能还给它接过工具——定义一个 JSON schema，模型返回一个函数名和参数，你解析出来、执行、把结果拼回去，再调一次模型。

第一次跑通的时候会觉得，这有什么难的。

难的是第二天。产品说：这个退款要人工确认才能执行。你发现你的 while 循环里没地方停。运维说：进程重启了，昨天那个卡在人工确认的会话怎么办。你发现你的对话历史只存在内存里。前端说：用户要看到它正在做什么。你发现你的循环是个黑盒，中间什么都推不出来。测试说：昨天它把一个不该退的单子退了，是哪一步判错的。你发现你除了最后那句回复，什么都没留下。

这四个问题——人工介入、断点续跑、过程可见、事后可查——才是把一个 demo 变成一个能交给别人用的 agent 的真正工作量。它们和「怎么调模型」几乎没关系，和「怎么组织一段有状态的、可能跑很久的、随时可能被打断的流程」全部有关。

LangChain 和 LangGraph 分别站在这条分界线的两侧。LangChain 管的是一次调用：把不同厂商的模型、消息、工具、结构化输出抹平成同一套接口，再给你一个开箱即用的 agent 循环。LangGraph 管的是一段流程：状态放在哪、谁决定下一步去哪、中断了怎么接着跑、跑到一半崩了怎么办。官方自己的说法很直白——LangChain 的 agent 就是建在 LangGraph 上的，你可以从高层开始，需要的时候再往下掉一层。

这份教程要带你走完的不是「十行代码跑通一个 agent」。跑通很容易，官方最小示例确实只有十行。真正难的是后面那一大段：为什么两个节点同时写一个字段会直接报错；模型不肯停下来的时候你怎么让它停；人隔了一天才来点批准，那个会话凭什么还在；前端到底该订阅哪一种流；它变慢变贵的时候钱花在哪里；以及最后那个问题——这套东西上线之后，出了问题你能不能查出来。

读完你会有一个真正做完的产物：一个退款工单助手。它读一条客服工单，查订单、按政策判断、金额超过阈值必须人工批准、批准可能隔一天才来、整个过程能流式展示给前端、上线后能追溯每一次判断。十四章就是把它一步步做出来的过程。

动手之前，先说清楚三件事。

第一，这两个库刚经历过一次大改版，网上大部分中文文章讲的是改版之前的东西。LLMChain、AgentExecutor、initialize_agent、ConversationBufferMemory 这些你搜索时最常见的名字，在当前版本里 import 就会失败。create_react_agent 改名成了 create_agent，prompt= 改成了 system_prompt=。这不是细节，是你复制任何一段旧代码都会撞上的第一堵墙，所以第 2 章会专门用一节把对照表列清楚。

第二，本教程的所有结构性代码都在本机真跑过。文中出现的每一段报错原文、每一份 JSON、每一条消息序列、每一次 REST 响应，都是真实运行结果，版本是 langchain 1.4.0 / langchain-core 1.6.2 / langgraph 1.2.11 / langgraph-cli 0.4.31（2026 年 9 月 6 日安装）。唯一的例外是真实模型调用——写作环境没有模型 API key，所以凡是涉及模型真实返回、token 用量、流式节奏的地方，教程只给代码和官方说明，不会伪装成实测结果。这一点在相关章节都会明确标出。

第三，版本还会继续变，而且变得很快。官方发布政策自己写着 patch 版本「一周数次」；实测这两个包在写作前一周内就发了六个版本。所以本教程里的版本号、参数名、命令语法，动手前请用官方文档核对一遍。教程教的是判断方法和排错路径，不是可以永远照抄的常量。

技术栈：Python 3.12，依赖与命令统一用 uv。