从零搭一个AI Agent：手把手用LangGraph做一个能用的智能体

从零搭AI Agent这事儿我憋了一阵才动笔，因为网上的LangGraph教程大多停在"Hello World"。讲完一个最简单的图就收工。真到要干活儿，全是空白。这篇我直接拿一个实际项目——论文研究Agent——把全流程拆给你看。根据Anthropic 2026年开发者调查，超过38%的AI应用团队已经在用图框架编排Agent，比半年前翻了一倍，LangGraph是其中最主流的一个。

会写Python就行。不用懂分布式，不用懂数据库。会调API、会写函数，足够了。

LangGraph是什么：把Agent画成一张图

原子答案：LangGraph是LangChain团队出的Agent编排框架，把Agent的执行流程抽象成"节点+边"的有向图，每个节点干一件事，边决定下一步去哪。

老式的ReAct Agent是"模型自己决定下一步干啥"，听起来很美，跑起来经常失控。模型会无限循环、忘记调用工具、或者一直重复同一句话。我自己就被绕进去过，调试到凌晨两点发现是模型在"思考"和"调用工具"之间反复横跳。

LangGraph的思路不一样。你提前画好图：这个节点搜索、那个节点总结、再一个节点判断要不要继续。流程是确定的，模型只在节点内部做决策。控制权回到了你手里。

对新手的好处很明显。调试简单——哪一步出问题就去看哪个节点。可观测性强——每一步的输入输出都能打日志。想接 MCP协议 把工具统一管理也方便。详细概念可以去翻 LangGraph官方文档。

开工前：环境和基础装好

原子答案：Python 3.10以上、装langgraph和langchain-openai、准备一个OpenAI或兼容API的key，三样齐了就能开干。

我用的版本：langgraph 0.2.x、langchain-openai 0.2.x、Python 3.11。装包就一行：

pip install langgraph langchain-openai langchain-core

说个坑。第一次我装了langgraph但没装langchain-openai，import直接报错。这俩是分开的包，文档没特别强调。还有，如果你用国内中转的OpenAI兼容API，记得设base_url，不然默认走官方域名可能连不上。要省钱可以挂本地模型，参考我们另一篇 本地LLM RAG搭建指南。

API key放环境变量，别硬编码进代码。我吃过亏——key推到GitHub被刷了18美元才反应过来。

第一步：定义Agent的状态（State）

原子答案：State就是Agent在图里传递的"数据包"，用TypedDict定义，所有节点读写同一个状态对象。

论文研究Agent我设计了这样的状态：

class ResearchState(TypedDict):
    query: str
    papers: list
    summaries: list
    final_report: str
    loop_count: int

query是用户的问题，papers存搜到的论文，summaries存摘要，final_report是最终输出，loop_count防死循环。最后这个特别重要。我第一版没加，Agent跑着跑着一直搜一直搜，停不下来。加了loop_count上限3次，立刻老实了。

第二步：写节点函数（Node）

原子答案：每个节点是一个普通Python函数，入参是state、返回值是更新后的state字段。

我写了三个节点：search_papers（搜论文）、summarize（生成摘要）、write_report（写最终报告）。search_papers内部调arxiv API和搜索引擎工具，把结果塞进state["papers"]。

坑点：节点返回的字典只要包含想更新的字段，不需要返回整个state。我一开始老老实实返回全量，结果代码又臭又长还容易出错。LangGraph会自动合并。

summarize节点里我让它并行处理多篇论文。LangGraph原生支持map-reduce模式，一篇论文一个subgraph，跑完汇合。这个功能太香了，10篇论文并行摘要只要40秒，串行得4分钟。

第三步：连线建图（Edge）

原子答案：用StateGraph把节点串起来，add_edge连固定流程，add_conditional_edges做分支判断。

我的图长这样：START → search → summarize → judge（要不要再搜一轮）→ write_report → END。judge是条件边，根据loop_count和摘要质量决定继续搜还是收尾。

条件边长这样：graph.add_conditional_edges("summarize", should_continue, {"continue": "search", "end": "write_report"})。should_continue函数返回字符串"continue"或"end"，LangGraph按这个字符串路由。

