最近在尝试把一些零散的大模型调用、工具调用和数据处理流程串起来做成一个能稳定运行的 AI Agent 系统。一开始觉得不就是写几个函数然后按顺序调用吗但真做起来发现完全不是那么回事。单次调用一个模型处理一个任务确实简单。但当你需要根据不同的输入动态选择不同的处理路径Router或者把一个复杂任务拆成几个子任务交给不同的“专家”Sub-agent去处理甚至还要让这些“专家”能调用外部工具Skill并且整个过程能记住上下文、能处理异常、能重试时问题就复杂了。你会发现代码里很快充满了if-else、状态判断和回调函数逻辑纠缠在一起调试起来像在解一团乱麻。这时候一个专门用来编排 AI Agent 工作流的框架就显得至关重要。它帮你把“做什么”业务逻辑和“怎么流转”控制流分开。在众多选择中LangGraph 以其基于有向图Graph的直观设计和对复杂工作流的强大支持成为了很多开发者的首选。但面对 LangGraph 里Workflow、Router、Sub-agent、Skill这些核心概念很多人又陷入了新的困惑它们到底有什么区别我的项目里该用哪个怎么组合起来才最有效这篇文章我们就来彻底理清这些概念。我不会只给你一个功能列表而是会结合具体的工程场景告诉你每个组件解决的是什么层面的问题以及在实际搭建一个可维护、可扩展的 Agent 系统时你应该如何思考和选型。1. 先别急着写代码理解 AI Agent 系统的“分层”与“分治”在深入 LangGraph 的具体组件之前我们必须建立一个核心认知一个健壮的 AI Agent 系统其复杂度不是线性增长的而是随着任务复杂性、状态依赖性和外部交互的增加而指数级上升。试图用一套“万能”的扁平化代码来处理所有情况最终只会导致系统难以理解和维护。因此我们的首要任务是对系统进行“分层”和“分治”。这听起来像软件工程的老生常谈但在 Agent 领域它有非常具体的含义。1.1 第一层原子能力层Skill这是系统最底层、最具体的部分。一个Skill就是一个原子化的、可执行的动作单元。它通常对应一次确定性的调用。例如调用某个大模型的 Chat Completion API。执行一个数据库查询。调用一个外部 HTTP API如天气查询、股票数据。运行一段 Python 代码进行数据处理。读写一个文件。Skill 的核心特征是高内聚、低耦合。它只关心“如何完成一件具体的事”而不关心“这件事在哪个工作流中被谁调用”。在 LangGraph 的语境下一个 Skill 通常被实现为一个Tool或者一个封装好的函数function。它的输入和输出是明确的。工程建议在实现 Skill 时要像设计微服务接口一样思考。确保它职责单一只做一件事并做好。接口清晰输入参数、输出格式尤其是错误格式要定义明确。可独立测试不依赖复杂的上下文就能进行单元测试。具备鲁棒性包含基本的错误处理和重试逻辑。1.2 第二层决策与路由层Router Sub-agent当你的系统需要处理多种不同类型的任务或者一个任务需要多种不同的处理策略时你就需要引入决策逻辑。这就是Router和Sub-agent发挥作用的地方。Router路由器它的职责是“根据当前状态决定下一步去哪里”。这是一个纯粹的决策节点。例如在一个客服 Agent 中Router 根据用户问题判断是应该转接到“技术咨询 Sub-agent”、“账单查询 Sub-agent”还是直接使用“信息查询 Skill”。在 LangGraph 中这通常通过一个条件判断边conditional edge来实现其核心是一个判断函数。Sub-agent子智能体你可以把它理解为一个“专家模块”。它本身可能就是一个微型的、具备特定能力的 Agent内部可能封装了多个 Skill 和简单的逻辑。Sub-agent 的引入是为了实现“分治”。例如一个“数据分析 Sub-agent”可能专门负责理解用户的数据分析需求、生成 SQL、执行查询并可视化而一个“内容生成 Sub-agent”则专门负责撰写报告或邮件。Router 和 Sub-agent 常常配合使用Router 像是一个调度中心它根据任务类型将工作分发给最专业的 Sub-agent 去处理。Sub-agent 处理完毕后再将结果返回由 Router 决定下一步是结束、继续分发还是进行结果整合。关键区别Router 是“决策”它本身不处理具体任务只做选择题A/B/C。Sub-agent 是“执行”它接管一个子领域并负责完成该领域内的任务。一个 Sub-agent 内部可以非常复杂甚至可以包含它自己的小工作流。1.3 第三层流程编排层Workflow这是将上述所有元素粘合起来的蓝图和控制器。Workflow工作流定义了整个任务的执行流程图。它明确了系统有哪些节点Nodes哪些是 Skill哪些是 Sub-agent哪里是 Router。节点之间的连接关系Edges在什么条件下从一个节点跳转到另一个节点。系统的全局状态State如何定义和流转数据在各个节点间如何传递和修改。在 LangGraph 中你通过定义一个Graph对象并添加节点和边来构建 Workflow。Workflow 的核心价值在于可视化和可控。你可以清晰地看到任务的所有可能路径并且能够管理循环、并行、条件分支等复杂逻辑。一个常见的误解是认为 Workflow 是“写死”的流程。实际上通过结合 RouterWorkflow 可以实现动态工作流Dynamic Workflow。即下一步要执行哪个节点不是预先完全确定的而是根据上一步的执行结果State动态决定的。这极大地增强了 Agent 的灵活性和适应性。把这四者的关系总结一下Skill是砖块。Sub-agent是由砖块砌成的功能房间如厨房、卧室。Router是连接房间的走廊和指路牌告诉你下一步该去哪个房间。Workflow是整个房子的建筑图纸规定了所有房间和走廊的布局与通行规则。理解了分层我们才能在做技术选型时有的放矢。2. 实战选型从需求倒推架构而非从技术堆砌功能现在我们不再抽象地讨论概念而是面对几个具体的开发场景看看如何运用这些组件来设计解决方案。记住没有最好的架构只有最适合当前需求和未来扩展性的架构。2.1 场景一构建一个智能客服路由中心需求用户输入一个问题系统需要自动判断其意图技术问题、产品咨询、投诉建议并路由到对应的处理模块最后给出统一格式的回复。分析与选型核心挑战意图识别与路由。这是一个典型的分类决策问题。组件选择Router必需这是本场景的核心。你需要一个节点其功能是分析用户输入输出一个意图分类标签如tech_support,product_info,complaint。Skill多个每个处理模块背后可能是一个 Skill。例如“产品信息查询”可能是一个检索知识库的 Skill“技术问题”可能是一个调用故障排除文档的 Skill。Sub-agent可选如果某个模块的处理逻辑非常复杂例如技术问题需要多轮对话诊断则可以将其封装为一个独立的 Sub-agent。对于简单查询直接调用 Skill 更轻量。Workflow必需用于编排整个流程用户输入 - Router - 根据路由结果跳转到对应 Skill/Sub-agent - 整合回复。LangGraph 实现草图from langgraph.graph import StateGraph, END from typing import TypedDict, Literal class AgentState(TypedDict): user_input: str intent: Literal[“tech”, “product”, “complaint”, “unknown”] # Router 的输出 response: str # 最终回复 def router_node(state: AgentState) - AgentState: # 这里可以调用一个 LLM 或一个分类模型来判断意图 # 简化示例基于关键词 if “error” in state[“user_input”].lower() or “bug” in state[“user_input”].lower(): state[“intent”] “tech” elif “price” in state[“user_input”].lower() or “feature” in state[“user_input”].lower(): state[“intent”] “product” else: state[“intent”] “complaint” # 默认 return state def tech_support_skill(state: AgentState) - AgentState: # 调用技术支持的逻辑 state[“response”] f“Tech support handling: {state[‘user_input’]}” return state def product_info_skill(state: AgentState) - AgentState: # 调用产品信息的逻辑 state[“response”] f“Product info for: {state[‘user_input’]}” return state # 构建 Workflow builder StateGraph(AgentState) builder.add_node(“router”, router_node) builder.add_node(“tech_support”, tech_support_skill) builder.add_node(“product_info”, product_info_skill) builder.set_entry_point(“router”) # 设置条件边根据 state[‘intent’] 的值决定下一步 builder.add_conditional_edges( “router”, lambda state: state[“intent”], # 决策函数返回下一个节点的 key { “tech”: “tech_support”, “product”: “product_info”, “complaint”: END, # 直接结束或跳转到其他节点 } ) builder.add_edge(“tech_support”, END) builder.add_edge(“product_info”, END) graph builder.compile()2.2 场景二开发一个多步骤数据分析助手需求用户用自然语言描述一个数据分析需求如“帮我分析上个月销售额最高的三个产品”Agent 需要理解需求、生成查询、执行查询、处理数据并生成可视化图表或文字报告。分析与选型核心挑战这是一个多步骤、可能包含分支的复杂流程且每一步都需要不同的专业能力。组件选择Sub-agent高度推荐这是使用 Sub-agent 的绝佳场景。我们可以设计一个“数据分析师 Sub-agent”它内部协调多个步骤。或者更进一步拆分成“需求理解 Sub-agent”、“SQL 生成 Sub-agent”、“数据可视化 Sub-agent”。Skill多个每个 Sub-agent 会调用具体的 Skill例如调用 LLM 进行需求澄清的 Skill、调用代码解释器生成 SQL 的 Skill、调用数据库连接池执行查询的 Skill、调用绘图库的 Skill。Router可能用到如果用户的需求类型差异很大例如有的只是查询有的需要复杂建模可能需要一个顶层 Router 来分配任务给不同的“专家 Sub-agent”。Workflow必需用于定义 Sub-agent 之间的协作顺序和数据流。这个 Workflow 可能会比客服场景的更复杂可能包含循环如需求不明确时循环澄清。设计思路 与其把所有逻辑塞进一个巨大的节点不如设计一个主 Workflow其中包含几个关键的 Sub-agent 节点。每个 Sub-agent 节点本身可能又是一个小型的 LangGraph。这种“图中有图”的层次化设计能极大提升系统的模块化和可维护性。主 Workflow 负责流程编排和状态传递Sub-agent 负责领域内的具体实现。2.3 场景三实现一个具有长期记忆和工具调用的个人助理需求一个能记住和用户历史对话并能根据用户指令调用各种工具如日历、邮件、搜索引擎的私人助理。分析与选型核心挑战状态记忆的长期维护以及对外部工具的动态调用。组件选择Skill核心每个外部工具查日历、发邮件、搜索网页都应被封装为一个独立的 Skill。这是 Agent 能力的延伸。Workflow核心需要设计一个能够循环运行、持续接收用户输入的工作流。这个 Workflow 通常包含一个“主循环”节点该节点调用 LLMLLM 根据记忆和当前指令决定是直接回复还是调用某个 Skill。Router内嵌在 LLM 中在这个场景中Router 的功能常常由 LLM 本身承担。LLM 根据对话历史和当前指令判断下一步动作Final Answer或Use Tool: xxx。在 LangGraph 中这可以通过ToolNode和条件边来实现让 LLM 的输出来驱动图的流转。Sub-agent可选如果助理功能非常复杂可以按领域划分 Sub-agent如“行程管理 Sub-agent”、“信息检索 Sub-agent”。顶层 Router 根据指令类型来分发。关键实现点 这个场景最能体现 LangGraph 的状态管理优势。你需要精心设计State使其包含messages: 对话历史长期记忆的载体。next: 指示下一步动作由 LLM 决定。tool_result: 工具调用的结果。 Workflow 会循环运行更新消息 - LLM 思考 - 判断下一步 - 执行工具或结束 - 更新状态 - 继续循环。3. 避坑指南新手在 LangGraph 中常犯的五个设计错误理解了概念和场景在实际动手时还有一些常见的“坑”需要避开。这些错误往往会导致系统难以调试、扩展和维护。3.1 错误一把整个业务逻辑写在一个巨大的节点里这是最常见的反模式。开发者图省事在一个节点函数里写了大量的if-else、循环和多个 LLM 调用。这完全违背了使用工作流引擎的初衷。正确做法遵循“单一职责原则”。如果一个节点的代码超过了屏幕一屏或者它做了两件以上的事例如既解析用户意图又调用数据库还格式化结果就应该考虑将其拆分成多个节点或一个 Sub-agent。3.2 错误二State 设计过于复杂或过于扁平State 是 LangGraph 中节点间通信的唯一媒介。设计不好后续寸步难行。过于复杂State 是一个包含多层嵌套、各种数据类型的巨大字典。这导致每个节点都需要知道复杂结构的细节耦合度高。过于扁平所有数据都堆在顶层缺乏结构容易产生键名冲突且难以管理数据生命周期。正确做法使用TypedDict或Pydantic模型来明确定义 State 的结构。将数据按模块或生命周期分组。例如class AgentState(TypedDict): # 输入/原始数据 user_query: str raw_data: Any # 处理中间状态 current_step: str extracted_info: Dict # 工具调用相关 next_action: str # “call_tool”, “final_answer” tool_name: Optional[str] tool_args: Optional[Dict] tool_result: Optional[str] # 最终输出 final_response: str3.3 错误三忽视错误处理和边缘情况工作流在运行中任何节点都可能失败LLM 调用超时、工具返回异常、网络错误等。如果不在设计时考虑系统会崩溃或卡死。正确做法节点级容错在每个节点函数内部使用try-except捕获可能异常并将错误信息妥善地放入 State例如state[“error”] str(e)供后续节点或 Router 判断。工作流级容错设计专门的“错误处理节点”或利用条件边。例如可以设置一个规则如果 State 中包含error字段则路由到一个“补偿节点”或直接跳转到 END并返回一个友好的错误消息。设置超时和重试对于调用外部 API 的节点务必配置超时。对于暂时性错误可以实现简单的重试逻辑。3.4 错误四混淆 Router 和 Sub-agent 的职责这个问题在概念不清时经常发生。记住Router 是交警它只指挥交通决定下一步去哪不亲自修路或开车不处理具体业务。Sub-agent 是特种部队它被派往一个地点负责完成一项具体的战术任务处理一个子问题。如果一个模块既做了复杂的业务处理又根据处理结果决定了下一步的流向那么它可能承担了过多职责。应考虑将其拆分为一个“纯业务处理节点”和一个紧随其后的“纯路由判断节点”。3.5 错误五没有为工作流设计可视化与调试接口LangGraph 的一个巨大优势是图结构可可视化。但很多开发者只停留在代码层面当流程复杂时靠print日志来调试如同大海捞针。正确做法善用 LangGraph Studio这是官方提供的可视化开发工具可以直观地看到工作流图并逐步执行、检查每个节点的输入输出 State。在开发阶段不可或缺。结构化日志为每个节点的执行记录结构化的日志包括节点名、输入 State关键字段、输出 State、耗时、是否出错等。这能帮你快速定位性能瓶颈和逻辑错误。状态快照在关键节点后可以考虑将 State 的快照持久化如存到数据库。这对于复现和调试复杂、多轮的工作流非常有帮助。4. 进阶思考从“能跑通”到“可工程化”的跨越当你用 LangGraph 成功搭建了一个可以运行的原型后接下来要考虑的是如何让它成为一个真正可靠、可维护、可扩展的生产级系统。这涉及到一些更深层次的工程化考量。4.1 性能与并发Workflow 不是银弹LangGraph 本身是工作流编排框架它不直接解决并发和性能问题。一个包含多个 LLM 调用的复杂 Workflow可能会很慢。优化策略异步节点确保你的节点函数特别是那些调用 I/O如网络请求、数据库查询的是异步的async。LangGraph 支持异步执行这能有效提高吞吐量。并行执行分析你的工作流图如果某些节点之间没有数据依赖关系可以考虑使用 LangGraph 的Pregel接口的并发特性来并行执行。但要注意LLM 调用通常有速率限制盲目并行可能导致被限流。缓存对于昂贵的、结果确定的操作如某些复杂的数据库查询或外部 API 调用可以考虑引入缓存机制将结果缓存起来避免重复计算。4.2 可观测性与监控在生产环境中你需要知道你的 Agent 系统运行得怎么样。需要监控的指标工作流执行耗时整体耗时、每个节点的耗时。节点成功率/失败率哪个节点最容易出错LLM 调用成本与延迟Token 消耗、响应时间。路由分布各个分支路径被触发的频率这有助于你优化 Router 逻辑和资源分配。实现方式可以在节点函数中埋点将指标发送到监控系统如 Prometheus。也可以利用 LangGraph 的Checkpointer或回调系统来追踪执行过程。4.3 版本管理与迭代你的 Agent 系统会不断迭代更新 Prompt、调整路由逻辑、增加新的 Skill 或 Sub-agent。挑战如何管理不同版本的工作流定义如何做到灰度发布和回滚建议代码化将 LangGraph 的工作流定义像其他代码一样进行版本控制Git。配置化将容易变化的元素如 Router 的判断阈值、某些节点的 Prompt 模板抽取为配置文件或数据库配置实现热更新。蓝绿部署对于核心工作流可以考虑部署两套环境通过流量切换来验证新版本。4.4 安全与权限当 Agent 能够调用外部工具Skill时安全就成为重中之重。Skill 的权限控制不是所有请求都能调用所有 Skill。需要根据用户身份、会话上下文等对 Skill 的调用进行鉴权。这可以在调用 Skill 的节点之前增加一个“权限校验”节点来实现。输入输出过滤对用户输入和 LLM 的输出进行安全检查防止注入攻击或恶意指令。敏感信息处理确保 State 中流转的敏感信息如 API Key、用户个人数据不会被泄露到日志或错误信息中。回到最初的问题Workflow、Router、Sub-agent、Skill 到底怎么选答案不在于记住它们的定义而在于理解它们所应对的系统复杂度层次。Skill 解决“怎么做”的问题Router 解决“去哪做”的问题Sub-agent 解决“谁来做”的问题而 Workflow 解决“如何组织大家有序地做”的问题。在设计你的 AI Agent 系统时不妨先在白板上画出你想象中的任务处理流程图。问问自己哪些步骤是原子操作封装为 Skill哪些决策点需要动态判断引入 Router哪些部分可以打包成一个独立的、可复用的功能模块设计为 Sub-agent最后用 Workflow 这张“图纸”把它们有机地连接起来并管理好数据State的流动。LangGraph 提供的是一套强大的范式和一组合适的积木。真正的挑战和乐趣在于你如何根据自己独特的业务场景搭建出既坚固又灵活的系统架构。从今天起试着用分层的眼光去看待你的 Agent 设计你会发现很多纠结会自然消散而通往可维护、可扩展系统的路径会变得清晰起来。