企业官网建设流程全解析

这次我们来看 2026 年企业级 AI Agent 开发绕不开的一条技术主线：LangChain 1.x + LangGraph。标题里的 V1.3 可以理解为课程或文档体系中的版本口径，实际动手时你装到的多半是当前 1.x 最新稳定版，所以这篇文章不纠结具体补丁号，直接按生态里最主流的 API 用法来讲。看完之后，你会发现多智能体架构并不神秘，核心就几件事：状态怎么维护、节点怎么编排、分支和循环怎么控制、结果怎么持久化。

LangChain 解决的是“零件”问题：模型接入、提示词、工具、RAG、输出解析；LangGraph 解决的是“生产线”问题：状态管理、节点编排、条件路由、多智能体协作、人机协同和持久化。两者配合，正好覆盖了从单次模型调用到复杂 Agent 系统的完整开发链路。比起过去自己用while True写 Agent 循环，LangGraph 提供了更规范、更容易上生产的执行框架。

这篇文章会带你完成：确认技术栈分工、搭好本地环境、跑一个最小 LangGraph Agent、用多智能体模式做流程编排、接入工具调用、完成 API 化部署和批量任务，最后给出一份排错清单和工程化建议。适合后端工程师、AI 应用开发者，以及准备把 Agent 真正放进业务系统的技术团队。

1. 核心能力速览

先把这组技术栈的关键信息放在最前面，方便你快速判断值不值得投入时间。

有一点需要提前说明：Agent 开发的主要资源瓶颈不是显卡，而是 token 消耗、接口延迟和状态存储。很多人被“大模型必须大显存”这个印象误导，实际上如果你的模型走 API 调用，本地开发和测试用一台普通电脑完全够用。真正需要显卡的是本地部署模型场景，那是另一条技术路线。

版本选择上，我的建议是直接安装langchain和langgraph的最新稳定版，不要为了教程去锁定老旧版本。1.x 发布之后，很多 0.x 时代的手写 Chain 模式已经不建议使用，官方更推荐直接把图结构写到 LangGraph 里。

2. LangChain 与 LangGraph 的分工：别再混淆

很多初学者第一个问题就是：LangChain 和 LangGraph 到底什么关系？是不是学了 LangChain 就不用学 LangGraph？

不是。两者是分工关系，不是替代关系。

LangChain 更像是“工具箱”，它把模型调用、提示词模板、文档加载、向量检索、工具定义、输出解析这些能力统一封装成标准接口。你可以只学 LangChain 就做一个简单的 RAG 问答，但如果要做带状态的 Agent、多智能体协作、循环和人工介入，LangChain 0.x 时代那种 Chain 串联方式会非常吃力。

LangGraph 是 LangChain 团队推出的“图执行引擎”。它把 Agent 流程建模成一张有向图：节点是业务步骤，边是步骤之间的流转，状态在整张图上共享。它原生支持循环、分支、条件跳转、断点续跑，还内置了 checkpoint 机制，可以把每次执行状态保存下来。这正好补上了 LangChain 在复杂编排上的短板。

从材料看，LangGraph 1.0 之后已经不只是 Agent 框架，更像一个轻量级的 AI 应用运行时。生产级应用里常见的并发控制、断点恢复、人工审批等需求，LangGraph 都提供了对应机制，这也是它能够进入企业级项目的原因。

有人会问：LangGraph 能不能替代 Flowable 这类工作流引擎？我的判断是“部分可以”。LangGraph 擅长 AI 编排，比如多 Agent 协作、RAG 流程、动态路由；Flowable 擅长的是严格的 BPM 审批流。如果业务流程需要强合规审计和成熟的审批节点，不建议为了技术新鲜感直接替换成熟工作流引擎。两者结合使用，反而更符合企业现状。

3. 2026 年企业级 AI Agent 开发环境准备

在写代码之前，先把环境准备好。这里给出一套通用的本地开发环境搭建流程，按你自己的系统情况调整即可。

3.1 Python 与虚拟环境

LangChain 和 LangGraph 都是 Python 生态，建议使用 Python 3.9 及以上版本，最好在虚拟环境里安装，避免和系统 Python 包冲突。

python -m venv langchain-demo # Windows langchain-demo\Scripts\activate # macOS / Linux source langchain-demo/bin/activate python -m pip install -U pip

3.2 安装核心依赖

接下来安装 LangChain 生态的核心包：

pip install -U langchain langchain-openai langchain-community langgraph pip install -U langchainhub python-dotenv

