1. LangGraph 核心定位与设计哲学LangGraph 本质上是一个面向长期运行、有状态智能体stateful agents的低层级编排框架。与常规任务编排工具不同它的设计哲学体现在三个关键维度持久化执行引擎采用类似Pregel模型的计算范式通过检查点机制实现故障恢复。当agent因网络中断或代码错误崩溃时系统能自动从最近的有效状态恢复而非重新开始整个工作流。这种特性对处理耗时数小时甚至数天的复杂任务至关重要。状态显式管理所有工作流状态包括短期上下文和长期记忆都通过Pydantic模型强制结构化。开发者可以精确控制哪些数据需要跨会话持久化如写入数据库哪些仅作为临时计算中间值如LLM生成的中间推理步骤。这种设计避免了传统方案中状态管理混乱的问题。人机协同接口内置的interrupt机制允许在任意执行节点插入人工审核或修改。例如当agent检测到高风险操作如发送邮件或执行支付时可以暂停流程并等待人工确认。这种设计模式在金融、医疗等合规敏感场景尤为实用。提示虽然常与LangChain比较但LangGraph的定位更接近智能体的操作系统内核。它不提供现成的RAG或工具调用实现而是专注于解决长期运行agent的基础设施难题。2. 环境搭建与核心组件剖析2.1 安装与最小验证推荐使用隔离环境进行安装python -m venv langgraph-env source langgraph-env/bin/activate # Linux/Mac pip install -U langgraph验证安装成功的标准方式from langgraph.graph import Graph print(Graph.__version__) # 应输出类似1.2.9的版本号2.2 四大核心抽象StateGraph工作流的状态容器from langgraph.graph import StateGraph workflow StateGraph(MyStateModel) # 需定义继承自pydantic.BaseModel的状态模型Node执行单元的最小颗粒度def retrieval_node(state: MyStateModel): # 实现检索逻辑 return {new_data: processed_result} workflow.add_node(retriever, retrieval_node)Edge控制流路由规则from langgraph.graph import END workflow.add_edge(retriever, generator) # 线性流程 workflow.add_conditional_edges( # 条件分支 classifier, lambda x: path_a if x[category] A else path_b )Checkpointer持久化引擎支持Redis、Postgres等后端from langgraph.checkpoint.redis import RedisCheckpointer checkpointer RedisCheckpointer( hostlocalhost, ttl3600 # 状态保留1小时 )3. 实战构建带记忆的客服Agent3.1 状态模型设计良好的状态设计是LangGraph应用的关键from pydantic import BaseModel from typing import Dict, List class CustomerSession(BaseModel): chat_history: List[Dict] [] # 对话记忆 current_query: str product_db: List[Dict] [] # 产品数据库快照 pending_actions: List[str] [] # 待执行操作3.2 工作流组装构建包含异常处理的完整流程def query_analyzer(state: CustomerSession): # 使用LLM解析用户意图 return {intent: analyzed_result} def product_retriever(state: CustomerSession): # 向量数据库检索 return {products: matched_items} def response_generator(state: CustomerSession): # 生成自然语言回复 if needs_human_approval(state): raise InterruptionRequired(需人工审核回复内容) return {response: generated_text} # 组装工作流 workflow StateGraph(CustomerSession) workflow.add_node(analyze, query_analyzer) workflow.add_node(retrieve, product_retriever) workflow.add_node(generate, response_generator) # 定义流转逻辑 workflow.add_edge(analyze, retrieve) workflow.add_edge(retrieve, generate) # 配置中断处理 workflow.set_interrupt_handler( lambda _: input(请输入审核意见:) )3.3 运行与调试启动工作流并连接LangSmith观察app workflow.compile(checkpointercheckpointer) # 模拟用户输入 result app.invoke({ current_query: 推荐适合程序员的笔记本电脑, product_db: load_products() }) # LangSmith跟踪URL会自动打印4. 高级模式与性能优化4.1 子图与分布式执行对于复杂场景可将工作流模块化sub_graph StateGraph(...) main_graph.add_node(submodule, sub_graph)通过ray实现分布式节点执行from langgraph.distributed import RayNode ray_node RayNode.bind( retriever_node, runtime_env{pip: [langgraph]} )4.2 记忆压缩策略长期运行的agent会产生大量记忆数据推荐采用关键事件摘要使用LLM定期生成对话摘要向量化压缩将文本记忆转换为embedding存储TTL自动清理为不同数据类型设置生存时间from langgraph.memory import VectorMemory memory VectorMemory( embedding_modeltext-embedding-3-small, max_entries1000 )4.3 容错机制实战通过装饰器实现重试逻辑from langgraph.decorators import retry retry(max_attempts3, delay1.0) def unreliable_api_call(state): # 调用可能失败的外部API配置熔断策略防止级联故障from langgraph.circuit_breaker import CircuitBreaker cb CircuitBreaker( failure_threshold5, recovery_timeout60 ) cb.protect def critical_service(state): # 关键业务逻辑5. 生产环境部署要点5.1 监控指标埋点核心监控维度应包括节点执行耗时分布状态存储吞吐量中断事件频率记忆使用增长率Prometheus配置示例from langgraph.metrics import PrometheusExporter exporter PrometheusExporter( port9090, registryglobal_registry )5.2 水平扩展方案采用分片策略处理高并发from langgraph.cluster import ShardedExecutor executor ShardedExecutor( nodes_per_shard5, checkpointerRedisCheckpointer(shardedTrue) )5.3 安全合规实践敏感数据自动脱敏如信用卡号识别所有状态变更记录审计日志通过interrupt实现关键操作四眼原则class PaymentAction(BaseModel): amount: float recipient: str approval_token: str None # 需人工审核填充
1. LangGraph 核心定位与设计哲学LangGraph 本质上是一个面向长期运行、有状态智能体stateful agents的低层级编排框架。与常规任务编排工具不同它的设计哲学体现在三个关键维度持久化执行引擎采用类似Pregel模型的计算范式通过检查点机制实现故障恢复。当agent因网络中断或代码错误崩溃时系统能自动从最近的有效状态恢复而非重新开始整个工作流。这种特性对处理耗时数小时甚至数天的复杂任务至关重要。状态显式管理所有工作流状态包括短期上下文和长期记忆都通过Pydantic模型强制结构化。开发者可以精确控制哪些数据需要跨会话持久化如写入数据库哪些仅作为临时计算中间值如LLM生成的中间推理步骤。这种设计避免了传统方案中状态管理混乱的问题。人机协同接口内置的interrupt机制允许在任意执行节点插入人工审核或修改。例如当agent检测到高风险操作如发送邮件或执行支付时可以暂停流程并等待人工确认。这种设计模式在金融、医疗等合规敏感场景尤为实用。提示虽然常与LangChain比较但LangGraph的定位更接近智能体的操作系统内核。它不提供现成的RAG或工具调用实现而是专注于解决长期运行agent的基础设施难题。2. 环境搭建与核心组件剖析2.1 安装与最小验证推荐使用隔离环境进行安装python -m venv langgraph-env source langgraph-env/bin/activate # Linux/Mac pip install -U langgraph验证安装成功的标准方式from langgraph.graph import Graph print(Graph.__version__) # 应输出类似1.2.9的版本号2.2 四大核心抽象StateGraph工作流的状态容器from langgraph.graph import StateGraph workflow StateGraph(MyStateModel) # 需定义继承自pydantic.BaseModel的状态模型Node执行单元的最小颗粒度def retrieval_node(state: MyStateModel): # 实现检索逻辑 return {new_data: processed_result} workflow.add_node(retriever, retrieval_node)Edge控制流路由规则from langgraph.graph import END workflow.add_edge(retriever, generator) # 线性流程 workflow.add_conditional_edges( # 条件分支 classifier, lambda x: path_a if x[category] A else path_b )Checkpointer持久化引擎支持Redis、Postgres等后端from langgraph.checkpoint.redis import RedisCheckpointer checkpointer RedisCheckpointer( hostlocalhost, ttl3600 # 状态保留1小时 )3. 实战构建带记忆的客服Agent3.1 状态模型设计良好的状态设计是LangGraph应用的关键from pydantic import BaseModel from typing import Dict, List class CustomerSession(BaseModel): chat_history: List[Dict] [] # 对话记忆 current_query: str product_db: List[Dict] [] # 产品数据库快照 pending_actions: List[str] [] # 待执行操作3.2 工作流组装构建包含异常处理的完整流程def query_analyzer(state: CustomerSession): # 使用LLM解析用户意图 return {intent: analyzed_result} def product_retriever(state: CustomerSession): # 向量数据库检索 return {products: matched_items} def response_generator(state: CustomerSession): # 生成自然语言回复 if needs_human_approval(state): raise InterruptionRequired(需人工审核回复内容) return {response: generated_text} # 组装工作流 workflow StateGraph(CustomerSession) workflow.add_node(analyze, query_analyzer) workflow.add_node(retrieve, product_retriever) workflow.add_node(generate, response_generator) # 定义流转逻辑 workflow.add_edge(analyze, retrieve) workflow.add_edge(retrieve, generate) # 配置中断处理 workflow.set_interrupt_handler( lambda _: input(请输入审核意见:) )3.3 运行与调试启动工作流并连接LangSmith观察app workflow.compile(checkpointercheckpointer) # 模拟用户输入 result app.invoke({ current_query: 推荐适合程序员的笔记本电脑, product_db: load_products() }) # LangSmith跟踪URL会自动打印4. 高级模式与性能优化4.1 子图与分布式执行对于复杂场景可将工作流模块化sub_graph StateGraph(...) main_graph.add_node(submodule, sub_graph)通过ray实现分布式节点执行from langgraph.distributed import RayNode ray_node RayNode.bind( retriever_node, runtime_env{pip: [langgraph]} )4.2 记忆压缩策略长期运行的agent会产生大量记忆数据推荐采用关键事件摘要使用LLM定期生成对话摘要向量化压缩将文本记忆转换为embedding存储TTL自动清理为不同数据类型设置生存时间from langgraph.memory import VectorMemory memory VectorMemory( embedding_modeltext-embedding-3-small, max_entries1000 )4.3 容错机制实战通过装饰器实现重试逻辑from langgraph.decorators import retry retry(max_attempts3, delay1.0) def unreliable_api_call(state): # 调用可能失败的外部API配置熔断策略防止级联故障from langgraph.circuit_breaker import CircuitBreaker cb CircuitBreaker( failure_threshold5, recovery_timeout60 ) cb.protect def critical_service(state): # 关键业务逻辑5. 生产环境部署要点5.1 监控指标埋点核心监控维度应包括节点执行耗时分布状态存储吞吐量中断事件频率记忆使用增长率Prometheus配置示例from langgraph.metrics import PrometheusExporter exporter PrometheusExporter( port9090, registryglobal_registry )5.2 水平扩展方案采用分片策略处理高并发from langgraph.cluster import ShardedExecutor executor ShardedExecutor( nodes_per_shard5, checkpointerRedisCheckpointer(shardedTrue) )5.3 安全合规实践敏感数据自动脱敏如信用卡号识别所有状态变更记录审计日志通过interrupt实现关键操作四眼原则class PaymentAction(BaseModel): amount: float recipient: str approval_token: str None # 需人工审核填充
