【langgraph 从入门到精通graphApi 篇】LangGraphAPI 方式调用 - 初识与核心概念

文章目录第 1 章LangGraph 初识与核心概念1.1 本章目标1.2 核心概念LangGraph 是什么LangGraph 在 AI 生态中的位置第一个 Graph 的内部结构1.3 实战你的第一个 LangGraph 程序1.4 API 速查1.5 错误与避坑指南坑 1忘记导入 START 和 END坑 2节点函数返回 None 而非 dict坑 3返回的 key 不在 State 中坑 4混淆 invoke() 的参数1.6 最佳实践总结第 1 章LangGraph 初识与核心概念1.1 本章目标学完本章你将能够理解 LangGraph 在 AI 开发生态中的定位掌握 State、Node、Edge、Graph 四大核心概念独立编写并运行第一个 LangGraph 程序1.2 核心概念LangGraph 是什么在计算机科学中图Graph由节点Node和边Edge组成。节点是执行任务的单元边是连接节点的线决定了任务执行的先后顺序。就像地铁线路图——每个站点是节点连接站点的轨道是边。LangGraph 是一个有状态的多步骤 AI 应用编排框架。你可以把它想象成一个智能工厂的流水线概念比喻工厂流水线技术定义Graph图整个工厂的布局图定义了所有节点和边的有向图结构State状态在流水线上流转的零件在节点间共享的数据结构每个节点可以读取和修改Node节点每个工位执行具体操作的函数LLM 调用、工具执行、数据处理Edge边连接工位的传送带定义节点间的执行顺序和条件核心公式Nodes 做工作Edges 决定流程State 是纽带LangGraph 在 AI 生态中的位置基础设施模型层编排层AI 应用层你的 AI 应用LangGraph状态编排 流程控制LangChain模型调用 工具集成 提示词LLM 模型OpenAI / Claude / DeepSeek / ...持久化Checkpoint / Store外部工具搜索 / 计算 / API第一个 Graph 的内部结构开始完成STARTgreet 节点生成问候语END1.3 实战你的第一个 LangGraph 程序让我们从一个最简单的例子开始输入一个人的名字输出一句问候语。# # 第 1 步导入必要的模块# fromtypingimportTypedDictfromlanggraph.graphimportStateGraph,START,END# # 第 2 步定义 State状态—— 图中流转的数据结构# classState(TypedDict): State 是图中所有节点共享的数据结构。 使用 TypedDict 定义提供类型安全和 IDE 提示。 这里定义了两个字段 - name: 用户输入的名字 - greeting: 生成的问候语初始为空 name:strgreeting:str# TypedDict 是 Python 的类型提示工具它定义了字典中每个键对应的值类型。# LangGraph 用 TypedDict 来声明 State 的结构这样 IDE 可以自动补全字段名# 也能在编写代码时检查类型错误。# # 第 3 步定义 Node节点—— 执行具体操作的函数# defgreet(state:State)-dict: 节点函数签名规则 - 参数接收当前 State 作为输入 - 返回值返回一个 dict包含要更新的 State 字段 注意只需返回要更新的字段不需要返回完整 State LangGraph 会自动将返回值合并到当前 State 中。 print(f [greet 节点] 收到名字:{state[name]})# 从 State 中读取 name生成问候语返回更新return{greeting:f你好,{state[name]}!}# # 第 4 步构建 Graph图—— 把节点和边组合起来# # 创建 StateGraph 构建器传入 State 类型builderStateGraph(State)# 注册节点给 greet 函数起名为 greetbuilder.add_node(greet,greet)# 添加边流程控制# START → greet → END# 表示从图入口开始执行 greet 节点然后结束builder.add_edge(START,greet)builder.add_edge(greet,END)# 编译图将构建器冻结为可执行的图对象graphbuilder.compile()# # 第 5 步运行 Graph# print( 执行 Graph )# invoke() 方法传入初始状态返回最终状态resultgraph.invoke({name:小明})print(f 结果:{result[greeting]})# # 运行输出# 执行 Graph # [greet 节点] 收到名字: 小明# 结果: 你好, 小明!# 代码执行流程解析graph.invoke({name: 小明})— 传入初始 State只有namegreeting为默认值图从START出发找到第一条边START → greet执行greet节点函数传入当前 State函数返回{greeting: 你好, 小明!}图将返回值合并到 State 中State 变为{name: 小明, greeting: 你好, 小明!}找到下一条边greet → END图结束invoke()返回最终的完整 State1.4 API 速查API完整签名入参说明返回值说明StateGraph(state_schema)StateGraph(state_schema: Type[StateT])state_schema: State 类型TypedDict/dataclass/PydanticStateGraph构建器对象创建状态图构建器.add_node(name, action)add_node(node: str, action: Callable)node: 节点名str;action: 节点函数Self支持链式调用注册一个节点.add_edge(start, end)add_edge(start_key: str, end_key: str)start_key: 源节点名;end_key: 目标节点名Self添加一条普通边.compile()compile(checkpointer, interrupt_before, interrupt_after, ...)可选参数见后续章节CompiledStateGraph编译图使之可执行.invoke(input)invoke(input: dict, config: dict None)input: 初始 State 字典;config: 运行配置可选dict最终 State同步执行图1.5 错误与避坑指南坑 1忘记导入 START 和 END# ❌ 错误写法fromlanggraph.graphimportStateGraph# 只导入了 StateGraphbuilderStateGraph(State)builder.add_edge(START,my_node)# NameError: name START is not defined# ✅ 正确写法fromlanggraph.graphimportStateGraph,START,END# 同时导入 START 和 END坑 2节点函数返回 None 而非 dict# ❌ 错误写法defbad_node(state:State):print(处理中...)# 忘记返回值隐式返回 None# → LangGraph 收到 None无法更新 State可能报错或静默失败# ✅ 正确写法defgood_node(state:State)-dict:print(处理中...)return{some_field:new_value}# 必须返回 dict坑 3返回的 key 不在 State 中classState(TypedDict):name:strgreeting:str# ❌ 错误写法defbad_node(state:State)-dict:return{message:hello}# message 不在 State 中定义运行时报错# ✅ 正确写法defgood_node(state:State)-dict:return{greeting:hello}# greeting 在 State 中定义坑 4混淆 invoke() 的参数# ❌ 错误写法graph.invoke(hello)# 传入字符串而非 dict# ✅ 正确写法graph.invoke({name:小明})# 传入 dictkey 对应 State 的字段1.6 最佳实践总结使用 TypedDict 定义 State类型安全IDE 有完整提示出错时容易定位问题节点函数保持单一职责一个节点只做一件事如搜索、“生成回复”、“调用工具”不要在一个节点里做太多事始终从 START 到 END 形成完整路径确保每个节点都有入口和出口避免死胡同节点返回值只包含变更字段不需要返回完整 StateLangGraph 自动合并减少冗余代码先画图再写代码复杂流程先用 Mermaid 画出图结构再着手实现思路更清晰