第一次跑通了兴奋得不行。然后立刻翻车——judge节点判断"摘要不够全"于是又搜一轮，但新一轮搜出来的论文和上一轮重复了，summarize节点对同样的内容摘要了三遍。修了半小时，加了个去重逻辑，按论文标题去重。

第四步：编译、跑起来、调试

原子答案：graph.compile()生成可执行图，调用时传初始state，用stream模式逐步看每个节点的输出。

调试必看stream。我每写一个节点就跑一遍stream，眼睛盯着每个节点的输入输出。比print高到不知道哪去了。LangSmith还能可视化整张图的执行轨迹，免费额度够个人用。

真实跑一次"transformer架构演进"这个query：search拿到12篇论文，summarize并行处理约45秒，judge判定第一轮摘要不够覆盖注意力机制变体，再搜一轮，最终write_report生成3200字报告。全程2分18秒，花了大概0.04美元的API费用。比我手动查arxiv再总结快了十倍不止。

说实话第一次完整跑通那一刻，比写出第一个Hello World还激动。Agent自己决定"还得再搜一次"那个瞬间，有种它真的在"思考"的错觉。

踩过的坑和调试SOP

原子答案：90%的Agent问题出在三处——死循环、工具调用失败、状态字段对不上，按这个顺序排查最快。

死循环：必加loop_count或max_iterations。我现在的习惯是任何带条件边的图都加，不管看上去多安全。

工具调用失败：先单独测工具函数，别在图里测。OpenAI的工具调用偶尔会返回格式错的JSON，包一层try-except返回空结果，比让Agent崩掉强。 OpenAI function calling文档 有详细说明。

状态字段对不上：TypedDict不强制类型检查，运行时才会爆。我在每个节点入口加assert确认关键字段存在，提前失败比后面莫名其妙好查。

还有个隐蔽坑：parallel节点写state时如果同时改同一个字段，后写的会覆盖前面的。LangGraph有reducer机制处理这个，用Annotated[list, add]声明累加。不加reducer、又并行写list，你一定会丢数据。

Agent能干啥：任务边界和拓展

原子答案：LangGraph适合多步骤、有分支判断、需要状态管理的任务，比如研究、客服工单处理、代码review、报告生成。

纯一问一答别用LangGraph，杀鸡用牛刀。但只要你这个任务"需要分多步、中间要根据结果决定下一步"，LangGraph就值得上。我后来还搭过代码review Agent和客服工单分类Agent，套路一样：定义状态、写节点、连图、加防死循环。

想给Agent接更多工具，写个MCP server 是正路，工具多了管理起来不乱。想搞可视化的可以对比 n8n/Dify/Coze这类Agent搭建工具，零代码党用那几个更快。

话说回来，零代码平台搭简单Agent爽，但一旦逻辑复杂到要写条件分支和状态机，还是LangGraph这种代码框架灵活。这就是它的定位。

常见问题

从零搭AI Agent需要什么基础？

会写Python、会调API、理解函数和字典就行。不需要懂机器学习原理，不需要会训练模型。LangGraph本身是编排框架，模型是黑盒调用的，你管的是流程不是模型内部。

LangGraph和LangChain是什么关系？

LangChain是老牌大模型应用框架，功能杂。LangGraph是LangChain团队后来单独做的Agent编排子项目，专攻"图结构编排Agent"。可以单独用LangGraph不依赖LangChain主包，但现在两个生态共用很多组件。 LangChain官网 有完整说明。

搭一个能用的Agent大概要几步？

四步：定义State、写节点函数、连图加条件边、compile后跑stream调试。最小可用Agent代码不到150行。但调到稳定好用，按我的经验还要花两三天磨边角。

LangGraph入门难不难？

概念不难，半天能看懂。难在调试真实业务时的状态管理和分支逻辑。建议先抄官方示例跑通，再改成自己的场景，别一上来就从零设计图结构。

Agent跑起来一直循环停不下来怎么办？

加loop_count字段，在条件边的判断函数里检查超过N次就强制走END。这是最简单有效的防死循环手段。另外检查你的条件边返回值和路由字典的key是否完全匹配，拼写错也会导致路由失败原地打转。