LangGraph入门指南：构建天气查询Agent的完整教程

> ### 摘要 > 本文面向LangGraph新手，提供一个结构清晰的入门指南，逐步构建具备工具调用能力的天气查询Agent。LangGraph作为专为有状态、可循环、可恢复执行而设计的Agent编排运行时环境，显著超越传统线性流程框架。文章从零出发，搭建最小可运行实例，深入阐释State模型（定义Agent状态结构）、Node（封装具体执行逻辑）与Router（实现条件化路径分发）三大核心概念，助力读者扎实掌握Agent开发范式。 > ### 关键词 > LangGraph, Agent入门, 天气查询, State模型, Node路由 ## 一、LangGraph基础概念 ### 1.1 LangGraph的定义与特点：解析有状态、可循环、可恢复执行的Agent编排环境 LangGraph是一个专为有状态、可循环、可恢复执行的Agent编排设计的运行时环境。这一定义并非技术术语的堆砌，而是对Agent真实行为逻辑的精准回应——当一个智能体需要记忆用户上一轮的提问、中断后重新加载上下文、或在多次尝试失败后回退重试时，“有状态”意味着它不再是一次性函数调用，而是一个拥有内在时间感与记忆结构的生命体；“可循环”赋予它自我修正与迭代推理的能力，比如在天气查询中，若初次调用API失败，它可自主触发重试逻辑或切换备用服务；“可恢复执行”则保障了系统韧性，即使进程意外中断，也能从断点处继续推进，而非从头开始。这种设计哲学，使LangGraph天然适配Agent的本质：不是流水线上的零件，而是具备目标意识、反馈能力与路径弹性的协作者。它不满足于“完成任务”，而致力于“理解任务如何被完成”。 ### 1.2 LangGraph与传统工作流的区别：为何它更适合Agent应用场景 传统工作流框架往往遵循严格的线性或分支式执行模型，强调步骤串联与单向流转，其核心假设是“流程确定、路径唯一、状态无须持久”。而LangGraph超越了这一范式——它不将Agent视为被动执行指令的管道，而是主动管理自身状态、动态决策下一步动作的主体。在构建天气查询Agent的过程中，这种差异尤为鲜明：当用户问“上海明天和后天的气温对比如何？”，传统流程可能被迫拆解为固定两步调用，一旦某日数据缺失即告失败；而LangGraph通过State模型统一维护对话历史与查询参数，借助Node封装工具调用逻辑，并由Router依据API响应结果（如成功/超时/格式错误）实时分发至不同处理分支——这不再是预设路径的机械行走，而是基于当下状态的清醒判断。正因如此，LangGraph更适合Agent应用场景：它让智能体真正“活”了起来。 ## 二、构建天气查询Agent ### 2.1 环境准备：安装LangGraph及相关依赖库 踏入LangGraph世界的第一步，不是写代码，而是为思想铺就一条可信赖的轨道。安装LangGraph及其依赖库，看似是机械的命令行操作，实则是一次郑重其事的“迎请”——迎请一个能承载状态、尊重循环、允诺恢复的智能体运行时。只需执行 `pip install langgraph`，便悄然引入了整套有状态编排的底层骨架；若需调用天气API，再辅以 `httpx` 或 `requests` 等轻量HTTP客户端，即可构筑起现实世界与Agent之间的第一道呼吸通道。这一步无需宏大的架构设计，却要求绝对的准确性与一致性：版本兼容性隐于幕后，而开发者对环境的敬畏，正体现在每一个依赖的显式声明与可控约束中。它不喧哗，却奠定所有后续灵动的基础——当Node开始思考、State开始记忆、Router开始抉择，那一切跃动的起点，正是此刻安静敲下的这一行安装指令。 ### 2.2 设计State模型：定义天气查询Agent的状态结构 State，是LangGraph中沉默却最富叙事性的存在。它不是冷冰冰的数据容器，而是Agent在任务旅程中随身携带的“记忆之匣”：匣中盛放用户原始提问、解析出的城市与日期、已获取的天气数据、失败重试次数，甚至是一句尚未向用户出口的歉意草稿。在天气查询Agent中，State模型被精炼为一个结构清晰的Pydantic模型——它强制类型安全，也温柔守护语义完整性。例如，`city: str` 不仅声明字段，更锚定“上海”“北京”等真实地理指称；`date: str` 暗含ISO格式的纪律，让“明天”“后天”终将被确定为“2025-04-06”这样的可计算坐标。这个模型，是Agent的自我认知初稿：它不预设答案，但预先承诺——无论流程如何迂回、中断几度发生，它的“我”，始终由这一组被明确定义、可序列化、可恢复的字段所构成。 ### 2.3 创建Node节点：实现天气查询逻辑和工具调用 Node，是LangGraph中真正“动手做事”的角色，是Agent指尖触达世界的具身化表达。在天气查询Agent中，每个Node都是一段被赋予意图的函数：一个负责解析用户自然语言中的地点与时间（`parse_query`），一个封装HTTP请求并处理API响应（`call_weather_api`），还有一个专司错误捕获与日志沉淀（`handle_failure`）。它们不孤立运行，而是在State的流转中彼此确认、接力推进——前一个Node写入`state.city`，后一个Node便据此发起请求；一次超时触发`state.attempt_count += 1`，随即成为Router判断是否重试的关键依据。这些Node不是黑箱，而是可调试、可测试、可替换的逻辑单元；它们让“查询天气”这件日常之事，在代码层面显影为一组清醒、克制、彼此留有余地的协作动作。 ### 2.4 Router机制：设计决策逻辑以确定下一步行动 Router，是LangGraph赋予Agent的“当下意识”——它不预演全部路径，而是在每一个State抵达时，凝神审视现状，然后轻声说：“现在，该往哪里去？”在天气查询场景中，Router不再依赖固定分支编号，而是基于`state.api_status`字段值进行语义化分发：若为`"success"`，则导向结果格式化Node；若为`"timeout"`且重试未超限，则退回API调用Node；若为`"invalid_city"`，则跳转至澄清对话Node。这种条件判断不是僵硬的if-else罗列，而是将业务逻辑升华为状态驱动的决策契约。它让Agent在面对“上海明天38℃”或“查无此地”时，都能保持同一套判断节律——不因数据完美而傲慢，亦不因异常频发而失序。Router的存在本身即是一种宣言：真正的智能，始于对“此刻状态”的诚实回应。 ## 三、总结 本文以构建最小可运行的天气查询Agent为实践主线，系统阐释了LangGraph作为有状态、可循环、可恢复执行的Agent编排运行时环境的核心价值。通过逐步拆解State模型（定义Agent状态结构）、Node（封装具体执行逻辑）与Router（实现条件化路径分发）三大概念，读者得以在真实代码语境中把握LangGraph区别于传统工作流框架的本质特征。该入门路径不依赖抽象理论堆砌，而始于环境准备、成于结构设计、显于行为决策，切实服务于LangGraph新手对Agent开发范式的扎实理解与可迁移应用。