企业官网建设流程全解析

前几天在社区里有人甩给我一句话：AI Agent 已经聊了两年，能聊明白的人很多，能把它放到生产环境里稳定跑起来的人很少。这话有点扎心，但确实是现状。我自己跟 Agent 打了大半年交道，从最开始在 Jupyter Notebook 里调 API，到后来用 FastAPI 把 Agent 包成服务给业务方调用，中间踩过无数个坑。回头总结下来，真正决定一个 Agent 能不能落地的，不是某个模型的推理能力有多强，而是你有没有把它的“七要素”想清楚，以及在七个关键决策点上做了正确选择。

这篇文章想把这两个框架讲透。它不是概念科普，而是工程视角的拆解：先看 Agent 由哪些零件组成，再看从 Demo 到生产你要拍板哪些事，最后给一套可以直接抄作业的 FastAPI + LangGraph 实现思路。适合后端工程师、AI 应用开发者，以及那些已经跑通原型、正准备把它推上线的团队看。

1. 七要素拆解：Agent 的工程骨架

1.1 Agent 不是“提示词 + API”，而是一条感知-决策-执行闭环

很多人第一次接触 Agent，以为它就是把提示词写长一点，然后循环调用大模型。这个理解不算错，但离工程实现差得很远。如果只做一次“模型调用 + 返回结果”，那叫单轮问答，不叫 Agent。Agent 的本质是一个闭环：拿到的用户请求先进入上下文，模型基于当前状态给出下一步动作，动作可能是一个回答，也可能是一个工具调用；工具返回结果后再喂回模型，模型继续决策，直到它认为任务完成。

这个循环跑起来以后，你就不得不面对一系列工程问题：模型怎么知道自己有哪些工具可用？上一次调用产生了什么中间结果，下一次要如何继承？如果某一步工具报错，是重试还是终止？这些问题的答案，全都落在“七要素”上。

我把这七个要素按角色分一下：模型是大脑，提示词是行为准则，工具是手脚，记忆是工作台，规划是思考路径，多智能体协作是分工体制，编排是控制中枢。

1.2 七要素逐个过一遍，先搞清楚每个零件在干什么

先聊模型。模型是 Agent 的推理引擎，决定了它能理解多复杂的指令、能生成多稳定的结构输出。但工程上要注意，模型不是越强越好，而是越匹配越好。你做一个只查数据库的问答 Agent，用顶级大模型就是浪费；做一个要自我纠错的复杂任务 Agent，用小模型就很容易陷入死循环。这个取舍后面会展开，先记住一句话：模型选型本质是“能力下限”的选型。

第二个要素是提示词。在 Agent 工程里，提示词的作用被很多人低估，它不是写一段“你是一个助手”就完事。你要在提示词里说清楚：Agent 的角色边界是什么、它握有哪些工具、每个工具的适用场景、遇到不确定信息时应该怎么办、输出格式必须遵守什么。一个好的 Agent 提示词，读起来更像一份员工手册，而不是一句咒语。

第三个是工具。工具是 Agent 与外部世界交互的通道，可以是函数调用、HTTP API、数据库查询、代码解释器。没有工具的 Agent 只能纸上谈兵，有了工具才算真正“下地干活”。工程上，工具的定义要尽量原子化，一个工具只做一件事，描述要足够清晰，否则模型很容易在选工具时犹豫或选错。

第四个是记忆。记忆分短期和长期。短期记忆指当前任务上下文里的对话历史和中间结果，长期记忆指跨会话的用户偏好、历史结论、领域知识。记忆放在哪、怎么压缩、怎么防止上下文爆炸，是 Agent 工程里最容易出问题的一环。

第五个是规划。规划能力让 Agent 能把一个大任务拆成多个小步骤，而不是指望一次调用就得到最终答案。实现规划的方式有很多种：让模型直接输出步骤、用 ReAct 模式交替推理和行动、或者外挂一个 Planner 模块。工程上规划需要控制和兜底，否则模型会“想太多”，把简单任务拆成八步，反而拉低效率和成功率。

