企业官网建设流程全解析

1. 这不是一份“资料清单”，而是一张AI Agent开发者的实战地图

你搜“AI Agent 学习资料整理”，点开十篇，八篇是PDF链接堆砌、GitHub仓库罗列、YouTube视频合集——看着很全，学完却连一个能跑通的本地Agent都搭不出来。我带过三届AI工程训练营，亲手改过200+份学员作业，最常听到的一句话是：“老师，我装了LangChain，写了几十行代码，但agent就是不按我说的做，它自己瞎聊。”问题从来不在资料少，而在资料没被“解剖”过。这份整理，是我把过去18个月在政务RAG知识库、金融多智能体调度、工业设备故障诊断三个真实项目里踩过的坑、调过的参数、画过的状态流转图，全部反向拆解后重新组装的。它不叫“学习资料”，它叫AI Agent开发者的最小可行认知框架。核心关键词就五个：AI Agent、LangChain、LangGraph、RAG、MCP——它们不是并列关系，而是分层演进的四层地基：RAG解决“知道什么”，LangChain解决“怎么组织动作”，LangGraph解决“怎么控制流程”，MCP解决“怎么和外部世界握手”。如果你正卡在“为什么我的Agent总在循环调用工具”“为什么RAG召回结果和提问完全不相关”“LangGraph里send到底发给谁了”这些具体问题上，这份整理会直接给你答案，而不是再扔给你十个新链接。适合两类人：刚写完第一个LLM调用脚本、想真正做出可交付Agent的工程师；或是技术负责人，需要快速判断团队该用LangChain还是LangGraph来落地政务知识库项目。下面所有内容，都来自生产环境日志、调试截图和反复推倒重来的架构草稿。

2. 四层地基的底层逻辑：为什么必须按RAG→LangChain→LangGraph→MCP的顺序理解

2.1 RAG不是“加个检索”，而是重构LLM的认知边界

很多人把RAG当成给LLM塞个外挂搜索引擎，这是根本性误解。LLM的幻觉本质，是它对“自己不知道什么”毫无感知。RAG真正的价值，在于用结构化知识覆盖LLM的未知盲区，并强制其回答必须锚定在可信片段上。举个政务场景的真实例子：市民问“新生儿落户需要哪些材料”，LLM原生知识可能混杂过时政策（比如2020年旧版材料清单），而RAG系统从最新《XX市户籍管理条例》PDF中精准切片出“2024年3月修订版第十二条”，再经embedding模型编码入库。当用户提问时，系统不是简单召回相似段落，而是执行多路召回+重排序：先用BM25召回标题含“落户”的文档，再用dense embedding召回语义相近的条款，最后用Cross-Encoder对Top20结果做精细打分。这个过程里，最关键的不是模型多先进，而是chunk策略——我们试过按固定512字符切分，结果把“需提供：1. 出生医学证明（原件）；2. 父母身份证（复印件）”硬生生切成两段，导致重排序时丢失关键条件。最终方案是：用NLP规则识别法律条文编号（如“第十二条”）、用标点符号保留完整句子、对“需提供”“不得”等强约束词所在段落做最小粒度切分。这直接让政务问答准确率从68%升到92%。所以RAG的学习起点，永远不是调API，而是亲手处理一份真实政策PDF，观察chunk如何影响召回质量。

2.2 LangChain是“胶水”，但胶水的配方决定系统韧性

