企业官网建设流程全解析

1. 一个前端Leader的AI Agent转型路线图：第70天我踩过的坑和想明白的事

前端做到Leader这个位置，说实话，日常已经很少写纯业务代码了。更多时间花在架构评审、排期协调、跨部门对齐这些事情上。但今年身边越来越多的技术群在聊AI Agent，从LangChain到LangGraph，从Dify到CrewAI，各种框架层出不穷。我一开始是抗拒的，觉得这波跟当年“前端工程师要不要学Node”一样，属于焦虑营销。直到有一次我用一个简单的Agent帮团队自动处理了每周的周报汇总和代码Review提醒，前后端加起来不到200行Python，那一刻我意识到：这东西不是噱头，它真的在改变我们构建软件的方式。

于是从第1天开始，我给自己定了一个规矩：每天至少花1小时动手写Agent相关代码，不只看文档。到今天正好第70天。这70天里，我从一个Python只能写脚本的前端，到能用FastAPI搭后端、用LangChain编排Agent、用LangGraph做状态机、用Ollama跑本地模型，中间踩了无数坑。这篇文章不是教程，是我自己的学习笔记和实操复盘，适合那些跟我一样有前端背景、想切入AI Agent但不知道从哪下手的人。我会把每个阶段的核心思路、工具选型理由、具体操作步骤、以及那些文档里不会写的坑，全部摊开讲。

2. 为什么前端Leader学AI Agent反而有优势

2.1 前端思维在Agent开发中的迁移价值

很多人觉得前端转AI是跨行，其实不是。Agent开发的核心工作是什么？是编排流程、处理状态、对接接口、渲染结果。这四件事，前端每天都在做。LangChain里的Chain，本质上就是前端的Promise链；LangGraph里的StateGraph，跟Redux的状态管理思路高度相似；Agent的Tool调用，跟前端调用后端API没有本质区别。你甚至可以把Agent理解成一个“会自己决定调用哪个API的前端应用”。

我在第10天左右写了一个自动整理会议纪要的Agent，核心逻辑是：接收一段文字，判断是否包含待办事项，如果有就提取出来写入Notion，如果没有就返回摘要。这个流程用LangChain的LCEL写出来，跟写一个前端表单提交逻辑几乎一模一样。区别只在于，前端的if-else是你写死的，Agent的if-else是模型自己判断的。这个认知转变很关键，它让我不再觉得AI是另一个世界的东西。

2.2 前端Leader的独特视角：从工程化角度看Agent

纯算法背景的人做Agent，容易陷入模型调优的细节里。但前端Leader的优势在于工程化思维。一个Agent要上线，不只是模型跑通就行，还要考虑：接口怎么设计、错误怎么处理、日志怎么打、状态怎么持久化、前端怎么展示。这些恰恰是前端Leader最熟悉的东西。

我在第30天的时候开始用FastAPI搭Agent的后端服务，发现它的设计哲学跟Express/Koa非常像。路由定义、中间件、依赖注入，前端开发者上手几乎没有门槛。而且FastAPI自带Swagger文档，调试起来比Postman还方便。我用它把之前散落在各个脚本里的Agent逻辑统一成了一个服务，前端通过一个简单的fetch就能调用。这种“把Agent当后端服务来设计”的思路，让我在团队里推动AI落地时顺畅了很多。

2.3 学习路径的取舍：为什么我选择Python而不是Node

前端学AI，第一个纠结就是语言。Node生态里也有LangChain.js，为什么还要学Python？我的理由是：Python生态的库更全、更新更快、社区更大。LangChain的Python版本比JS版本领先至少一个季度，很多新功能比如LangGraph的某些特性，Python先有，JS要等。而且大部分AI相关的论文、示例代码、开源项目都是Python写的，你学Python等于打开了一个更大的资源池。

当然，如果你只是想做简单的Agent调用，LangChain.js完全够用。但如果你想深入理解Agent的底层机制，比如自定义Tool、实现复杂的多Agent协作、对接本地模型，Python是绕不开的。我自己的做法是：先用LangChain.js快速验证想法，确认可行后用Python重写并部署。这样既利用了前端的快速原型能力，又保证了后端的扩展性。

3. 环境搭建：从零到跑通第一个Agent

3.1 Python环境安装与版本选择

第1天我做的第一件事就是装Python。这里有个坑：不要装最新版。我一开始装了Python 3.12，结果很多库还不兼容，LangChain的某些依赖直接报错。后来退回到Python 3.10，一切正常。如果你用的是Windows，去Python官网下载3.10.x的安装包，安装时务必勾选“Add Python to PATH”，否则后面命令行里调不到python命令。