第六个是多智能体协作。当你把任务拆给多个角色 Agent 时，就涉及谁来分配任务、谁汇总结果、它们之间怎么通信。多 Agent 不是银弹，它只有在任务本身具备天然分工、或者需要不同角色视角时才有价值。这点我会在决策点里细说。

第七个是编排。编排层负责把上面所有要素串起来，决定 Agent 循环的启动条件、每个节点的执行顺序、出错时的回退策略。在代码层面，它就是一个状态机。LangGraph、AutoGen 这些框架解决的就是编排问题，你可以用它们，也可以自己写一个，但绝对不能不写。

1.3 缺一个会怎样：从真实翻车案例看短板效应

缺模型的 Agent 不成立，缺工具的叫聊天机器人，但其余几个要素缺一个，都会在特定场景翻车。

举个我自己的例子。早期做一个自动写周报的 Agent，当时觉得提示词写得够详细、工具也接上了，但跑了一周发现它经常把上周的数据和这周的数据混在一起。原因就是没有做记忆隔离：每次会话都带着上一轮的向量检索结果，模型分不清哪些是当前周期的数据。后来单独加了一块“临时工作区”，每次任务开始前清空，只允许工具调用写入本次结果，问题立刻解决。这是缺“记忆管理”的典型症状。

再举个例子，有个朋友用低代码平台搭客服 Agent，单轮对话效果很好，但用户一旦连续追问几句，它就答非所问。拆开看发现，平台默认把整段对话历史全部塞给模型，旧信息把关键问题淹没了。后来把历史压缩成摘要、只保留最近两轮原文，准确率立刻回到正常水平。这说明提示词再强，也兜不住糟糕的上下文组织。

所以我一直建议团队在画架构图之前，先用七要素检查一下自己的方案：模型选型有没有依据、工具清单是否完整、记忆策略是空白还是拍脑袋、编排节点有没有定义清楚。任何一项是空白，都要在进入编码之前想办法补上，否则后面全是返工。

2. 七个决策点：从 Demo 到生产的分岔路口

2.1 决策一：单 Agent 还是多 Agent，先问业务复杂度

很多团队看到别人用多 Agent 协作觉得很酷，上来就设计五个角色：老板 Agent、分析师 Agent、写手 Agent、审核 Agent。结果跑起来后互相踢皮球，一个任务要循环七八轮才完，Token 消耗翻了三倍，准确率反而没提升。

我的经验是，能用单 Agent 解决的单 Agent 解决。单 Agent 只有一个上下文、一套状态机，调试成本低、Token 消耗少、行为更可控。什么时候才考虑多 Agent？一是任务里确实存在冲突的目标，比如既要忠实原文又要压缩到两百字，让一个模型同时满足容易两头不讨好，拆成“摘要 Agent”和“润色 Agent”反而各司其职；二是工具类型差异太大，比如一个 Agent 只操作数据库、另一个 Agent 只调用外部内容接口，拆开可以隔离权限和错误域。

如果你用的是扣子这类低代码平台，更要克制，平台把多 Agent 入口做得太顺滑，很容易让你误以为“加一个 Agent 就能加一分能力”。实际上每次多一个 Agent，你就多了一条需要排查的链路。先让单 Agent 跑通，再用日志数据证明瓶颈出在“角色冲突”上，再拆也不迟。

2.2 决策二：模型选型先算 token 账，别只看跑分

很多新人对“AI Agent token 是什么意思”有疑问。你可以把 token 理解为模型处理文本的最小单位，一个中文汉字大约对应 1 到 2 个 token，一段千字文章大约是一千多 token。模型每次调用都会消耗输入 token 和输出 token，输入 token 是丢给模型的全部内容，输出 token 是模型吐出来的内容。Agent 循环跑 N 轮，就是把“每轮的输入 token + 输出 token”累加起来。