安装完成后，可以检查一下版本，确认环境可用：

python -c "import langchain, langgraph; print('langchain:', langchain.__version__); print('langgraph:', langgraph.__version__)"

如果你的项目要用到向量库，再额外安装 Chroma、FAISS 或对应的数据库驱动。用不到就先不装，保持环境干净。

3.3 模型 API Key 配置

LangChain 通过环境变量读取模型凭据。最常用的做法是在项目根目录创建.env文件，然后用dotenv加载：

OPENAI_API_KEY=sk-xxxxxxx

如果你用的是国内模型服务或 OpenAI 兼容端点，可以通过base_url参数切换，不必修改业务代码：

from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="gpt-4o-mini", temperature=0, base_url="https://api.example.com/v1", api_key="sk-xxxxxxx", )

这里需要注意：模型名称要和你的服务商提供的名称一致，否则启动时就会报模型不存在、认证失败之类的错误。建议先单独测试一次模型调用，排除网络和 Key 的问题，再进入 Agent 开发。

4. LangChain 核心组件拆解：模型、提示词、工具、RAG、记忆、输出解析

LangChain 的价值不在“调模型”，而在把模型周边的工程问题标准化。下面这六个组件，是大多数 Agent 系统都会用到的。

4.1 模型接入

模型层是 Agent 的“大脑”。LangChain 用统一的ChatModel接口屏蔽了不同厂商的差异：

from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="gpt-4o-mini", temperature=0, )

需要本地模型时，可以用 Ollama 配合langchain-ollama接入。模型选择和 Agent 的复杂性没有直接关系，业务路由逻辑再复杂，底层模型也可以只用一个。不要为了做 Agent 就到处接模型，模型调用成本是逐次累加的。

4.2 提示词模板

Agent 里的提示词往往是动态拼装的。LangChain 提供了ChatPromptTemplate，可以结构化组织 system prompt 和 user prompt：

from langchain_core.prompts import ChatPromptTemplate prompt = ChatPromptTemplate.from_messages([ ("system", "你是一名企业级 AI Agent 技术顾问，回答要简洁、可落地。"), ("human", "请解释 {topic} 的实现思路，并给出关键代码片段。"), ]) chain = prompt | llm resp = chain.invoke({"topic": "多智能体 Supervisor 模式"}) print(resp.content)

实际项目里，提示词不要写在代码里硬编码，建议独立成配置文件或模板文件，方便运营人员调整。提示词的版本管理，直接影响 Agent 线上效果的稳定性。

4.3 工具封装

Agent 要发挥作用，必须能调用工具。LangChain 用@tool装饰器把普通函数变成模型可调用的工具：

from langchain_core.tools import tool @tool def query_stock_price(code: str) -> str: """查询指定股票代码的最新价格。code 为 6 位股票代码。""" return f"{code} 最新价 12.30 元"

工具的描述信息非常重要，底层模型依赖描述来判断“什么场景该用这个工具”。描述写得含糊，模型就可能乱调用。生产环境里，建议给每个工具加上清晰入参说明、超时时间、错误返回格式。

4.4 RAG 检索

RAG 是企业落地 Agent 最高频的需求。LangChain 把文档加载、切分、向量化、检索串成一条标准流水线：

from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_community.vectorstores import FAISS from langchain_openai import OpenAIEmbeddings loader = TextLoader("./docs/knowledge.txt") documents = loader.load() splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50) chunks = splitter.split_documents(documents) vectorstore = FAISS.from_documents(chunks, OpenAIEmbeddings()) retriever = vectorstore.as_retriever(search_kwargs={"k": 4})

很多人把 RAG 理解成简单的“把文档灌进向量库”，实际工程里难点在切分策略、召回率、引用溯源和知识更新。这里只演示基础接入，正式项目需要结合检索评测持续优化。

4.5 记忆与状态

0.x 时代的 LangChain Memory 类在新架构里逐渐边缘化。官方更推荐把对话历史直接放进 LangGraph 的 State 中管理。这不仅是实现方式的改变，更是思维方式的改变：记忆不再是 Agent 内部的黑盒，而是整个执行图可见的状态数据。

4.6 输出解析

结构化输出是 Agent 对接业务系统的关键。用PydanticOutputParser或with_structured_output可以直接让模型输出 JSON 结构，避免在业务代码里做脆弱的字符串解析。

5. LangGraph 核心概念与最小可跑 Agent