装完之后验证一下：

python --version pip --version

如果两个命令都能正常输出版本号，说明环境没问题。接下来建议装一个虚拟环境工具，我用的是venv，Python自带，不需要额外安装：

python -m venv agent-env agent-env\Scripts\activate # Windows source agent-env/bin/activate # Mac/Linux

虚拟环境的好处是每个项目的依赖隔离，不会互相污染。我见过太多人因为全局装了一堆包导致版本冲突，最后重装系统的。这个习惯从一开始就要养成。

3.2 核心依赖安装：LangChain、FastAPI与Ollama

环境好了之后，装核心库。我的requirements.txt大概长这样：

langchain==0.1.0 langchain-community==0.0.10 langchain-openai==0.0.2 fastapi==0.108.0 uvicorn==0.25.0 python-dotenv==1.0.0 requests==2.31.0

安装命令：

pip install -r requirements.txt

这里注意，LangChain的版本更新非常快，不同版本之间的API差异很大。我建议锁定版本，不要用最新版，否则你今天写的代码明天可能就跑不起来了。上面这些版本是我实测稳定的组合，可以直接抄。

关于Ollama，如果你想本地跑模型，去Ollama官网下载安装包，装完之后拉一个模型：

ollama pull qwen2:7b

这个模型对中文支持不错，7B参数在16G内存的机器上能跑起来。如果你机器配置一般，可以用更小的模型比如qwen2:1.5b，效果差一些但速度快。Ollama的好处是它提供了一个本地API，LangChain可以直接对接，不需要联网，数据也不出本地。

3.3 第一个Agent：自动整理待办事项

环境搭好之后，我写了一个最简单的Agent来验证链路。功能是：输入一段文字，Agent判断里面有没有待办事项，有就提取出来，没有就返回“无待办”。

from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser llm = ChatOpenAI( model="qwen2:7b", base_url="http://localhost:11434/v1", api_key="ollama" ) prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个待办事项提取助手。如果用户输入中包含待办事项，请提取出来，每条一行。如果没有，返回'无待办'。"), ("user", "{input}") ]) chain = prompt | llm | StrOutputParser() result = chain.invoke({"input": "明天要交周报，后天跟产品对需求，另外记得给张三回邮件"}) print(result)

这段代码跑通的那一刻，我确认了一件事：Agent开发的门槛没有想象中高。核心就是Prompt加模型加输出解析，跟前端写一个表单验证逻辑的复杂度差不多。当然，这只是开始，真正的挑战在后面。

4. LangChain核心概念：从前端视角理解Chain与Agent

4.1 Chain的本质：可组合的异步流水线

LangChain里的Chain，你可以把它理解成前端的管道操作。比如你有一个数组，先filter再map再reduce，这就是一个链。LangChain的Chain也是一样，只不过每一步操作的不是数组元素，而是文本或者模型调用。

LCEL（LangChain Expression Language）用竖线|把各个组件串起来，这个语法跟Unix管道和前端RxJS的pipe操作符非常像。我第15天的时候写了一个多步Chain：先让模型生成文章大纲，再根据大纲生成正文，最后对正文做摘要。用LCEL写出来就是：

outline_chain = outline_prompt | llm | StrOutputParser() content_chain = content_prompt | llm | StrOutputParser() summary_chain = summary_prompt | llm | StrOutputParser() full_chain = {"outline": outline_chain} | content_chain | summary_chain

这种组合方式的好处是每一步都可以单独测试，出问题了容易定位。前端调试过中间件的人应该很熟悉这种感觉。

4.2 Agent与Chain的区别：什么时候该用哪个

Chain是线性的，你写死了步骤。Agent是动态的，模型自己决定下一步做什么。这是两者最核心的区别。

举个例子：如果你要做一个“根据用户问题查询数据库并返回答案”的功能，用Chain就够了，因为流程是固定的：接收问题→生成SQL→执行查询→格式化结果。但如果你要做一个“帮用户规划旅行”的功能，用户可能问机票、可能问酒店、可能问景点，Agent需要根据问题类型决定调用哪个工具，这时候就要用Agent。

我自己的经验是：能用Chain解决的就不要用Agent。Agent的灵活性带来的是不可预测性，调试难度成倍增加。我第25天的时候用Agent做了一个自动回复客户消息的功能，结果模型有时候会调用不存在的工具，有时候会陷入循环。后来改成Chain加条件分支，稳定性好了很多。

4.3 Tool的定义与调用：Agent的手和脚

