技能使用指南

langgraph（LangGraph 语言图）Skill 是什么？如何搭建状态化 AI 代理？

LangGraph（语言图）Skill 以代理架构师身份，教你用 StateGraph 构建状态化、可调试的生产级 AI 代理，覆盖状态归约器、条件路由、检查点持久化与人机交互。本文含一键安装思路、分步使用指南、竞品对比与典型场景，帮你避开无限循环等常见坑，快速把原型推进到生产。

LangGraph（语言图）Skilllanggraph
13 个章节 约 13 分钟阅读 AI 智能生成

LangGraph（语言图）Skill：用「图」把 AI 代理的流程画出来，构建可调试、可持久化的生产级智能体

  • 它是什么：一个专注于 LangGraph 框架的专家型 AI 技能，扮演「LangGraph 代理架构师」，帮你把状态化、多参与者的 AI 应用按「图」的方式搭出来，而不是堆一段难以维护的提示词链。
  • 它解决什么问题：让代理的执行流程变得可见、可调试、可持久化，条件分支、循环、人工介入、断点续跑都有明确的结构化写法。
  • 核心能力：StateGraph 图构造、状态管理与归约器、条件路由、检查点持久化、人机交互模式、工具集成、流式与异步执行、ReAct 代理模式。
  • 上手门槛：需要 Python 3.9+、langgraph 包、LLM API 访问能力，以及对「图」这一基本概念的理解。
  • 适合谁：想把原型代理推进到生产环境的 AI 工程师、后端开发者、以及需要多代理协作编排的技术团队。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能中文名：LangGraph（语言图）Skill 技能英文名：langgraph 技能ID：12415

这是一个面向 LangGraph 框架的专家技能。LangGraph 是 LangChain 官方推荐用于构建代理（Agent）的方式，主打「状态化」与「图结构」：把代理的每一步拆成节点，把节点之间的流转画成边，把共享数据放进状态。据技能说明，该框架已在 LinkedIn、Uber 以及 400 多家公司的生产环境中使用。

它解决的问题非常具体——代理一旦复杂起来就容易失控：循环停不下来、上下文丢失、分支逻辑散落在 if-else 里、出错后无法从中间恢复。LangGraph 用图把这些都显式化，而本技能就是把「怎么正确用 LangGraph」这件事打包成一个可随时召唤的专家。

一键安装的思路与步骤

  1. 确认安装前提：本技能对运行环境的要求写在技能说明里——Python 3.9+、已安装 langgraph 包、可用的 LLM API（如 OpenAI、Anthropic 等），以及理解图的基本概念。具体版本的安装命令请以官方说明为准。
  2. 找到技能入口：在支持技能的 AI 客户端或技能市场中，用技能英文名 langgraph 或技能ID 12415 检索，具体入口位置以官方说明为准。
  3. 一键安装/启用：点击安装或启用后，技能会以「LangGraph 代理架构师」的角色身份生效，无需你自己写提示词去描述框架细节。
  4. 验证是否生效：安装完成后，直接提问「用 LangGraph 写一个带工具调用的 ReAct 代理图」，如果返回的内容包含状态定义、节点、条件边、编译调用等结构化代码，且明确使用了 StateGraph、add_messages 等框架要素，说明技能已正常工作。
  5. 补充依赖：如果返回的代码依赖某些包，按官方文档补齐后再运行。

一键安装的真正价值在于：你省下的不只是查文档的时间，而是「架构决策」的时间——状态怎么设计、哪里该加归约器、循环怎么防止跑飞，这些经验被预先封装好了。