LangGraph 的核心概念只有几个：State、Node、Edge、Conditional Edge、Checkpointer。把这几个概念理解透，多智能体架构就是搭积木。

5.1 核心概念

State 是整张图的“全局变量”。LangGraph 允许你定义 State 的数据结构，并指定 Reducer 来处理状态更新。最常用的 reducer 是add_messages，它的作用是：当多个节点返回消息时，自动拼接而不是覆盖。

Node 是一个普通的 Python 函数，输入是当前 State，输出是一个字典，表示要更新的字段。Edge 表示节点之间的流转路径。Conditional Edge 是条件边，根据当前 State 动态决定下一步走向哪个节点。

Checkpointer 负责保存每一步的执行状态。开启后，图可以在任意节点暂停、恢复，这就为人工审批、断点调试、失败重跑提供了基础能力。

5.2 最小可跑 LangGraph Agent

下面这个例子，是一个最简单但完整的有状态对话 Agent：

from typing import Annotated, TypedDict from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, START, END from langgraph.graph.message import add_messages llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) class ChatState(TypedDict): messages: Annotated[list, add_messages] def chatbot(state: ChatState): response = llm.invoke(state["messages"]) return {"messages": [response]} graph = StateGraph(ChatState) graph.add_node("chatbot", chatbot) graph.add_edge(START, "chatbot") graph.add_edge("chatbot", END) app = graph.compile() result = app.invoke({ "messages": [{"role": "user", "content": "你好，介绍一下你自己"}] }) print(result["messages"][-1].content)

这个例子看起来简单，但它包含了 LangGraph 的完整骨架：定义了 State，注册了节点，画了边，编译成图，最后调用执行。后续多智能体架构，只是在这个骨架上增加更多节点和更复杂的路由逻辑。

5.3 启动本地开发服务

如果你想在本地打开一个可视化调试环境，LangGraph 提供了langgraph dev命令：

pip install -U langgraph-cli # 在项目目录下启动 langgraph dev

如果项目用 uv 管理依赖，也可以用uv run langgraph dev。启动后，根据命令行输出的地址访问本地开发 UI，就能看到图结构、State 变化流和每一步的输入输出。这个调试体验，比在 Jupyter 里反复打印结果要直观得多。

6. 多智能体架构模式与代码实战

多智能体架构听起来很高端，本质上解决的是一个工程问题：当一个任务超过单个模型单次推理能力，或者需要多个角色协作时，如何把任务拆解、分配、汇总。LangGraph 提供了图级别的表达力，可以天然实现多种多智能体模式。

6.1 常见多智能体模式

第一类是顺序执行模式，Agent 之间按固定顺序串联，前一个输出作为后一个输入。适合流水线任务，比如资料收集、内容生成、人工审核。第二类是监督者模式，也叫 Supervisor，由中央调度节点决定下一步交给哪个子 Agent。适合任务动态变化、需要自主路由的场景。第三类是层级模式，多个 Supervisor 再向上汇总到一个总控节点，适合大型组织架构模拟。第四类是协作模式，多个 Agent 共享同一个任务池，通过共享状态互相传递中间结果。

选择模式的依据不是“哪个更高级”，而是“哪个更稳”。大多数企业项目从顺序模式开始，只有路由逻辑足够复杂时才引入 Supervisor。

6.2 代码实战：两阶段多智能体条件路由

这里给出一个可运行的两阶段例子：研究节点产出初稿，评审节点判断是否通过，不通过就回到研究节点重写，通过后进入终稿节点。这个结构在很多内容生成型 Agent 里非常典型：

from typing import TypedDict from langgraph.graph import StateGraph, START, END class ReportState(TypedDict): topic: str draft: str passed: bool def research_node(state: ReportState): return {"draft": f"《{state['topic']}》研究报告初稿：市场规模与应用现状。"} def review_node(state: ReportState): # 真实项目里由模型或人工判断，这里用长度做演示 return {"passed": len(state["draft"]) >= 20} def finalize_node(state: ReportState): return {"draft": state["draft"] + "（已终审）"} def route_after_review(state: ReportState): if state["passed"]: return "finalize" return "research" graph = StateGraph(ReportState) graph.add_node("research", research_node) graph.add_node("review", review_node) graph.add_node("finalize", finalize_node) graph.add_edge(START, "research") graph.add_edge("research", "review") graph.add_conditional_edges( "review", route_after_review, {"finalize": "finalize", "research": "research"} ) graph.add_edge("finalize", END) app = graph.compile() result = app.invoke({ "topic": "AI Agent 在企业服务中的应用", "draft": "", "passed": False, }) print(result["draft"])

