企业官网建设流程全解析

这次我们来看一套覆盖LangChain + LangGraph 开发实战的完整课程。它的定位不是讲几个概念 Demo，而是从 0 基础一路做到企业级 Agent：LangChain负责把大模型、提示词、检索、工具调用串成可复用的链，LangGraph负责把这些链放进一个带状态、带分支、可恢复、支持人工审批的图里。

很多人在学 Agent 开发时会遇到同一个问题：看了一堆 LangChain 文档，还是会写成一个"死循环调 LLM"的脚本，一旦工具调用失败、上下文超长、流程需要分叉，代码就乱了。这套课程要解决的，就是这个问题。它带你把 Agent 从"能跑"做到"能上线"：状态怎么设计、节点怎么划分、工具怎么注册、RAG 怎么接、多 Agent 怎么分工、接口怎么暴露、批量任务怎么处理，全部按项目实战的方式走一遍。

如果你正准备入门 Agent 开发，或者已经在做内部工具但觉得当前架构不好扩展，这篇文章可以先收藏。下面我会把课程内容拆成学习路线，按"核心能力 → LangChain 和 LangGraph 的区别 → 环境准备 → 最小 Agent 实现 → 企业级实战 → API 与批量任务 → 资源观察 → 问题排查 → 最佳实践"的顺序展开，不会只有概念，每一步都有可执行的代码和验证方式。

1. LangChain + LangGraph 核心能力速览

先给一张总览表，把课程涉及的核心内容和学习收益看清楚。

注意一点：LangChain 和 LangGraph 本身是开源框架，不是某个固定版本的软件。2026 年的课程内容会更贴近当时的 SDK 版本，所以学习时一定要以官方最新文档为准，不要背旧版本的 API。课程里提到的langchain、langgraph包名和核心概念是稳定的，但参数名、默认行为可能随版本调整。

2. LangChain 和 LangGraph 到底有什么区别

这是整个课程最先要讲清楚的问题，也是实际开发中最容易混淆的地方。

LangChain 解决的是"串联"问题。

它把大模型使用过程中的固定环节抽象成组件：Prompt 模板、模型调用、输出解析、Memory、检索器、工具。你通过 Chain 把组件串起来，最典型的是LLMChain这种结构：用户输入 → 填充 Prompt → 调用模型 → 解析输出。它的好处是代码整洁、复用性高，适合流程相对固定的场景，比如简单的问答、摘要、关键词提取。

LangGraph 解决的是"状态和分支"问题。

真实业务不是一条直线跑到底。一个企业级 Agent 可能需要先判断要不要查数据库，再决定调用哪个工具，然后根据工具结果决定继续追问还是直接返回，甚至在写入数据之前插入一个人工审批节点。这种"带条件、带循环、带中断恢复"的流程，用 Chain 写会越来越难维护。LangGraph 把流程建模成图：节点是执行单元，边是流转方向，状态是全局共享的数据对象。每一步执行的结果都会更新状态，图引擎根据状态决定下一步走向。

举个例子：一个工单处理 Agent。LangChain 的写法可能是一个大 Chain 调用多个工具，逻辑写在 Prompt 里让模型"自己理解什么时候该做什么"。LangGraph 的写法则不同。

从实际项目看，LangChain 更像"工具箱"，LangGraph 更像"调度引擎"。两者不是替代关系，而是叠加关系：你用 LangChain 的组件处理具体任务，用 LangGraph 把组件组织成一个可控的 Agent 流程。

有一个热词是"LangGraph 代替 Flowable"。这里要说得准确一点：LangGraph 不是用来替代所有 BPM 流程引擎的。Flowable 这类引擎面向的是 BPMN 流程、人工任务、系统间集成，是成熟的业务流程中台。LangGraph 更擅长的是动态的、由大模型决定路径的编排。在企业落地里，常见做法是两者共存：Flowable 管正式的审批流，LangGraph 管 AI Agent 的推理和工具调用。课程里也会讲到这个边界，避免学员在没理解实际业务时就盲目换框架。

3. 0 基础入门 LangChain + LangGraph 学习路线