Tool是Agent跟外部世界交互的接口。你可以把Tool理解成前端里的API封装函数。定义一个Tool需要三样东西：名称、描述、参数schema。描述非常重要，模型就是靠描述来判断什么时候该调用这个Tool。

from langchain.tools import tool @tool def get_weather(city: str) -> str: """查询指定城市的天气。输入城市名称，返回天气描述。""" # 实际实现省略 return f"{city}今天晴，25度"

这个@tool装饰器跟前端装饰器语法几乎一样。定义好之后，把Tool列表传给Agent，模型就会在需要的时候自动调用。我踩过的坑是：Tool的描述要写得非常明确，不要有歧义。我写过一个“查询订单”的Tool，描述只写了“查询订单信息”，结果模型有时候会用它来查用户信息。后来改成“根据订单号查询订单的物流状态和金额，不用于查询用户个人信息”，准确率立刻上去了。

5. FastAPI实战：把Agent包装成后端服务

5.1 FastAPI项目目录结构设计

当你的Agent逻辑越来越多，就不能再写在单个脚本里了。我第35天的时候把项目重构成了FastAPI的标准结构：

agent-service/ ├── app/ │ ├── __init__.py │ ├── main.py │ ├── routers/ │ │ ├── __init__.py │ │ ├── chat.py │ │ └── tools.py │ ├── services/ │ │ ├── __init__.py │ │ ├── agent_service.py │ │ └── llm_service.py │ ├── models/ │ │ ├── __init__.py │ │ └── schemas.py │ └── core/ │ ├── __init__.py │ └── config.py ├── requirements.txt └── .env

这个结构跟Express项目的组织方式很像：routers对应routes，services对应业务逻辑层，models对应数据模型。前端Leader看一眼就能理解。分层的目的是让Agent逻辑跟HTTP接口解耦，方便测试和复用。

5.2 核心接口实现：一个对话端点

在routers/chat.py里定义一个对话接口：

from fastapi import APIRouter from app.models.schemas import ChatRequest, ChatResponse from app.services.agent_service import run_agent router = APIRouter() @router.post("/chat", response_model=ChatResponse) async def chat(request: ChatRequest): result = await run_agent(request.message, request.session_id) return ChatResponse(reply=result)

agent_service.py里封装Agent调用：

from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate async def run_agent(message: str, session_id: str) -> str: llm = ChatOpenAI( model="qwen2:7b", base_url="http://localhost:11434/v1", api_key="ollama" ) prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个 helpful 的助手。"), ("user", "{input}") ]) agent = create_openai_tools_agent(llm, tools, prompt) executor = AgentExecutor(agent=agent, tools=tools) result = await executor.ainvoke({"input": message}) return result["output"]

启动命令：

uvicorn app.main:app --reload --port 8000

跑起来之后访问http://localhost:8000/docs就能看到自动生成的Swagger文档，直接在上面测试接口。这个体验比前端自己搭Mock服务还方便。

5.3 前端如何对接Agent服务

前端调用Agent服务跟调用普通后端API没有区别。我用React写了一个简单的聊天界面，核心就是一个fetch：