这里有个容易被忽略的事：Agent 的 Token 消耗不是一次性的，而是循环累积的。假设一次任务要调用模型五次，每次输入两千 token、输出五百 token，那一次任务就是一万两千五百 token。如果每次都把完整历史带进去，这个数字会随着任务步骤增长。所以模型选型时必须算账：你的任务平均要循环多少轮、每轮保留多少上下文、预期日调用量是多少，用这些数字去对比模型价格。你不能只因为某模型跑分高就选它，否则成本会失控。

具体账可以这样算：设定每个会话平均 5 轮，每轮输入和工具返回共 3000 token，输出 800 token，一个会话就是 19000 token。日活一万个会话，就是 1.9 亿 token。按当前主流商用模型的价格，这已经是一笔很大的开销了。所以生产级 Agent 必须做上下文压缩，甚至给不同任务分配合适的模型：简单意图用小模型，复杂推理才上大模型。

2.3 决策三：工具协议选 function calling 还是 MCP，别被概念带偏

工具要暴露给模型，必须有一个协议层。目前最主流的是 OpenAI 的 function calling，它通过 JSON Schema 描述工具入参，模型在需要调用时返回一个结构化的 function call 对象，你的代码再解析它、执行本地函数、把结果塞回消息列表。这套机制已经成了事实标准，LangChain、LlamaIndex 都支持。

MCP（Model Context Protocol）是最近很热的协议，它更像一套标准化客户端-服务器协议，目标是让工具、数据源能以统一方式接入不同模型和框架。它的价值在于生态互通：一个 MCP 服务可以被多个 Agent 框架复用。但工程上我不会为了追新立刻全面切 MCP。如果你的 Agent 是内部闭环、工具就七八个 HTTP 接口，直接定义 JSON Schema 就够；如果团队有多个 Agent 项目，或者要接入第三方工具生态，MCP 才值得考虑。切换的成本不只是代码改造，还有调试链路的复杂度增加：原来一个模型工具调用报错直接看函数日志，现在要查 MCP Server 日志。

工具协议还有一个关键点：描述质量。同一个工具，描述写成“获取天气”和“根据经纬度获取指定城市的实时天气，入参需使用城市拼音全称”会让模型调用的准确率差别很大。模型在选工具时是在做语义匹配，描述里必须包含触发场景、必填参数、参数格式约定，最好附一个或两个典型示例。

2.4 决策四：记忆放在对话窗口、摘要还是向量库，分场景定

记忆方案是 Agent 工程里最容易拍脑袋的模块。我见过最偷懒的做法是所有历史消息原封不动全部塞给模型，直到打爆上下文窗口；也见过最折腾的做法，不管什么场景先建向量库，把所有对话记录嵌入进去，最后检索质量一团糟。

正确的姿势是先分类型。短期记忆服务当前任务，必须保证模型能“记得住”前几步做了什么，放对话窗口最直接；但当对话轮数变多，就得做裁剪，把早期多轮对话压缩成摘要，只保留最近两三轮的原文。长期记忆服务跨会话，比如用户偏好、历史订单信息，这些数据通常结构化程度较高，放在数据库按用户 ID 查询可能比向量检索更准。向量库只适合非结构化语义检索，比如“从历史文档里找出和当前问题相似的内容”，而不是所有记忆的默认方案。

这里还要提一个技巧：上下文压缩不能等快爆了才做。Agent 每循环一次，都要检查当前对话窗口的 token 占用。超过了阈值，就把早期消息转成摘要，用“用户名说：要预订周五的机票，已在周三确认出票”这种高度压缩的句子替换掉完整对话。压缩后的摘要也参与下一次循环，这样模型既不会丢关键信息，又不会让字节数无限膨胀。

2.5 决策五：状态机是 Agent 工程的底盘，框架只是辅助

Agent 循环本质上是一个状态机：有初始状态、中间状态、终止状态，每轮模型输出触发一次状态迁移。很多团队忽略状态管理，直接把 while 循环写到流程里，结果一旦需要断点续跑、人工介入、超时恢复，代码就纠缠成一团。

我自己更推荐把“状态”显式建模，不管用不用框架。至少要定义清楚：会话 ID 用于隔离不同用户的任务、当前节点位置决定模型下一步能做什么、已收集的工具结果、要传给下一轮的消息列表、任务终止条件。把这些状态字段放进一个结构体或者数据库记录里，Agent 循环每次从状态里恢复现场，而不是靠一堆全局变量。