这里最关键的是add_conditional_edges：它能根据route_after_review的返回值决定下一步走向。循环、重试、回退这些逻辑，都是通过条件边实现的。理解了这一点，多智能体架构的骨架就打通了。

6.3 Supervisor 监督者模式实现思路

监督者模式是生产环境里讨论最多的多智能体架构。它的核心是：一个 supervisor 节点接收所有子 Agent 的返回结果，再决定下一步执行谁。LangGraph 的Command类型就是为这种场景设计的，可以在节点返回时直接指定下一个节点：

from langgraph.types import Command def supervisor(state) -> Command: # 生产环境用 LLM 路由，这里演示固定跳转 return Command( goto="researcher", update={"messages": state["messages"] + ["已调度 researcher"]} )

完整实现还需要一个路由用的 LLM，让它从研究员、写手、代码工程师等成员中选择下一步执行者，并确保在任务完成时跳转到 END。实际项目里，为了避免 Supervisor 陷入无限循环，一定要在 State 里维护任务轮次或完成标记，并在条件路由中加上退出条件。

6.4 代码实战：多工具 ReAct Agent

如果不希望维护复杂图结构，又想要多角色协作效果，可以把多个“角色工具”挂到一个 ReAct Agent 下。底层模型负责判断何时使用哪个工具，LangGraph 的create_react_agent帮我们封装了循环逻辑：

from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langgraph.prebuilt import create_react_agent @tool def research_tool(query: str) -> str: """检索行业资料并返回摘要，适合研究类问题。""" return f"资料摘要：{query} 行业规模约 120 亿元。" @tool def coding_tool(requirement: str) -> str: """生成 Python 代码片段，适合编程类需求。""" return f"代码：def solution():\n return '{requirement}'" llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) agent = create_react_agent(llm, tools=[research_tool, coding_tool]) result = agent.invoke({ "messages": [{"role": "user", "content": "先查 AI Agent 市场规模，再写一个输出该数字的 Python 函数"}] }) print(result["messages"][-1].content)

运行后，模型会在一次对话中自动完成多轮工具调用：先查资料，再写代码，最后汇总结果。这种模式实现成本低，适合快速验证业务逻辑。但要注意：工具数量过多时，模型可能选错工具，需要对工具描述和模型参数做针对性调优。

7. 接口 API 与批量任务

Agent 写出来最终要服务上层业务。LangGraph 生态提供了把图服务化部署的方案，所有节点状态、运行记录、断点恢复都会通过 API 暴露出来。

7.1 API 服务启动

本地开发阶段，用langgraph dev启动的不只是调试 UI，同时也是一个本地 API 服务。生产环境可以用 LangGraph Server 或 LangGraph Platform 部署。启动之后，你会在命令行看到服务地址，常见的调用端口是 2024，具体以你启动时的输出为准。

7.2 Python 调用 API 示例

假设服务已经启动，可以通过 REST API 创建会话并发起运行：

import requests BASE_URL = "http://localhost:2024" thread_id = "demo-thread-001" resp = requests.post( f"{BASE_URL}/threads/{thread_id}/runs", json={ "assistant_id": "agent", "input": { "messages": [{"role": "user", "content": "运行一次测试任务"}] }, }, timeout=120, ) print(resp.status_code) print(resp.json())

这是 LangGraph Server 的常见调用格式，不同版本可能略有差异，以你实际使用的 SDK 方法和接口文档为准。接口方式的好处是，上层可以用任何语言接入，Java、Go、Node.js 都能通过 HTTP 调用。

7.3 批量任务实现

批量任务最常见的做法是并发调用已编译好的图，或者并发调用 API 服务。这里给出一个 Python 线程池模板：

from concurrent.futures import ThreadPoolExecutor tasks = ["任务 1", "任务 2", "任务 3", "任务 4"] def run_task(text: str): result = app.invoke({ "messages": [{"role": "user", "content": text}], }) return result["messages"][-1].content with ThreadPoolExecutor(max_workers=4) as executor: outputs = list(executor.map(run_task, tasks)) for text, output in zip(tasks, outputs): print(f"{text} => {output}")