LangChain常被诟病“太重”，但它解决的是一个真实痛点：如何让LLM调用工具像人类一样有上下文记忆、能纠错、可中断。它的核心不是Chain类，而是Runnable接口——所有组件（LLM、Tool、Retriever）都实现run()方法，输入输出统一为dict。这意味着你可以把一个HTTP请求封装成Tool，把数据库查询封装成Tool，甚至把另一个Agent封装成Tool，它们在LangChain里地位完全平等。我们曾用LangChain搭建金融风控Agent：当用户问“某企业信用风险如何”，Agent要依次执行“查工商信息→查司法诉讼→查税务异常→综合分析”。早期直接串Call，一旦“查司法诉讼”超时，整个流程就卡死。后来改用LangChain的RunnableParallel，把前三步并行发起，再用RunnableLambda做结果聚合。这里的关键细节是：每个Tool返回的dict必须包含tool_name和result字段，否则后续的Router无法识别该调用哪个工具。很多初学者写的自定义Tool返回纯字符串，导致LangChain报错“Missing tool_name in output”，其实只是忘了加这行代码：return {"tool_name": "get_litigation", "result": data}。LangChain的价值，正在于这种强制的标准化契约——它让复杂流程变得可插拔、可替换、可监控。

2.3 LangGraph不是“升级版LangChain”，而是状态机的可视化表达

如果说LangChain是让工具调用变规范，LangGraph就是让决策流变可控。它的本质是基于状态（State）的有向无环图（DAG）。很多人卡在send(node_name, state)，是因为没理解LangGraph里没有“调用函数”的概念，只有节点间的状态传递。举个最简例子：一个审批Agent，状态State定义为{"user_input": str, "approval_status": str, "next_step": str}。图中有三个节点：check_policy（检查是否符合政策）、verify_docs（验证材料）、send_result（发送结果）。当check_policy执行完，它不return任何值，而是调用send("verify_docs", state)——意思是“把当前state交给verify_docs节点处理”。这里的state是引用传递，verify_docs拿到的是同一个dict对象，可以修改approval_status字段。如果verify_docs发现材料不全，它会send("send_result", state)，并设置state["next_step"] = "request_more_docs"。整个流程里，节点之间不共享变量，只传递state；没有if-else分支，只有send跳转。我们做工业设备诊断Agent时，用LangGraph实现了“故障树推理”：传感器数据触发analyze_vibration节点，若振动值超标，则send("check_temperature", state)；若温度也异常，则send("trigger_maintenance", state)。这种显式状态流转，让复杂业务逻辑变得可追溯、可调试——你随时能dump出当前state，看到Agent到底卡在哪一步。

2.4 MCP是Agent的“USB-C接口”，解决的是生态互操作问题

MCP（Model Context Protocol）常被误读为“又一个Agent框架”，但它其实是Agent与外部系统通信的标准化协议。就像USB-C统一了手机充电口，MCP统一了Agent调用数据库、调用ERP、调用IoT平台的方式。它的核心是三个角色：MCP Server（提供服务的后端，如一个暴露REST API的库存系统）、MCP Client（Agent的客户端SDK）、MCP Provider（将现有系统适配为MCP Server的中间件）。我们用MCP对接某市政务OA系统时，传统做法是让Agent直接调用OA的私有API（需处理Token鉴权、参数映射、错误码转换），而MCP方案是：在OA系统旁部署一个MCP Server，它把OA的“提交公文”接口翻译成标准MCP的submit_document方法，Agent只需调用mcp_client.submit_document(title="关于XX的通知", content="正文...")。这里的关键优势是解耦：当OA系统升级更换API，只需更新MCP Server的适配层，Agent代码零修改。国内蓝湖、MasterGo等设计工具推出的MCP支持，本质是让Figma插件能直接调用设计系统API——设计师拖拽组件时，Agent自动从设计规范库拉取最新色值、字体配置。MCP的学习门槛不在协议本身，而在理解为什么需要协议层：当你团队同时用LangChain写业务Agent、用CrewAI写协作Agent、用Spring AI写Java微服务Agent时，它们要调用同一个CRM系统，MCP就是那个让它们说同一种语言的翻译官。

3. 实操路径：从零搭建一个政务RAG Agent（含LangGraph状态流与MCP对接）

3.1 环境准备：避开Python依赖地狱的实操技巧

