如果你正在做 Agent 方向的开发2026 年这个时间点 LangChain 和 LangGraph 基本是无法绕开的技术栈。LangChain 负责把大模型、向量库、工具调用这些能力组合成生产可用的链路LangGraph 则在更底层用图状态机的思路把 Agent 的流程讲清楚让多步骤、多工具、人类介入审批这类企业级需求变得可控。这套“LangChain LangGraph 开发实战”课程的核心就是带你从最简单的 Prompt 调用开始一路做到带 RAG、带工具调用、带记忆、带节点控制流的企业级 Agent。这篇文章会从学习路线的角度把整个课程涉及的关键知识点拆开讲先说明两份框架的核心能力和分工再给出环境准备、安装部署、功能测试、API 服务封装、批量任务、性能观察和常见问题排查的完整流程。也就是说这篇文章不是单纯的路由推荐而是把所有关键技术点串成一条可执行的实战路线你可以照着装环境、跑案例再回到自己的业务里去设计 Agent。无论你是刚接触 Agent 的初学者还是已经了解 LangChain 但没系统梳理过 LangGraph 的开发者下面这一套内容都值得完整过一遍。1. LangChain LangGraph 核心能力速览在开始装依赖之前先建立整体印象。LangChain 和 LangGraph 不是替代关系而是不同抽象层级的配合关系实际项目中经常组合使用。能力项说明LangChain 定位大模型应用开发框架提供 Prompt 管理、模型调用封装、输出解析、RAG 组件、Agent 工具链等能力LangGraph 定位基于图状态机的大模型编排框架用于构建可控、可恢复、可审计的 Agent 工作流核心功能LCEL 表达式语言、RAG 检索增强、工具调用、多轮记忆、多节点图编排、人工介入节点、流式输出支持模型OpenAI 兼容接口、Claude、通义、DeepSeek、Ollama 本地模型等通过ChatOpenAI或对应适配器接入运行环境Python 3.10 以上建议新版本Windows / Linux / macOS 均可显存要求无需 GPU 也能学习调用本地模型时才需要考虑显存是否支持 API支持LangGraph 可部署成 LangGraph Server也可以自己用 FastAPI 封装服务是否支持批量任务支持可以在 Python 脚本中循环调用或结合消息队列处理并发请求典型场景企业知识库问答、客服工单处理、数据分析 Agent、多智能体协作、流程审批学习门槛需要 Python 基础、熟悉 Prompt 基本概念了解大模型 API 调用方式更佳从实际使用看最值得先理解的是两者的分工方式LangChain 负责“零件”LangGraph 负责“流程”。想快速搭一个原型LangChain 的chain足够一旦流程复杂到需要判断分支、多轮工具调用、错误恢复LangGraph 的图模型会明显更清晰。2. 适用场景与使用边界并不是所有 AI 应用都需要 Agent 框架。如果一个需求只是单纯问答直接调用大模型 API 就够了加入知识库检索后就需要 LangChain 的 RAG 组件当问题变成“根据用户提问自动查询多个数据源、调用多个工具、再汇总结论”时才真正轮到 Agent 编排上场。2.1 适合什么业务企业知识库问答用 LangChain 做文档加载、切片、向量化用 LangGraph 编排检索和生成状态。复杂任务分解把用户需求拆成多个子任务依次调用搜索引擎、数据库、代码执行器等工具。多智能体协作一个物流 Agent 负责订单查询一个售后 Agent 负责退款审批两个子 Agent 通过主 Graph 串联。流程审批与人工介入利用 LangGraph 的interrupt机制在关键节点停住等人工确认后再继续执行。2.2 不适合什么场景固定不变的简单提示词直接用prompt model就能解决使用框架反而增加复杂度。需要毫秒级响应的场景引入框架和 Agent 多轮调度会显著增加延迟对实时性要求极高的接口不建议用 Agent。大规模计算任务Agent 适合做“智能编排”不适合替代数据清洗和模型训练等重计算任务。涉及未授权数据的处理接入企业内部数据或用户个人信息时必须获得合规授权否则框架能力越强风险越大。另外凡是涉及生成内容、调用外部工具的场景都要注意安全边界。比如 Agent 调用代码执行器时要限制在沙箱环境调用数据库时要用只读账号或 SQL 白名单涉及人脸、声音、隐私数据的生成与处理必须有明确的授权流程。企业级 Agent 不是简单把接口接好而是数据权限、操作审计、模型输出的合规复核都要一起考虑。3. LangChain LangGraph 开发环境准备建议使用 Python 3.10 及以上版本Python 3.12 和 3.13 在多数 Linux/Windows 环境都能正常安装依赖。实际项目中常用conda或venv创建独立虚拟环境避免和系统 Python 冲突。3.1 基础环境检查清单Python 3.10 pip / conda 一个可调用的大模型 API Key或本地部署的 Ollama Chroma 或其他向量数据库做 RAG 时用 Git可选用于拉取示例代码如果你使用的是 OpenAI 兼容接口服务需要确认对应服务的网络访问是否正常。这一点容易在启动时报错后才想起来建议先单独调用一次 API 确认连通性。3.2 创建虚拟环境python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate不推荐直接在全局环境安装 LangChain 全家桶因为依赖数量多且版本更新频繁全局安装容易造成包冲突。3.3 安装 LangChain、LangGraph 和相关依赖pip install -U langchain langgraph langchain-core langchain-openai langchain-community pip install -U chromadb pip install -U fastapi uvicorn httpx需要说明的是LangChain 和 LangGraph 生态版本更新非常快按上述命令安装时拿到的是当前稳定版本。如果你学习时遇到 API 不一致优先查看当前版本的官方文档。3.4 配置模型密钥通过环境变量管理密钥不要把 Key 硬编码在代码里export OPENAI_API_KEYyour-api-key export OPENAI_BASE_URLhttps://api.example.com/v1如果你用的是本地模型也可以通过配置OPENAI_BASE_URL指向 Ollama 或 vLLM 地址从而用同一个ChatOpenAI接口完成调试。4. LangChain LangGraph 安装部署与启动方式很多初学者卡在最开始的“如何启动”。这里的启动分两种一种是直接在脚本里跑python xxx.py另一种是用langgraph dev启动可视化调试服务。两者对应不同阶段。4.1 直接运行 Python 脚本这是最基础的验证方式。下面是一个最小可运行的 LangChain LCEL 示例from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-4o-mini, temperature0.7 ) resp llm.invoke(用一句话介绍 LangGraph) print(resp.content)运行后如果控制台能输出结果说明依赖安装和 API 配置都没问题。4.2 使用 langgraph dev 启动开发模式把 Agent 逻辑写在项目目录的agent.py或其他 Python 模块里然后安装langgraph-clipip install -U langgraph-cli langgraph dev这个命令会启动 LangGraph 开发服务同时打开一个可视化交互页面可以看到图的节点、边、状态流转。对新手理解 Agent 内部流程尤其有帮助。需要注意的一点是langgraph dev和uvicorn app:app的启动方式不同。langgraph dev是 LangGraph 的专用开发调试模式会读取项目结构并自动生成服务适合本地查看图和调用流程而uvicorn app:app是直接把 FastAPI 应用跑起来适合把 Agent 封装成普通 HTTP 服务后集成到生产环境。两者并不是同一件事。4.3 构建最小 LangGraph 图LangGraph 的基本单元是节点节点之间通过边连接状态对象在图内流转from typing import Annotated, TypedDict from langgraph.graph import StateGraph, START, END from langgraph.graph.message import add_messages from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini) class AgentState(TypedDict): messages: Annotated[list, add_messages] def call_model(state: AgentState): resp llm.invoke(state[messages]) return {messages: [resp]} graph StateGraph(AgentState) graph.add_node(model, call_model) graph.add_edge(START, model) graph.add_edge(model, END) agent graph.compile()这个图虽然简单但已经具备了状态管理、节点执行和边连接的基本要素。后续加入工具调用、条件分支、记忆节点都基于同样的结构扩展。4.4 调用编译后的 Agentresult agent.invoke({messages: [{role: user, content: 你好介绍一下你自己}]}) print(result[messages][-1].content)如果这一步成功说明你的 LangGraph 工作流已经能跑通后面就可以在此基础上加工具、加检索、加记忆。5. LangChain LangGraph 功能测试与效果验证学习阶段不要贪多先把这些功能点逐个跑通。每个功能点请按照“输入 - 执行 - 判断结果”的方式验证。5.1 LangChain RAG 检索增强测试RAG 是企业 Agent 最常见的起点。原理不复杂先加载文档切成小段向量化后存入向量库用户提问时从向量库检索相关片段拼进 Prompt 再交给大模型。from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_chroma import Chroma from langchain_core.prompts import ChatPromptTemplate from langchain_core.runnables import RunnablePassthrough loader TextLoader(docs/company_manual.txt) documents loader.load() splitter RecursiveCharacterTextSplitter(chunk_size500, chunk_overlap50) docs splitter.split_documents(documents) embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vectorstore Chroma.from_documents(docs, embeddings) retriever vectorstore.as_retriever(search_kwargs{k: 4}) prompt ChatPromptTemplate.from_template( 基于以下资料回答问题如果资料中找不到答案就回答不知道。\n\n资料{context}\n\n问题{question} ) def format_docs(docs): return \n\n.join(doc.page_content for doc in docs) rag_chain ( {context: retriever | format_docs, question: RunnablePassthrough()} | prompt | ChatOpenAI(modelgpt-4o-mini) ) answer rag_chain.invoke(公司请假制度是什么) print(answer.content)判断标准很简单问题答案是否来自文档内容而不是模型“自由发挥”。如果模型回答出现了文档里根本没有的信息需要调整切片大小、重叠区间或检索 TopK 数量。5.2 Agent 工具调用测试工具调用是 Agent 区别于普通问答的关键。LangChain 通过装饰器定义工具再绑定到大模型from langchain_core.tools import tool from langchain_openai import ChatOpenAI tool def get_weather(city: str) - str: 根据城市名查询天气情况 return f{city}晴天温度 23℃适合出行 llm ChatOpenAI(modelgpt-4o-mini) llm_with_tools llm.bind_tools([get_weather]) resp llm_with_tools.invoke(上海今天天气怎么样) if resp.tool_calls: tool_call resp.tool_calls[0] result get_weather.invoke(tool_call[args]) print(工具调用结果:, result) else: print(未触发工具调用:, resp.content)验证重点有两个一是模型是否在应该调用工具的 prompt 下正确产生了tool_calls参数二是工具返回结果后是否能正确组合成最终答案。5.3 LangGraph 多节点工作流测试把工具调用放入 LangGraph 节点流程就变成“模型判断调用哪个工具 - 执行工具 - 回到模型生成答案”from typing import Annotated, TypedDict from langgraph.graph import StateGraph, START, END from langgraph.graph.message import add_messages from langchain_openai import ChatOpenAI from langchain_core.messages import ToolMessage llm ChatOpenAI(modelgpt-4o-mini) tools [get_weather] llm_with_tools llm.bind_tools(tools) class AgentState(TypedDict): messages: Annotated[list, add_messages] def should_continue(state: AgentState): last_message state[messages][-1] return tools if last_message.tool_calls else END def call_model(state: AgentState): return {messages: [llm_with_tools.invoke(state[messages])]} def call_tool(state: AgentState): tool_call state[messages][-1].tool_calls[0] result get_weather.invoke(tool_call[args]) return {messages: [ToolMessage(contentresult, tool_call_idtool_call[id])]} graph StateGraph(AgentState) graph.add_node(model, call_model) graph.add_node(tools, call_tool) graph.add_edge(START, model) graph.add_conditional_edges(model, should_continue, [tools, END]) graph.add_edge(tools, model) agent graph.compile()执行下面的代码观察整个流程是否在model - tools - model之间正确流转messages agent.invoke({messages: [{role: user, content: 北京今天天气怎么样}]}) for msg in messages[messages]: print(msg.type, -, msg.content)5.4 记忆与多轮对话测试企业级 Agent 必须具备上下文记忆否则每轮都是“身份证”。LangGraph 中可以通过add_messages保留整个消息列表也可以外接长短期记忆存储。常见做法是在状态中维护messages字段每次调用把所有历史消息传给模型。from langgraph.checkpoint.memory import MemorySaver memory MemorySaver() agent graph.compile(checkpointermemory) config {configurable: {thread_id: user-001}} agent.invoke({messages: [{role: user, content: 我叫小明}]}, config) agent.invoke({messages: [{role: user, content: 我叫什么名字}]}, config)如果第二次回答正确说出“小明”说明对话记忆生效。注意thread_id是区分不同会话的关键企业场景下可以用用户 ID、会话 ID 做隔离。5.5 LangGraph 可视化调试在项目目录下运行langgraph dev浏览器打开交互页面后左侧能看到整个图结构点击节点可以查看输入输出和状态变化。出现死循环或节点报错时可视化页面能帮你快速定位是哪一跳出了问题。6. LangChain LangGraph 接口 API 与批量任务Agent 最终要变成服务才能被业务系统调用。虽然 LangGraph 有官方服务化方案但直接用 FastAPI 封装编译好的 Agent 更直观也更容易集成到企业内部网关。6.1 用 FastAPI 封装 Agentfrom fastapi import FastAPI from pydantic import BaseModel from typing import List app FastAPI() class MessageItem(BaseModel): role: str content: str class ChatRequest(BaseModel): thread_id: str messages: List[MessageItem] class ChatResponse(BaseModel): reply: str app.post(/chat, response_modelChatResponse) def chat(req: ChatRequest): config {configurable: {thread_id: req.thread_id}} state {messages: [m.model_dump() for m in req.messages]} result agent.invoke(state, config) return ChatResponse(replyresult[messages][-1].content)启动服务uvicorn main:app --host 0.0.0.0 --port 80006.2 Python 请求示例import requests url http://127.0.0.1:8000/chat payload { thread_id: user-001, messages: [{role: user, content: 帮我查一下广州天气}] } resp requests.post(url, jsonpayload, timeout60) print(resp.json())6.3 curl 调用示例curl -X POST http://127.0.0.1:8000/chat \ -H Content-Type: application/json \ -d {thread_id:user-001,messages:[{role:user,content:广州天气怎么样}]}6.4 批量任务设计批量任务的核心不是简单 for 循环而是要考虑并发、限流和失败重试。常见做法是把任务 ID 丢进消息队列Worker 进程消费后调用 Agent再把结果写回数据库。import time import concurrent.futures questions [ 产品A的使用方法, 产品B的保修政策, 产品C的售后电话, ] def process(q: str): try: result agent.invoke({messages: [{role: user, content: q}]}) return q, result[messages][-1].content except Exception as e: return q, fERROR: {e} with concurrent.futures.ThreadPoolExecutor(max_workers4) as executor: results list(executor.map(process, questions)) for q, answer in results: print(q, -, answer[:80])这里给出的是一套通用批量示例。实际使用时需要注意并发太高可能触发模型服务限流建议根据模型服务的并发限制调整max_workers每条任务都要记录状态和日志失败任务自动进入重试队列。6.5 服务安全注意事项API 服务不要直接暴露到公网至少要加 API Key 或内部网关认证。thread_id要按用户隔离防止跨用户读历史。Agent 调用的外部工具权限要收敛数据库账号使用只读权限。对输出内容做审计日志记录入参、出参和耗时方便后续追溯。7. 资源占用与性能观察Agent 项目的性能瓶颈通常不在 GPU而在上下文长度、模型响应延迟和外部工具耗时。这是和图像生成类项目完全不同的观察维度。7.1 Token 消耗与成本控制Agent 每多一次工具调用就会把中间结果写进messages再次发给模型时历史消息全部都要计费。因此工具返回内容越大Token 消耗越大。建议做到三点工具返回结果做截断只保留关键字段。长时间会话定期做消息摘要压缩历史。模型选择按需分级普通问答用轻量模型复杂推理才切大模型。7.2 延迟拆解可以用简单的计时观察整体链路import time start time.perf_counter() result agent.invoke({messages: [{role: user, content: 查询北京天气}]}) elapsed time.perf_counter() - start print(f总耗时: {elapsed:.2f}s)如果耗时过高要拆开看模型响应花了多久、工具调用花了多久、向量检索花了多久。工具调用如果是 HTTP 请求通常要重点排查目标服务的响应时间。7.3 RAG 检索相关参数chunk_size过大检索结果可能包含太多无关内容过小则可能丢掉关键上下文。chunk_overlap用于保留段落衔接语义但不宜超过 chunk 的 20%。TopK越大Prompt 越长成本越高。建议从 3 到 5 开始测试。向量化模型的选择会影响检索质量切换模型后需要重新生成向量库。7.4 系统资源观察方法本地用nvidia-smi观察显存用htop观察 CPU 和内存。大部分 LangChain Agent 场景占用的是内存和网络带宽显存只有在本地加载大模型时才会有明显占用具体数字取决于模型规模和量化方式要以实际测试为准。8. LangChain LangGraph 常见问题与排查方法整理一些学习过程中最高频的问题方便你遇到报错时对照处理。问题现象可能原因排查方式解决方案ModuleNotFoundError: langchain未安装 langchain检查 pip listpip install -U langchainPydantic 校验报错依赖版本冲突查看完整报错堆栈升级或锁定 pydantic 版本建议先重装相关包API Key 无效环境变量未读取或 Key 错误打印环境变量检查确认.env是否正确加载重新 export模型调用超时网络不通或模型服务响应慢单独调用模型接口测试确认网络连通性增加 timeout 参数LangGraph 图一直死循环条件边判断逻辑错误打开可视化调试检查should_continue的返回是否总返回tools工具调用失败工具函数报错或参数解析失败打印 tool_call 参数单独调用工具方法测试检查参数类型和必填项多轮对话记不住未使用 checkpointer 或 thread_id 不一致检查调用配置使用MemorySaver并固定thread_idlanggraph dev页面打不开端口被占用查看启动日志更换端口或关闭占用进程uvicorn app:app与langgraph dev行为不一致两者启动方式和服务内容不同检查访问地址和路由开发调试用 langgraph dev线上服务用 uvicorn上下文超长被模型拒绝消息历史过多查看模型上下文限制做消息摘要或裁剪历史RAG 回答不准确切片或检索参数不合理打印检索片段查看相关性调整 chunk_size、overlap、TopK或换向量模型特别说明一下langgraph dev与uvicorn app:app的差异前者是 LangGraph 的专用开发模式内置可视化调试和热更新适合学习阶段和问题定位后者是标准 FastAPI 启动方式适合将 Agent 封装成普通 Web 服务部署到生产。如果你在langgraph dev中能运行但uvicorn app:app报错通常是应用对象路径或依赖初始化方式不同导致的检查 FastAPI 实例的导入路径即可。9. 企业级 Agent 最佳实践与使用建议课程的价值不只是教你写代码而是帮你建立工程化思维。以下几个习惯建议从第一个练习项目就开始养成。9.1 目录结构设计一个可维护的 Agent 项目建议按模块拆分不要把所有代码堆在一个main.py里agent_project/ ├── main.py # FastAPI 入口 ├── agent/ │ ├── graph.py # LangGraph 图定义 │ ├── nodes.py # 节点函数 │ ├── state.py # 状态定义 │ ├── tools/ # 工具函数 │ └── prompts.py # Prompt 管理 ├── services/ │ ├── memory.py # 记忆服务 │ └── retriever.py # 检索服务 ├── docs/ # 知识库原始文件 ├── tests/ # 测试用例 └── .env # 环境变量9.2 先跑小案例再扩规模不要第一步就设计十几个节点的超级工作流。建议先实现一个prompt - model - output的最小闭环再逐步加工具、加检索、加条件分支。每加一个节点就运行一次并确认输出正确。9.3 把可复用能力做成 SkillLangGraph 里怎么增加 Skill通用思路是把可复用的能力比如查天气、查库存、生成报表封装成独立工具或子图Agent 通过工具调用或子图节点复用这些 Skill。业务的决策逻辑留在主图里工具的实现细节下沉到 Skill 层这样后面对接新系统时不需要改动主流程。9.4 日志、评估与审计企业级环境里模型输出波动是常态。建议建立三层机制每次运行记录完整输入、中间步骤、输出和耗时。准备一组标准测试用例每次修改 Prompt、换模型或改图结构后跑一遍回归。对关键业务场景设置人工复核节点模型输出不直接触达用户。9.5 合规与权限控制企业级 Agent 涉及的数据通常比个人项目敏感得多。接入内部文档前确认文档脱敏工具调用需要保留审批记录涉及个人信息时遵循最小化原则模型输出对外发布前要有内容复核。Agent 如果连接到代码执行器、数据库或支付系统必须通过白名单、只读账号、沙箱等方式限制其权限边界。10. 从 0 到 1 的学习路线与项目进阶方向基于整套课程的内容组织建议按以下四个阶段推进每个阶段都有明确的验收标准。阶段一LangChain 基础掌握 LCEL 链式调用、Prompt 模板、输出解析器、模型调用封装。验收标准完成一个输入问题、检索知识库、输出格式化工单的 RAG 链路。阶段二Agent 核心机制掌握工具定义、工具调用、ToolMessage 回传、多轮工具调度。验收标准实现一个能自主调用两个以上工具并汇总答案的 Agent。阶段三LangGraph 工作流掌握 StateGraph、节点、边、条件分支、checkpointer 记忆、人工介入节点。验收标准实现一个带“查询 - 判断 - 工具调用 - 人工审批 - 输出”的完整流程。阶段四企业级工程化掌握 FastAPI 封装、批量任务、日志审计、测试与部署。验收标准将一个 Agent 服务部署到内部服务器接入业务系统并稳定运行。后续可以继续扩展的方向包括多智能体协作、长期记忆与向量记忆库、Agent 与知识图谱结合、自动评估与回归测试体系。如果对一个固定流程要求高可以对比 LangGraph 和传统工作流引擎的差异来理解各自的边界。最后提醒一句框架版本更新很快今天的写法到下一个版本可能就变了。学习的重点是理解“状态、节点、边、工具、记忆”这些底层概念而不是死记某个版本的 API这也是 LangGraph 相对其他 Agent 框架更有长期价值的原因。建议先把环境装好跑通最小案例再回头选自己业务里最值得 Agent 化的流程动手改造。难度不算低但从实际效果和可维护性来看值得投入。