用 LangGraph 这类框架能省很多事，它把状态迁移变成一张图，节点和边都是显式声明的。但我提醒一句，别把图铺得特别大再开始写代码，先画一条主干：接收输入 → 调用模型 → 执行工具 → 判断是否结束 → 更新状态。跑通主干以后，再往上面加条件分支和回退逻辑。框架的作用是降低状态管理的门槛，不是替你决定流程怎么设计，流程依然要靠业务逻辑来定。

2.6 决策六：并发瓶颈不在模型，在状态隔离

“AI Agent 怎么扛并发”是最近被问烂的问题。先说结论：模型调用本身是天然并发的，你发多少个请求都行，真正的瓶颈在于会话状态能不能隔离。

假如你用全局变量保存每个 Agent 的中间状态，那并发一多必然串号；假如你用单线程 while 循环跑任务，那一个慢任务会堵住后面所有请求。正确的做法是：把 Agent 的每次任务包装成一个可独立运行的工作单元，这个单元内包含独立的上下文、工具调用记录、状态数据。不同任务之间完全不共享可变数据，只共享工具和配置。在 Python 里可以用 asyncio 做协程并发，也可以用 Celery 这类任务队列把任务丢给多个 Worker 执行。

一个容易遗漏的点是长任务与短任务的处理差异。如果 Agent 任务普遍在十几秒内完成，用同步接口等结果就行；如果任务经常要一两分钟甚至更久，客户端等不了，就要改成异步任务模式：接口立即返回任务 ID，执行完通过 Webhook 或轮询通知结果。这件决策要在架构初期定下来，不然后面改接口语义会牵动所有调用方。

2.7 决策七：没有评估体系，Agent 就无法迭代

很多团队把 Agent 上线之后就开始摆烂，因为不知道什么叫“好”，什么叫“不好”。传统的离线指标只能衡量单轮回答的准确性，而 Agent 是过程性的：工具选择对不对、步骤顺序对不对、纠错能力好不好、最终结果完整度如何，这些都需要一套评估体系。

我的做法是先建评测集，收集三四十个典型业务场景，每个场景标注标准答案和关键过程要求。每次改提示词、换模型、改工具描述，都用同一批场景跑一遍，记录成功率、平均轮数、Token 消耗、工具调用准确率。不求每次都有提升，但必须知道变化方向。没有这套基线，你连“这次改动是变好了还是变坏了”都判断不了。

评估还有一个容易忽略的维度：失败模式。你要知道 Agent 在什么条件下会失败，是工具调用格式出错、上下文溢出，还是模型产生了幻觉步骤。把失败样例收集起来，每周过一遍，这比看任何跑分都有价值。因为生产环境的问题很少是模型能力不够，更多是边界情况没兜住。

3. 实操：用 FastAPI + LangGraph 落地一个能扛并发的 Agent 服务

3.1 为什么用 FastAPI 和 LangGraph 搭骨架，什么时候不选它

如果你的技术栈是 Python，FastAPI 配合 LangGraph 是目前我比较推荐的生产级组合。FastAPI 负责对外提供 HTTP 接口，它原生支持 async，天然契合 Agent 这种大量 I/O 等待的场景；LangGraph 负责 Agent 的状态机和节点编排，把前一节讲的决策点落成代码。

经常有人问，能不能用 Rust 写 Agent？可以，Rust 的优势是并发性能好、内存占用低，适合做高吞吐的基础设施层，但 Agent 生态里的工具链和框架还是 Python 更成熟，团队维护成本也低。另外如果团队是 Java 背景，Spring AI 也可以，但它的生态和 RAG、工具协议丰富度目前和 Python 社区还有差距。我的建议是别被语言性能绑架，Agent 的瓶颈在模型调用和状态设计，不在那几毫秒的语言开销。

下面的例子我故意把代码写得偏薄，没有堆砌框架 API，重点是展示“状态、工具、循环、并发”这四个核心怎么组织。你拿到手以后可以按自己的业务替换工具函数和状态字段。