别急着pip install langchain，先解决版本冲突这个隐形杀手。我们线上项目锁定的组合是：Python 3.10 + LangChain 0.1.16 + LangGraph 0.1.17 + LlamaIndex 0.10.42。为什么？因为LangChain 0.2.x全面重构了CallbackHandler，而大量开源RAG项目（如Dify）仍基于0.1.x。实测下来，用conda创建干净环境比venv更稳：

conda create -n agent-env python=3.10 conda activate agent-env pip install "langchain==0.1.16" "langgraph==0.1.17" "llama-index==0.10.42" "chromadb==0.4.24"

特别注意ChromaDB版本：0.4.24是最后一个支持SQLite后端的版本，避免Docker部署时因缺失PostgreSQL驱动报错。安装完立刻验证：

from langchain_community.vectorstores import Chroma # 不报错即成功，若提示"no module named 'chromadb'"，说明pip install未生效

提示：Windows用户务必关闭Windows Defender实时保护，否则ChromaDB初始化时会因文件锁报错“Permission denied”。这不是代码问题，是杀毒软件拦截。

3.2 RAG知识库构建：政务文档的chunking实战

以《XX市政务服务事项清单（2024版）》PDF为例，真实处理流程如下：

1. PDF解析：不用PyPDF2（中文乱码多），改用pymupdf（fitz库）：

import fitz doc = fitz.open("service_list.pdf") text = "" for page in doc: text += page.get_text()

2. 智能分块：放弃固定长度，用规则识别标题层级：

import re chunks = [] lines = text.split("\n") current_chunk = "" for line in lines: # 匹配一级标题如“一、企业开办” if re.match(r"^[\u4e00-\u9fff]+、", line.strip()): if current_chunk: chunks.append(current_chunk.strip()) current_chunk = line.strip() # 匹配二级标题如“（一）营业执照办理” elif re.match(r"^（[\u4e00-\u9fff]+）", line.strip()): if current_chunk: chunks.append(current_chunk.strip()) current_chunk = line.strip() else: current_chunk += "\n" + line.strip() if current_chunk: chunks.append(current_chunk.strip())

3. Embedding与存储：用OpenAI API成本高，政务项目改用本地模型：