这套课程的核心是从 0 到 1，所以学习路径设计得很明确。按下面的阶段走，比直接翻文档效率高很多。

3.1 阶段一：LangChain 基础

这个阶段不碰 Agent，先把组件用熟。

• 学会创建 Prompt 模板，理解变量填充。
• 学会调用大模型，区分聊天模型和补全模型。
• 学会 Output Parser，把模型输出转成结构化数据。
• 学会 Memory，处理多轮对话上下文。
• 学会 Retriever，把文档检索结果拼进 Prompt。
• 学会 Tool 的基本写法，理解模型如何决定调用工具。

实践目标：写一个能根据用户问题检索本地文档并回答的问答脚本。

3.2 阶段二：Agent 核心概念

接下来进入 Agent 部分。

• 理解 Function Calling，模型不是"自己执行工具"，而是"输出一个调用意图"。
• 理解 Agent 循环：模型判断 → 调用工具 → 观察结果 → 继续判断。
• 理解 ReAct 模式的思路，行动和推理交替进行。
• 学会给工具写清晰描述，因为这直接影响模型选择工具的正确率。
• 学会限制工具调用次数，避免死循环。

实践目标：让 Agent 具备搜索和计算能力，能回答需要查数据的问题。

3.3 阶段三：LangGraph 状态化编排

这是课程从入门到进阶的关键分水岭。

• 学习 State 的定义方式，理解 TypedDict 和消息列表。
• 学习add_node、add_edge、set_entry_point、set_finish_point。
• 学习条件边add_conditional_edges，让流程自己选择走向。
• 学习 Checkpoint 持久化，让 Agent 中断后能恢复。
• 学习如何在哪里设置断点，实现人工审批。

实践目标：把阶段二的 Agent 改造成一个可暂停、可恢复的 LangGraph 应用。

3.4 阶段四：企业级实战

最后是把项目做成能上线的状态。

• 接入 RAG，企业文档较多时先检索再生成。
• 设计多级工具，比如先查订单中心，再查库存系统。
• 设计多 Agent 协作，一个负责理解问题，一个负责工具调用，一个负责结果校验。
• 加入日志、追踪、异常处理。
• 通过 API 暴露服务，接入批量任务。

实践目标：交付一个带接口、带日志、能处理真实业务数据的企业级 Agent 原型。

4. 本地环境准备与安装

在实际开发之前，先把环境整理干净。下面是通用的本地开发环境准备流程，具体版本以官方文档为准。

4.1 环境要求

• 操作系统：Windows 10/11、macOS、Linux 都可以。
• Python 版本：建议使用当前稳定版，例如 Python 3.10 及以上。
• 包管理工具：推荐uv或pip，用uv会更快也更方便管理虚拟环境。
• 大模型访问方式：可以配置 OpenAI 兼容接口的 API Key，也可以使用本地模型服务如 Ollama。

如果你是纯本地学习，建议准备一个支持大模型推理的显卡；如果没有独立显卡，也可以先用本地小模型或云 API，课程里的业务逻辑部分不依赖特定显卡型号。

4.2 创建虚拟环境并安装依赖

使用uv的方式如下：

uv venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate

安装核心依赖：

uv pip install langchain langgraph

如果你需要接入本地模型、文档解析、向量数据库，按需安装对应包。需要注意，不同版本的langchain和langgraph对 Python 版本有要求，安装前先看pyproject.toml或官方文档。

4.3 配置模型访问

推荐把密钥放环境变量里，不要写死在代码中。

export OPENAI_API_KEY="your-api-key"

如果使用本地模型，设置OPENAI_API_BASE指向本地服务地址，具体变量名以所用模型服务为准。

4.4 了解两种启动方式

课程里有一个重点细节：uv run uvicorn app和uv run langgraph dev的区别。

# 方式一：普通 FastAPI 启动 uv run uvicorn app:app --host 127.0.0.1 --port 8000 # 方式二：LangGraph 开发服务器 uv run langgraph dev