3.2 先定义状态和工具，让模型知道它能做什么

第一步是定义 Agent 会话状态。用 TypedDict 做类型声明，LangGraph 会把它当成状态容器，每次节点返回会更新对应字段。

from typing import Annotated, TypedDict from langgraph.graph import StateGraph, END from langgraph.graph.message import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages] session_id: str task_done: bool result: str

messages 用 add_messages 注解，LangGraph 会自动把新消息追加进去，省去手动拼接历史。session_id 用来隔离不同用户的任务，task_done 是终止标志，result 存最终答案。

工具函数定义在另一个模块里。这里拿一个“查询订单状态”的工具做例子，实际项目中改成查数据库、调内部 API 都行。关键是给函数写清楚 docstring 和参数注释，模型会拿这些描述去匹配工具。

def query_order_status(order_id: str) -> str: """ 根据订单号查询订单的当前状态。 订单号格式：ORD-2025-XXXX。 返回结果包含订单状态、物流公司和最新节点。 """ # 这里模拟一次数据库或接口调用 data = {"ORD-2025-0001": "已发货，顺丰速运，预计三天内到达"} return data.get(order_id, "未查询到该订单，请检查订单号是否正确")

工具描述里写了订单号格式，能显著减少模型传参错误。这一步花两分钟，效果比换更强的模型明显得多。

3.3 把循环写成图：Agent 的四个节点

LangGraph 里 Agent 循环通常拆成四个节点：

• call_model：把当前消息列表发给模型，请求工具调用或最终回答。
• execute_tools：如果模型返回的是工具调用，执行对应函数。
• check_finish：判断任务是否该结束。
• build_final_answer：组装最终结果写入 state。

核心代码如下。

from langchain_openai import ChatOpenAI from langchain_core.tools import tool @tool def query_order_status_tool(order_id: str) -> str: """根据订单号查询订单的当前状态。订单号格式：ORD-2025-XXXX。""" return query_order_status(order_id) tools = [query_order_status_tool] llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) llm_with_tools = llm.bind_tools(tools) def call_model(state: AgentState): response = llm_with_tools.invoke(state["messages"]) return {"messages": [response]} def execute_tools(state: AgentState): last_message = state["messages"][-1] if hasattr(last_message, "tool_calls") and last_message.tool_calls: results = [] for tc in last_message.tool_calls: fn = globals()[tc["name"]] result = fn.invoke(tc["args"]) results.append( ToolMessage(content=str(result), tool_call_id=tc["id"]) ) return {"messages": results} return {"messages": []} def check_finish(state: AgentState): last_message = state["messages"][-1] if hasattr(last_message, "tool_calls") and last_message.tool_calls: return {"task_done": False} return {"task_done": True, "result": last_message.content}

然后把这些节点组装成图。

graph = StateGraph(AgentState) graph.add_node("call_model", call_model) graph.add_node("execute_tools", execute_tools) graph.add_node("check_finish", check_finish) graph.set_entry_point("call_model") graph.add_edge("call_model", "execute_tools") graph.add_edge("execute_tools", "check_finish") graph.add_conditional_edges( "check_finish", lambda state: "call_model" if not state["task_done"] else "final", {"call_model": "call_model", "final": END} ) app = graph.compile()

这个图表达的逻辑是：模型输出后如果有工具调用，就执行工具，再把工具返回结果追加进消息，然后回到模型节点继续决策；如果没有工具调用，说明任务完成，直接返回结果。这样就是一个完整的 ReAct 循环。

跑一个简单调用。

initial_state = { "messages": [{"role": "user", "content": "查一下 ORD-2025-0001 到哪了"}], "session_id": "u-001", "task_done": False, "result": "" } output = app.invoke(initial_state) print(output["result"])

3.4 并发与上下文压缩：两个必须处理的工程点