2. 该技能的主要功能和特点

  • 图构造（StateGraph）：以节点 + 边的方式组织代理流程，把「代理做了什么」从黑盒变成可视化的流程图。
  • 状态管理与归约器：支持 Annotated + 归约器来定义字段的合并规则，例如消息列表用 add_messages 追加而不是覆盖、字典用自定义函数合并、列表用 add 累积、整数错误计数用自定义函数累加。
  • 节点与边定义：节点是纯函数，只返回「要更新的字段」，其余状态由框架维护，避免手写状态机的混乱。
  • 条件路由：通过路由函数返回节点名称，实现「分类 → 分流到不同代理」的多路径工作流。
  • 检查点与持久化：内置检查点机制，支持对话恢复与长流程中断续跑，这是普通提示词链最难做到的部分。
  • 人机交互模式：支持在流程中间插入人工确认/修改环节，适合高风险操作前的审批。
  • 工具集成：可直接接入 LangChain 生态的工具（如 @tool 装饰器定义的工具），配合 ToolNode 完成工具执行。
  • 流式与异步执行：支持流式输出与异步调用，便于做实时交互体验。
  • 反模式提醒：技能内置了「无退出的无限循环」「无状态节点」「巨型单体状态」等常见坑的说明与替代方案，这是普通代码补全工具不会主动告诉你的。

和普通工具比强在哪：普通代码助手能写一段能跑的 LangChain 调用，但不会提醒你「这里没有退出条件会烧钱」「这个状态设计会导致序列化开销爆炸」。本技能以架构师角色输出，天然带着生产视角。

3. 如何使用该技能？

第 1 步：明确你的代理形态。 先说清楚是单代理工具调用、多代理共享状态，还是需要按查询类型分流。不同形态对应技能里的不同模式。

第 2 步：让技能产出状态定义。 状态是整个图的地基。示例提问：

「我要做一个能搜索和计算的代理，消息需要累积、错误需要计数，帮我定义状态。」

技能会给出类似以下结构（基于技能说明中的示例）：

from typing import Annotated, TypedDict
from langgraph.graph.message import add_messages

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]  # 追加而非覆盖

第 3 步：定义工具与节点。 用 @tool 装饰器描述工具能力，节点函数只返回局部更新。

def agent(state: AgentState) -> dict:
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

第 4 步：定义路由与边。 路由函数根据最后一条消息是否包含工具调用，决定回到代理还是结束；工具节点执行完再循环回代理。

def should_continue(state: AgentState) -> str:
    if state["messages"][-1].tool_calls:
        return "tools"
    return END

第 5 步：编译并运行。 graph.compile() 得到可执行应用，传入初始状态即可。

result = app.invoke({"messages": [("user", "25 * 4等于多少？")]})

输出说明：返回的最终状态中，messages 会包含用户提问、工具调用请求、工具返回结果以及代理的最终回答；由于使用了 add_messages 归约器，历史消息是逐条累积的，可直接用于多轮对话。

第 6 步：上线前做审查。 主动追问技能「这个图有没有退出条件？循环最多几次？检查点存哪里？」用它的反模式清单自查一遍。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
LangGraph（语言图）Skill（本技能） 以专家角色指导 LangGraph 图式代理开发 图构造、状态与归约器、条件路由、检查点持久化、人机交互、工具集成 需 Python 3.9+、langgraph 包、LLM API；技能本身一键安装 状态化单/多代理、需要断点续跑与人工审批的生产流程 优势：流程显式、可调试、生产级持久化，反模式提示到位；不足：图概念有学习曲线，目前以 Python 为主
手写 LangChain 链式调用 直接用链式组合提示词与工具 提示词串联、简单工具调用 门槛较低，熟悉框架即可 短流程、单轮任务、快速原型 优势：上手快、代码短；不足：分支与循环难维护，缺少持久化与断点恢复
CrewAI 面向角色分工的多代理协作框架 角色/任务编排、代理协作 需单独安装与配置，以官方说明为准 多角色分工的协作型任务 优势：角色抽象直观；不足：流程控制粒度不如显式图，复杂分支需绕路实现
自主代理框架（通用型） 让代理自行规划、自主调用工具 自主规划、工具循环 依赖配置较多 探索型、开放式任务 优势：灵活度高；不足：可控性弱、易陷入无限循环，生产调试成本高

选择建议：如果流程短、一次性、跑通即可，手写链式调用更省事；如果任务需要角色分工，可考虑 CrewAI；但只要你的流程涉及循环、分支、中断恢复、人工审核，图结构的优势就会非常明显。

5. 该技能的典型应用场景与实际体验情况

场景一：需要工具调用的客服/查询代理