区别在于：uvicorn只是把 FastAPI 应用启动起来，它不会自动启用 LangGraph 的状态检查点、调试面板和持久化能力；langgraph dev是 LangGraph 官方开发服务器，它会启动一个带持久化存储和实时追踪的本地服务，适合开发调试。生产环境通常是把它封装成普通 API 服务，再按实际需要配置持久化存储。

5. 写一个最小可运行的 LangGraph Agent

下面我们写一个最简的 LangGraph Agent，目标不是功能强大，而是让你看清一个图结构 Agent 的最小骨架。

from typing import TypedDict from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI class AgentState(TypedDict): """全局状态对象""" messages: list def call_model(state: AgentState) -> AgentState: """调用大模型，把回复追加到消息列表""" llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) reply = llm.invoke(state["messages"]) return {"messages": [reply]} # 1. 创建图 graph = StateGraph(AgentState) # 2. 添加节点 graph.add_node("agent", call_model) # 3. 设置入口和出口 graph.set_entry_point("agent") graph.add_edge("agent", END) # 4. 编译 app = graph.compile()

运行它：

result = app.invoke({"messages": [{"role": "user", "content": "你好，请介绍一下你自己"}]}) print(result["messages"][-1].content)

这个示例的预期结果是模型正常回复，消息列表里多了一条 assistant 消息。

这个最小图只有一个节点，看起来和直接调用模型差不多，但它已经具备 LangGraph 的核心特征：状态显式存在、节点是可插拔的、流程由边来控制。后面加工具、加分叉、加人工审批，都是在这个骨架之上扩展。

失败排查的思路也很固定：没有回复，先看OPENAI_API_KEY是否配置；报模型不存在，换成你实际可用的模型名；返回异常，检查messages结构是否符合聊天模型要求。

6. 企业级 Agent 的完整链路

课程的项目实战部分会按真实业务拆解，下面是几个核心模块的实现思路和测试方法。

6.1 接入 RAG 文档检索

企业级 Agent 最常见的一个需求是回答内部知识库问题。不能把全部文档都塞进 Prompt，正确做法是检索后拼接。

from langchain_community.vectorstores import FAISS from langchain_openai import OpenAIEmbeddings # 假设已经准备好了向量库 vectorstore = FAISS.load_local("kb_index", OpenAIEmbeddings()) retriever = vectorstore.as_retriever(search_kwargs={"k": 4})

在 LangGraph 中，检索通常是一个独立节点：先根据用户问题检索相关文档，再把文档内容写入状态，下一个节点负责拼接 Prompt 并生成回答。

测试步骤：

1. 输入一个文档中已有的问题。
2. 观察检索结果是否和问题相关。
3. 继续追问一个文档之外的问题，验证 Agent 是否诚实说"不知道"。

预期结果是：文档内问题回答准确，文档外问题不编造。如果回答与文档无关，说明检索结果质量低，优先检查切分方式和向量库索引。

6.2 让 LangGraph 增加 Tool

"LangGraph 怎么增加 skill" 这个问题，在实际课程里对应的是给 Agent 注册工具。LangGraph 本身没有独立的 skill 概念，而是通过 LangChain 的 Tool 机制扩展能力。

from langchain.tools import tool @tool def get_order_status(order_id: str) -> str: """根据订单号查询订单状态，参数为订单号字符串。""" # 这里替换成真实接口调用 return "订单已发货"

然后在 LangGraph 节点里让模型决定是否调用这个工具。核心注意点有两个：

1. 工具描述必须写清楚什么时候用、参数是什么。
2. 工具函数要注意异常处理，不要随便抛错。

验证方法：输入一个包含订单号的问题，观察模型是否调用工具，以及返回的状态是否正确。如果模型一直不调用工具，检查工具描述和 Prompt 是否足够明确。

6.3 多 Agent 协作

复杂项目里，单个 Agent 往往什么都做不好。课程会把任务拆给多个子 Agent。

• 入口 Agent：负责理解用户意图，判断任务类型。
• 知识库 Agent：负责检索文档。
• 业务查询 Agent：负责调用订单、库存、客户等系统接口。
• 校验 Agent：负责对最终结果做一致性检查。