const response = await fetch('http://localhost:8000/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message: input, session_id: sessionId }) }); const data = await response.json(); setMessages(prev => [...prev, { role: 'assistant', content: data.reply }]);

这里有个细节：Agent的响应时间通常比普通API长，因为要等模型推理。所以前端一定要加loading状态，最好用流式输出。FastAPI支持StreamingResponse，LangChain也支持stream模式，两者结合可以实现打字机效果。我第45天实现了这个功能，用户体验提升非常明显。

6. LangGraph进阶：用状态机管理复杂Agent流程

6.1 为什么需要LangGraph

LangChain的Agent虽然灵活，但有个问题：流程不可控。模型可能跳步、可能重复调用、可能忘记之前的上下文。当你的Agent需要处理多轮对话、需要记住中间状态、需要根据条件走不同分支时，LangChain的AgentExecutor就不够用了。

LangGraph的核心思想是把Agent流程定义成一个状态图。每个节点是一个操作，边是条件判断。这跟前端的状态管理库（Redux、XState）思路一致。我第50天开始用LangGraph重写了一个客服Agent，流程是：接收问题→判断问题类型→如果是售后走售后流程→如果是咨询走咨询流程→最后统一格式化输出。用状态图表示非常清晰。

6.2 StateGraph的基本用法

from langgraph.graph import StateGraph, END from typing import TypedDict class AgentState(TypedDict): messages: list next_step: str def classify(state: AgentState): # 判断问题类型 return {"next_step": "after_sale"} def handle_after_sale(state: AgentState): # 处理售后 return {"messages": state["messages"] + ["售后处理完成"]} workflow = StateGraph(AgentState) workflow.add_node("classify", classify) workflow.add_node("after_sale", handle_after_sale) workflow.set_entry_point("classify") workflow.add_conditional_edges("classify", lambda x: x["next_step"], { "after_sale": "after_sale", "consult": "consult" }) workflow.add_edge("after_sale", END) app = workflow.compile()

这段代码定义了一个最简单的状态图。AgentState是全局状态，每个节点读取并修改它。add_conditional_edges根据状态决定下一步走哪个节点。这种显式的流程定义，让调试变得容易很多。你可以清楚地看到每一步的输入输出，而不是像黑盒一样猜模型在干什么。

6.3 多Agent协作的实践

LangGraph还支持多Agent协作。我第60天做了一个内容创作Agent，包含三个角色：研究员负责搜集资料，写手负责写初稿，编辑负责润色。三个Agent通过状态图串联，每个Agent有自己的Prompt和工具。这种架构比单个大Agent效果好很多，因为每个Agent的职责单一，Prompt可以写得更精准。

实际跑下来，多Agent的token消耗是单Agent的三倍左右，但输出质量提升明显。如果你的场景对质量要求高、对成本不敏感，多Agent值得尝试。反之，单Agent加好的Prompt工程可能更划算。

7. 常见问题与排查技巧实录

7.1 模型调用超时与重试策略

本地跑Ollama的时候，如果模型太大或者机器内存不够，请求会超时。我一开始没做超时处理，前端一直转圈，用户体验很差。后来加了重试和超时：

from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="qwen2:7b", base_url="http://localhost:11434/v1", api_key="ollama", timeout=30, max_retries=2 )

timeout是单次请求超时时间，max_retries是失败重试次数。注意重试次数不要设太多，否则用户等太久。如果经常超时，考虑换更小的模型或者升级机器配置。

7.2 Token超限与上下文管理

Agent对话轮次多了之后，上下文会越来越长，最终超过模型的token限制。我遇到过模型突然开始胡言乱语，排查半天发现是上下文超了。解决办法有两个：一是限制历史消息数量，只保留最近N轮；二是用摘要的方式压缩历史。

from langchain.memory import ConversationSummaryBufferMemory memory = ConversationSummaryBufferMemory( llm=llm, max_token_limit=2000, return_messages=True )

ConversationSummaryBufferMemory会在token接近上限时自动把早期对话总结成摘要，既保留了关键信息又控制了长度。这个组件在LangChain里开箱即用，建议每个对话类Agent都配上。

7.3 常见问题速查表

提示：遇到任何奇怪的问题，第一步先看日志。LangChain和FastAPI的日志都很详细，大部分问题看日志就能定位。

7.4 几个文档里不会写的坑

第一个坑：Ollama的模型加载是懒加载的，第一次调用会特别慢，可能等一两分钟。解决办法是服务启动后先发一个预热请求，让模型提前加载到内存。

第二个坑：LangChain的版本升级经常有breaking change。我有一次手贱升级了langchain，结果之前跑得好好的代码全报错。后来学乖了，生产环境永远锁定版本，升级前先在测试环境跑一遍。

第三个坑：FastAPI的async函数里如果调用了同步的阻塞代码，会卡住整个事件循环。LangChain的某些方法只有同步版本，在async接口里调用会阻塞。解决办法是用run_in_executor包装，或者用LangChain的ainvoke异步方法。

8. 70天后的反思与后续方向

走到第70天，我最大的感受是：AI Agent不是替代前端，而是给前端打开了一扇新门。以前我们只能做界面和交互，现在我们可以做能自主决策、能调用工具、能处理复杂流程的智能应用。这个能力边界扩展是实实在在的。

接下来的方向，我打算深入两个点：一是RAG（检索增强生成），让Agent能基于私有知识库回答问题；二是Agent的评估与监控，怎么量化一个Agent的好坏，怎么在生产环境里持续优化。这两个方向都是目前落地时最缺的。

如果你也是前端背景想切入AI，我的建议是：不要等准备好了再开始，直接动手写。从最简单的Chain开始，跑通了再加Tool，再加状态管理，再加服务化。每一步都会遇到问题，但每一步的问题都有解。70天前我连Python的虚拟环境都搞不利索，现在能独立搭建一个完整的Agent服务。这个过程中积累的经验，比看任何教程都值钱。