角色：后端开发者。痛点：代理一会儿调搜索、一会儿直接回答，循环次数不可控。用法：用基础代理图模式，路由函数判断是否存在工具调用，工具执行后回边到代理形成受控循环。 体验：上手难度中等，代码结构比手写循环清晰得多；注意事项是一定要加迭代上限或明确 END 条件，否则代理可能反复调工具消耗额度。

场景二：多代理协作的研究型应用

角色：AI 应用工程师。痛点：研究代理和写作代理共享信息时互相覆盖，来源列表越写越乱。用法：用带归约器的状态，findings 用字典合并、sources 用列表累加、current_step 直接覆盖。 体验：归约器一上，状态冲突问题基本消失；注意状态字段不要什么都往里塞，避免形成「巨型单体状态」拖慢序列化。

场景三：多渠道请求分流系统

角色：平台架构师。痛点：代码类、搜索类、闲聊类请求混在一条链里，if-else 越写越长。用法：分类节点 + 条件边，按 query_type 路由到不同代理节点，各分支统一汇入 END。 体验：可读性提升最明显，新增一路只需加节点和一条条件边；注意路由函数必须返回明确的节点名，拼错会导致编译或运行报错。

场景四：需要人工确认的高风险操作

角色：业务系统开发者。痛点：让代理自动执行写操作风险太高，但中途暂停后上下文又丢了。用法：结合检查点持久化与人机交互模式，在关键节点暂停等待确认，恢复时从检查点继续。 体验：这是 LangGraph 相对其他方案最有辨识度的能力；注意事项是检查点存储方案要提前规划，否则长流程恢复会失效。

6. 该技能能为用户带来的价值

  • 效率提升：把「查文档 + 试错 + 重构」压缩成一次对话。常见代理骨架（状态定义、节点、条件边、编译）可以快速拿到可用起点，减少反复改写的时间。
  • 门槛降低：不需要先成为 LangGraph 专家。技能以架构师角色输出，把归约器、检查点、条件路由这些概念落到具体代码上，边写边学。
  • 风险降低：内置的反模式清单能提前拦住「无限循环烧额度」「无状态节点失去持久化」「单体状态拖慢序列化」这三类最常见的生产事故。
  • 可量化收益：受控循环意味着可控的调用次数，直接对应可控的成本；检查点持久化意味着流程中断后可恢复，避免重复执行带来的二次开销。
  • 长期价值：图结构的代码天然是「可读的架构文档」。团队交接时，看节点和边就知道业务流向，比读一大段提示词拼接代码高效得多。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要花钱吗？ A：在支持技能的客户端或技能市场中，用英文名 langgraph 或技能ID 12415 检索并启用即可，具体入口与计费方式以官方说明为准。技能本身来源于 vibeship-spawner-skills（Apache 2.0 许可）；但使用它的产出运行代理时，还需要你自己的 LLM API，这部分费用由对应模型服务商收取。

Q2：它是 LangGraph 框架本身吗？ A：不是。框架需要你自行安装（Python 3.9+ 环境 + langgraph 包）。这个技能是「LangGraph 代理架构师」角色，负责指导你如何设计状态、组织节点、设置路由与持久化，产出可直接参考的代码结构。

Q3：我完全没接触过「图」，能直接用吗？ A：可以用，但要预留学习时间。技能说明中明确把「图概念的学习曲线」列为限制之一。建议先从基础代理图模式跑通一个「工具调用 → 回答」的最小例子，再逐步加分支和持久化。

Q4：和 CrewAI 这类多代理框架怎么选？ A：看你要的是「角色分工」还是「流程控制」。CrewAI 的角色/任务抽象更直观，适合协作型任务；LangGraph 的图模型在分支、循环、断点续跑、人工介入上粒度更细，更适合流程复杂且需要上生产的场景。

Q5：为什么它老是提醒我加退出条件？ A：因为「无退出的无限循环」是代理开发中最贵的一类错误——代理会一直循环、持续消耗 token，直到报错。技能内置的反模式建议是：在状态里放最大迭代计数器、在路由函数中写明确的 END 条件，并配合应用级超时。