在 LangGraph 里，一个 Agent 也可以是另一个图的一个节点。这样写的最大好处是每个子 Agent 可以独立调试。

测试时，给一个需要多个系统配合的问题，观察流程是否正确跳转到对应 Agent，以及最终输出是否完整。失败时优先看每个子 Agent 的状态输出，定位是意图识别错误，还是接口调用错误。

6.4 人工审批与流程中断

企业环境中，不是所有操作都允许 Agent 自动执行。比如修改订单、发送合同、创建账号，这些动作应该停下来等人确认。

LangGraph 支持通过interrupt或者检查点机制实现人工介入。思路是：图执行到关键节点之前暂停，保存当前状态；人工审批通过后，从暂停位置继续执行。

config = {"configurable": {"thread_id": "order-001"}} # 第一次请求，流程会在审批节点前暂停 result = app.invoke({"messages": [...]}, config=config) # 人工审批通过后，继续执行 result = app.invoke(None, config=config)

验证方法：

1. 第一次调用后，观察流程是否在预期位置停止。
2. 检查状态是否被保存，没有因为中断而丢失。
3. 第二次调用后，流程是否从断点继续，而不是重新开始。

这个能力是企业级 Agent 区别于玩具 Demo 的关键。课程里会用实际项目演示审批节点的配置和前端交互方式。

7. 接口 API 与批量任务

企业级 Agent 不能只在终端跑，必须暴露成服务，让别人可以调用。LangGraph 应用本身是基于 FastAPI 的，所以可以用langgraph dev或者自定义app.py启动服务。

7.1 启动服务

uv run langgraph dev

启动后，本地会有一个 API 地址，同时附带一个可视化调试页面。也可以自定义 FastAPI：

from fastapi import FastAPI from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, END from typing import TypedDict app = FastAPI() class State(TypedDict): question: str answer: str def generate(state: State) -> State: llm = ChatOpenAI(model="gpt-4o-mini") answer = llm.invoke(state["question"]) return {"answer": answer.content} graph = StateGraph(State) graph.add_node("generate", generate) graph.set_entry_point("generate") graph.add_edge("generate", END) agent_app = graph.compile() # 包装成 HTTP 接口，字段按实际项目调整

7.2 通过 curl 调用

curl -X POST "http://127.0.0.1:8000/agent" \ -H "Content-Type: application/json" \ -d '{"question": "请帮我查询订单号 20260001 的状态"}'

7.3 通过 Python 调用

import requests url = "http://127.0.0.1:8000/agent" payload = {"question": "请帮我查询订单号 20260001 的状态"} response = requests.post(url, json=payload, timeout=120) print(response.json())

注意，上面的请求路径和字段是通用示例，每个项目的接口定义不同，需要按课程项目实际代码调整。

7.4 批量任务设计

处理批量任务时，不要直接开多个线程去并发跑同一个图，那样很容易把 API 打爆，也不方便控制失败重试。建议做法是引入一个任务队列。

import time from queue import Queue from threading import Thread def worker(graph, task_queue): while True: item = task_queue.get() if item is None: break task_id, payload = item try: result = graph.invoke(payload) print(f"task {task_id} done: {result}") except Exception as exc: print(f"task {task_id} failed: {exc}") finally: task_queue.task_done()

验证批量任务的三个指标：

1. 所有任务是否都有输出结果。
2. 单个任务失败是否影响其他任务。
3. 任务失败后日志里能否看到明确原因。

批量任务最容易出现的坑是状态共享。thread_id配置不当会导致不同任务的上下文串掉，这一点课程里会特别强调。

8. 资源占用与性能观察

Agent 项目的资源占用比普通脚本高，主要消耗在三个地方：

1. 大模型推理。
2. 向量检索。
3. 状态存储和日志记录。

如果在本地用 GPU 跑模型，建议先观察显存占用。观察方式很简单：启动服务后，在另一个终端运行nvidia-smi查看显存。如果换用本地大模型，模型参数量越大，显存占用越高，具体数值取决于模型版本、量化方式和上下文长度。

影响性能的关键因素包括：