先看并发。FastAPI 天然支持 async，把 Agent 调用放进 async 接口里，可以同时服务大量请求。但这里有一个坑：LangGraph 的 invoke 是同步阻塞的，直接放在 async 接口里会卡住事件循环。解决办法是用 asyncio.to_thread 把阻塞调用丢到线程池。

from fastapi import FastAPI import asyncio app = FastAPI() @app.post("/agent/run") async def run_agent(request: AgentRequest): initial_state = { "messages": [{"role": "user", "content": request.query}], "session_id": request.session_id, "task_done": False, "result": "" } result = await asyncio.to_thread(app.invoke, initial_state) return {"status": "ok", "result": result["result"]}

这样单机就能扛住不错的并发量。如果一台机器不够，下一步不是优化代码，而是把任务丢到 Celery/RQ 队列，多个 Worker 横向扩展。要注意，一旦上了任务队列，接口语义就要从“同步返回结果”改成“返回任务 ID + 客户端轮询/Webhook”，因为 Worker 执行是异步的。

再看上下文压缩。假设工具返回结果很长，Agent 反复循环几轮后 Token 消耗会暴涨。我采取的策略是：在 call_model 之前，先检查 state 里的消息总 token 数，超过阈值就把最老的消息压缩。这里给出一个极简实现，实际项目中可以用 LangChain 的 summarize 工具或自定义摘要节点。

def maybe_compress(state: AgentState, max_tokens: int = 4000): total = estimate_tokens(state["messages"]) if total <= max_tokens: return state head = state["messages"][:2] # 保留系统提示和最早一条用户消息 tail = state["messages"][-4:] # 保留最近两轮对话 summary = summarize_messages(state["messages"][2:-4]) state["messages"] = head + [summary] + tail return state

compress 之后塞进 call_model 之前调用。注意 summary 必须本身是一段可以被模型理解的消息，而不是给开发人员看的记录。把历史消息总结成“用户想预订周五的机票，已对比三个航班，倾向上午出发”，模型读到这段信息，就能继续后续任务。这个技巧能把一个长任务的 Token 消耗压掉一半以上，而且对最终结果影响很小。

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

4.1 高频翻车问题速查表

下面这张表是我在维护多个 Agent 服务时积累的，每个问题都配了排查方向。

4.2 三次实战排查过程还原

第一次翻车是在线上跑了一个自动写摘要的 Agent，用户反馈“回答越来越啰嗦”。看了完整 trace 发现，系统把前几轮生成的长摘要又当输入喂给了模型，模型基于摘要再生成摘要，内容不断膨胀。解决方案是把中间摘要单独存放，不进入下一轮消息列表，模型每次只基于原始材料生成。

第二次是并发压测时出现了串号，两个用户的订单状态互相写错了。定位后发现在早期原型里，为了图方便用了模块级 dict 存状态，后来接入 FastAPI 也没改。排查过程花了一晚上，原因是问题只在并发高时才偶发，单条请求复现不了。最终把所有状态改成显式传入 LangGraph 的 state，问题消失。

第三次是模型在工具调用返回后仍然重复调用同一个数据库查询。原因是工具返回“查询成功，共 3 条记录”，模型看到数据格式是列表，认为还要再查一次“完整详情”，而完整详情接口并不存在。我在工具描述里显式写明“这是唯一可用的查询接口，返回结果已包含全部字段”，同时在图上加了最大循环次数为 6 的熔断。从那以后，同类问题再也没有出现。

这三起案例都在印证一件事：Agent 的多数故障不是模型不够聪明，而是状态管理、上下文组织、工具描述这些工程细节没做到位。每一个问题都能在七要素和七个决策点里找到对应位置。排查的顺序也应该是固定的，先看状态对不对，再看上下文有没有污染，最后才怀疑是模型能力问题。

最后再分享一点个人经验。如果你现在准备从零开始做一个 Agent 项目，我的建议是先把第一天要做的事情列成四行：定义好状态结构、定义好工具函数和描述、确定终止条件、确定评测集。四件事做完，再开始搭 LangGraph 或直接写循环。这四件事里任何一件没想清楚，后面都会以翻车的形式来找你。我踩过这些坑，希望你少踩几个。