批量任务有两个坑。第一，并发数不要盲目调大，要同时关注模型 API 的限流策略和下游服务承受能力。第二，每个任务最好绑定一个独立的 thread_id，方便出问题时定位日志和恢复执行状态。任务量大时，建议引入消息队列，把任务状态、重试次数和最终结果都持久化。

8. 资源占用与性能观察

Agent 系统的性能观察，重点不在显存，而在 token、延迟、步数和持久化存储。

每次运行 Agent，你至少要记录四类指标。第一是 token 消耗，多智能体协作会成倍放大 token 开销，因为每个子 Agent 都要看到上下文。第二是运行步数，一个正常 Agent 任务通常在 3 到 10 个 step 内完成，如果超过 20 步还没有收敛，大概率是路由逻辑或提示词有问题。第三是接口延迟，模型 API 调用是最大耗时来源，工具调用和向量检索相对可控。第四是状态存储增长，checkpoint 会记录每一步的 State，长时间运行后存储量不可忽视。

LangGraph 的stream方法可以逐步观察执行过程，定位瓶颈节点：

for step in app.stream({ "messages": [{"role": "user", "content": "逐步处理这个任务"}] }): print(step)

如果 Agent 跑到某个节点长期没有输出，优先看是不是卡在模型调用超时，再检查工具的远程接口是否返回了异常。

资源调优方面，先降低上下文冗余，系统提示词不要重复堆叠；再引入模型缓存，相同语义的查询直接命中缓存；最后做任务路由，简单问题走小模型，复杂问题才走大模型，这是企业里最直接的成本优化手段。本地模型方案则重点观察显存和内存，模型越大，需要预留的空间越多，但实际占用必须用本机nvidia-smi或任务管理器实测，不同框架和量化方式差异很大。

9. 常见问题与排查方法

LangChain 和 LangGraph 生态迭代很快，遇到问题不要慌，按下面这张排查表定位即可。

这里最容易踩的坑是：网上教程代码版本太旧，API 已经改掉。遇到报错先看官方文档的迁移说明，不要硬抄旧代码。LangGraph 的报错信息一般比较明确，尤其是节点返回类型和 State 字段不匹配的问题，按提示修改即可。

10. 最佳实践与使用边界

技术能跑通只是第一步，企业级 Agent 最重要的是稳定、可控、可追溯。

第一次接触这套技术栈，先不要直接上多智能体。先写一个单 Agent 最小用例，确认模型调用、工具调用、状态流转都正常，再加分支和循环。每次增加复杂度后，都保留一个可运行的备份配置。生产项目里，建议把模型配置、提示词、工具描述、图结构完全分开管理，这样任何一个环节调整，都不会牵一发动全身。

日志和可观测性不能落后。每个 Agent 运行建议记录：输入、每一步节点输出、token 消耗、耗时、返回状态。出现线上问题时，这些日志是唯一的排查依据。接口服务要限制访问范围，不能把 Agent 服务直接暴露在公网，至少要加一层鉴权。

合规和安全边界必须重视。接入内部数据时，先完成数据脱敏和权限校验；RAG 知识库里的内容要确认来源合法，不要拿未经授权的作品做检索。工具调用如果涉及订单、支付、审批等敏感系统，要把“模型建议”和“自动执行”分开，重要操作走人工确认。提示注入也是企业落地必须正视的问题，用户输入可能试图劫持系统指令，需要用输入校验和权限隔离来降低风险。

如果你是 Java 后端团队，也不必担心被 Python 生态隔离。Java 侧可以通过 LangGraph 的 REST API 接入 Agent 能力，Spring Boot 应用只负责业务编排，Agent 图在 Python 服务里执行，两边通过接口协作，各司其职。

11. 总结与下一步

LangChain + LangGraph 最值得你投入时间的点，不是背 API，而是理解图编排的思维方式：状态放在哪里、节点之间如何流转、异常时如何恢复。先把文中的最小 Agent 跑通，再验证多工具调用，最后把 Supervisor 模式和条件路由用在自己的业务场景里，这是最快的进阶路径。

最容易踩的坑有三个：版本混乱导致代码不兼容、多智能体路由缺少退出条件、生产环境没有日志和鉴权。建议收藏这篇文章，搭建环境时对照排查表使用。

下一步可以按这个方向走：先做单 Agent 工具调用，再升级为两阶段条件路由的 RAG Agent，之后尝试 Supervisor 模式，最后接入 LangGraph Server 做 API 化部署。每一步都跑通之后再进入下一个阶段，企业级 Agent 开发就不会走太多弯路。