• 上下文长度：多轮对话或多次工具调用会让上下文越来越长。
• 工具调用轮数：Agent 每调用一次工具就要多一次模型推理。
• 并发数：同时处理的用户请求越多，资源占用越高。
• 检索数量：RAG 检索的文档块越多，拼接后的 Prompt 越长。

如果发现响应变慢或者显存不足，优先尝试：

• 换更小的模型。
• 限制最大工具调用轮数。
• 对 Prompt 做裁剪或摘要。
• 使用批量推理或缓存。

另外，不要把nvidia-smi的显存数值理解为"这个 Agent 固定占多少"。"整个 Agent 的显存=模型权重 + 并行请求数 x 单请求上下文开销"，所以并发越高，显存波动越大。

9. 常见问题与排查方法

下面的排查表都是从实际开发中总结出来的，建议保存一份。

这里重点说一下 "agent execution terminated due to error"。这是 Agent 开发最常见的报错之一。初学者看到这个错误会以为是 LangGraph 本身的问题，实际上通常是某个节点内部抛了异常：工具函数没处理网络错误、模型 API 返回了非预期格式、条件边返回了不存在的分支名。排查时不要只看最外层错误，要用traceback.format_exc()把完整堆栈打出来，定位到具体节点。

另一个常见问题是 LangGraph 版本升级后的 API 变化。很多旧代码中的参数在新版本里被改名或移除，所以遇到奇怪的报错先看官方更新日志。

10. 最佳实践与合规使用

课程最后会讲工程化落地。我整理几条通用建议，做 Agent 项目时大部分都能用上。

10.1 开发习惯

先小参数跑通，再上复杂业务。第一次实现只做单节点，然后逐步增加工具和分支。保留一个最小可运行配置，出问题时第一时间回退。

建议项目目录这样组织：

agent-project/ ├── app.py ├── graph.py ├── tools/ │ └── order_tool.py ├── state.py ├── prompts/ ├── logs/ ├── inputs/ └── outputs/

10.2 稳定性设计

所有工具调用都要加超时和异常捕获。批量任务要有日志、失败重试和结果落盘。接口服务要做访问限制，不能裸奔开放到公网。涉及用户数据的接口，还需要做权限校验和数据隔离。

Agent 是概率系统，哪怕 Prompt 写得再好，也可能在某条输入上表现异常。生产环境必须保留人工复核通道，尤其是写操作类任务。

10.3 合规与版权

开发 Agent 时要注意几个底线：

• 接入第三方系统前确认接口调用权限。
• 涉及客户隐私信息时，做脱敏处理。
• RAG 知识库只使用有权限使用的文档。
• 不要用 Agent 自动执行高风险操作，比如转账、发合同、删数据。
• 大模型生成内容需要人工审核，避免错误信息直接触达用户。

课程里的企业级项目都会演示如何在代码中处理这些边界，比如在审批节点停留，或者给 Agent 加一条"无法确认时拒绝回答"的规则。

11. 总结

这套 LangChain + LangGraph 开发实战课程最值得尝试的点，是它把 Agent 开发从"搭 Demo"拉到了"做项目"的层面：你会看清 LangChain 和 LangGraph 各自负责什么，会自己写出第一个图结构 Agent，也会完成 RAG、Tool、多 Agent、人工审批、API 暴露和批量任务这一整条链路。

建议第一个验证的功能就是"最小 LangGraph Agent 跑通"。如果状态、节点、边这三件事还没形成直觉，先不要急着上多 Agent 和审批流程，否则会浪费大量时间在调试复杂流程上。

最容易踩的坑是两个。一是把 LangGraph 当成普通函数调用库，不理解状态的作用，导致节点之间数据传不通；二是不做资源控制，让 Agent 无限循环调用工具，最后耗尽上下文和预算。只要避开这两个坑，后面的学习会顺畅很多。

后续可以继续扩展的方向包括：把 LangGraph 和已有业务流程引擎配合使用、接入更丰富的向量库、尝试多模态 Agent，以及把本地小模型作为 Agent 的推理引擎。这些方向都很适合从课程项目里长出来。建议收藏这份学习路线，动手的时候按章节对照练习。