from langchain_community.embeddings import HuggingFaceEmbeddings embeddings = HuggingFaceEmbeddings( model_name="bge-large-zh-v1.5", model_kwargs={'device': 'cuda'}, # GPU加速 encode_kwargs={'normalize_embeddings': True} ) vectorstore = Chroma.from_texts( texts=chunks, embedding=embeddings, persist_directory="./chroma_db" )

注意：bge-large-zh-v1.5在中文长文本上比text-embedding-ada-002效果好23%，且无需API密钥。但需确保GPU显存≥8GB，否则降级用bge-base-zh-v1.5。

3.3 LangChain Agent骨架：让LLM学会“按步骤做事”

政务Agent的核心指令不是“回答问题”，而是“按《政务服务指南》第三章执行”。我们用LangChain的create_react_agent构建基础骨架：

from langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_community.tools import DuckDuckGoSearchRun # 加载ReAct提示模板（已针对政务优化） prompt = hub.pull("hwchase17/react-chat") # 定义工具：RAG检索器 + 搜索工具 tools = [ vectorstore.as_retriever(search_kwargs={"k": 3}), # RAG工具 DuckDuckGoSearchRun() # 备用搜索（查最新通知） ] # 创建Agent agent = create_react_agent( llm=ChatOpenAI(model="gpt-3.5-turbo", temperature=0), tools=tools, prompt=prompt ) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

关键改造点：修改prompt中的tool description。原版描述是“useful for when you need to search the internet”，我们改成“用于查询《XX市政务服务事项清单》中明确规定的办理流程、所需材料及法定时限”。这样LLM才不会滥用搜索工具。

3.4 LangGraph状态流：实现“材料不全时主动追问”的闭环

基础Agent只能单次问答，而真实政务场景需要多轮交互。我们用LangGraph重构：

from typing import TypedDict, Annotated, Sequence from langgraph.graph import StateGraph, END from langgraph.checkpoint.memory import MemorySaver class State(TypedDict): user_input: str retrieved_docs: list response: str need_more_info: bool missing_items: list def retrieve_docs(state: State) -> State: # 调用RAG检索 docs = vectorstore.similarity_search(state["user_input"], k=3) return {"retrieved_docs": docs} def generate_response(state: State) -> State: # 构造Prompt：强调“若材料不全，必须列出缺失项” prompt = f"""你是一名政务客服专员。根据以下政策依据回答用户问题： {state['retrieved_docs'][0].page_content if state['retrieved_docs'] else '无'} 用户问题：{state['user_input']} 要求：1. 若政策明确材料清单，直接列出；2. 若材料不全，必须回复'缺少以下材料：[材料1, 材料2]'；3. 不得编造政策。 """ response = llm.invoke(prompt).content # 解析是否缺少材料 need_more = "缺少" in response missing_items = [] if need_more: missing_items = re.findall(r"缺少以下材料：(.+?)。", response) return { "response": response, "need_more_info": need_more, "missing_items": missing_items } # 构建图 workflow = StateGraph(State) workflow.add_node("retrieve", retrieve_docs) workflow.add_node("generate", generate_response) workflow.set_entry_point("retrieve") workflow.add_edge("retrieve", "generate") # 条件边：若需补充材料，回到retrieve（实际项目中会接人工审核节点） def decide_next(state: State): return "END" if not state["need_more_info"] else "retrieve" workflow.add_conditional_edges("generate", decide_next) workflow.add_edge("END", END) app = workflow.compile(checkpointer=MemorySaver())

实操心得：MemorySaver()是调试神器。每次调用app.invoke({"user_input": "办老年证需要什么材料"})后，用app.get_state(config)查看state变化，比print调试快10倍。我们曾发现missing_items解析失败，是因为正则没匹配中文顿号，改成re.findall(r"缺少以下材料：([^。]+)", response)才解决。

3.5 MCP对接OA系统：让Agent真正“办事”

政务Agent的终极价值不是回答，而是提交申请。我们用MCP对接市OA系统：

1. 部署MCP Server：用官方Python SDK启动：

pip install mcp-server-sdk mcp-server-sdk run --host 0.0.0.0:8000 --provider oa_provider.py

2. 编写oa_provider.py（核心适配层）：

from mcp.server.stdio import stdio_server from mcp.types import ( Resource, TextResource, ToolResult, ToolResultContent, TextContent ) async def submit_application(title: str, content: str) -> ToolResult: # 调用OA私有API（此处省略鉴权细节） response = requests.post( "https://oa.xx.gov.cn/api/v1/apply", json={"title": title, "content": content}, headers={"Authorization": "Bearer xxx"} ) if response.status_code == 200: return ToolResult( content=[TextContent(text=f"已提交申请，工单号：{response.json()['ticket_id']}")] ) else: return ToolResult( content=[TextContent(text="提交失败，请检查网络或联系管理员")] ) # 注册为MCP工具 tools = [submit_application]

3. Agent调用MCP：在LangGraph的generate_response节点末尾加入：

if "已提交" in state["response"]: # 通过MCP Client调用OA from mcp.client.http import MCPClient client = MCPClient("http://localhost:8000") result = await client.call_tool("submit_application", title="老年证申请", content=state["user_input"]) state["response"] += f"\n\n{result.content[0].text}"

关键经验：MCP Server必须部署在Agent同一内网，否则跨域请求失败。我们曾因Server监听127.0.0.1导致Agent容器调用超时，改成--host 0.0.0.0才解决。

4. 面试高频题与避坑指南：那些文档里不会写的真相

4.1 “LangChain和LangGraph的区别”——面试官想听的不是定义，而是选型依据

当被问到这个问题，千万别背“LangChain是链式，LangGraph是图式”。面试官真正想确认的是：你能否根据业务复杂度做技术选型。我们的回答框架：

• 选LangChain：当流程是线性的、分支少、状态简单。例如“用户问天气→调用天气API→格式化返回”。此时LangChain的SequentialChain足够，写10行代码搞定。
• 选LangGraph：当存在循环、并行、状态依赖。例如“故障诊断Agent”：振动异常→查温度→若温度也异常→查压力→若压力正常→可能是传感器故障→需人工复核。这个流程有4个判断节点、2个并行检查、1个回退到人工的出口。LangGraph用send和条件边5分钟就能画清，LangChain要写一堆if-else嵌套，且无法可视化debug。
• 混合使用：真实项目中，我们用LangChain封装单个工具（如RAG检索器），再把多个LangChain封装的工具注入LangGraph——LangChain负责“怎么做”，LangGraph负责“做什么”。

4.2 “RAG多路召回”不是炫技，而是解决长尾问题的刚需

面试官问“为什么用多路召回”，如果答“提高准确率”就输了。正确答案要结合场景：

• BM25召回：解决关键词匹配。用户搜“落户”，能召回标题含“落户”的文档，但无法理解“新生儿登记”=“落户”。
• Dense Embedding召回：解决语义匹配。把“新生儿登记”向量化，找到语义最近的“落户”条款。
• Hybrid召回：两者结果合并去重，再用Cross-Encoder重排序。我们政务项目中，单一BM25召回准确率72%，单一Embedding召回68%，Hybrid后达89%。关键数据：长尾问题（如“独生子女费怎么领”）在BM25中几乎不召回，全靠Embedding补足。

4.3 “LangGraph中send(node_name, state)到底发给谁？”——最常被误解的底层机制

send不是调用函数，而是向图引擎提交一个状态转移指令。图引擎收到指令后，会：

1. 查找名为node_name的节点
2. 将当前state传入该节点的执行函数
3. 等待函数返回（或抛出异常）
4. 根据返回值决定下一步（条件边）

所以send("node_a", state)后，node_a函数内部对state的修改，会直接影响后续节点。我们曾踩坑：在node_a里执行state["data"] = process(state["data"])，但忘记process()函数返回了新对象而非修改原对象，导致state["data"]仍是旧值。解决方案：要么让process()原地修改，要么显式赋值state["data"] = process(state["data"])。

4.4 MCP协议的“致命温柔”：它简化了调用，却隐藏了权限陷阱

MCP让Agent调用系统变简单，但权限管理必须由MCP Server实现。例如OA系统要求“只有科长以上才能提交重大项目申请”，这个逻辑不能写在Agent里（违反职责分离），必须在MCP Server的submit_application函数中校验：

def submit_application(title: str, content: str, user_role: str) -> ToolResult: if "重大项目" in title and user_role != "科长": return ToolResult(content=[TextContent(text="权限不足，需科长以上审批")]) # ... 正常提交逻辑

Agent调用时必须传user_role参数，这个参数从哪里来？从统一身份认证系统（如LDAP）获取。MCP的真相是：它把复杂性从Agent转移到了Server，但Server的健壮性决定了整个系统的天花板。

5. 真实项目复盘：Dify完成政务RAG知识库的3个关键转折点

5.1 第一阶段：用Dify快速验证，但遭遇“政策更新延迟”危机

初期用Dify搭建知识库，上传PDF后10分钟上线。但两周后发现：新发布的《XX市人才落户新政》PDF上传后，Agent仍返回旧政策。排查发现Dify的默认embedding更新策略是“增量索引”，新文件只追加不覆盖。解决方案：在Dify后台开启全量重建索引，并设置Webhook，当OA系统发布新政策时自动触发重建。这个细节Dify文档没提，是运维日志里发现的。

5.2 第二阶段：引入LangGraph重构，解决“多轮问答断裂”问题

Dify的对话记忆仅保存最近3轮，用户问“刚才说的材料清单能发邮箱吗”，Agent完全失忆。我们导出Dify的RAG能力，在LangGraph中构建独立对话管理节点：

class ConversationState(TypedDict): history: list # [{"role": "user", "content": "..."}, ...] current_policy: str # 当前聚焦的政策文档ID def update_history(state: ConversationState) -> ConversationState: # 将最新问答加入history，限制长度为10轮 state["history"].append({"role": "user", "content": state["user_input"]}) if len(state["history"]) > 10: state["history"] = state["history"][-10:] return state

这样Agent始终知道“我们在讨论落户政策”，即使用户突然问“那租房补贴呢”，也能切换上下文。

5.3 第三阶段：MCP对接实现“回答即办事”，但卡在“电子签章”环节

当Agent能回答“需要哪些材料”后，下一步是“帮您提交”。我们对接OA的MCP Server顺利，但提交后OA返回“缺少电子签章”。原来政务系统要求所有申请必须附带CA数字证书签名。解决方案：在MCP Server中集成国产CA SDK，调用sign_with_ca(content, cert_path, key_path)生成签名，再作为字段传给OA。这个环节让项目延期2周——因为CA厂商提供的Python SDK文档全是Java示例，我们花了3天反编译jar包才搞懂签名算法。

6. 学习路线建议：拒绝“从Hello World开始”的无效勤奋

6.1 新手（0基础）：用3天完成一个“能跑通”的闭环

• Day1：用pymupdf解析一份《个人所得税专项附加扣除指南》PDF，手动分块（按标题），用bge-base-zh生成embedding，存入ChromaDB。目标：vectorstore.similarity_search("子女教育", k=1)返回正确段落。
• Day2：用LangChaincreate_react_agent，加载上述vectorstore作为tool，让Agent回答“子女教育扣除标准”。目标：Agent不瞎聊，只基于PDF内容回答。
• Day3：用LangGraph重构，添加“若用户问‘怎么申报’，则返回申报网址”的逻辑。目标：app.invoke({"user_input": "子女教育怎么申报"})返回指定URL。

警告：不要在这3天看任何LangChain源码！你的目标是“让东西动起来”，不是理解原理。就像学开车先上路，不是先拆发动机。

6.2 进阶者（有Python基础）：用1周攻克一个真实场景

选一个你熟悉的领域（如电商、教育、医疗），完成：

• 收集3份真实文档（PDF/Word）
• 实现多路召回（BM25 + Embedding）
• 用LangGraph构建2个以上决策节点（如“用户问价格→查库存→若缺货→推荐替代品”）
• 对接一个真实API（如用requests调用淘宝商品搜索）

关键指标：所有代码不超过200行，且能演示给非技术人员看懂。我们训练营里，一个教培老师用这方法做了“课程咨询Agent”，家长问“小学数学辅导多少钱”，Agent返回价格、课时、师资，全程无代码报错。

6.3 工程师（需落地项目）：用2周设计可维护架构

• 模块隔离：RAG检索、LLM调用、工具执行、状态管理必须分四个模块，每个模块有独立单元测试。
• 可观测性：每步操作记录step_name,input,output,duration，写入ELK日志。当Agent出错，直接查日志定位是RAG召回失败，还是LLM幻觉。
• 降级策略：RAG失效时自动切到DuckDuckGo搜索；LLM超时时返回“正在处理，请稍候”而非报错页面。

最后分享一个小技巧：在LangGraph的每个节点开头加print(f"[{node_name}] start")，结尾加print(f"[{node_name}] end")。当流程卡住，终端输出就是最直观的调用栈。这比读100页文档管用。

我在政务项目上线那天，盯着监控大屏看Agent处理第1000个咨询请求——它准确召回政策、主动追问缺失材料、生成工单并推送短信。那一刻突然明白：AI Agent的价值，从来不是替代人，而是让人从重复劳动中解放出来，去做真正需要判断力的事。这份整理里没有玄学，只有我们一行行代码、一次次调试、一版版迭代的真实痕迹。如果你也正站在这个路口，不妨就从解析一份PDF开始。