企业官网建设流程全解析

1. 为什么"能跑通 Demo"离"能上线"还差着十个 Sprint

今年做应用层的团队几乎都在聊 AI Agent，框架也越出越多：LangGraph、AutoGen、CrewAI、Spring AI，甚至 Rust 社区已经有人拿 tokio 手搓 Agent 运行时。但一个特别典型的现状是：教程收藏了一堆，Demo 照着跑通了，一说到"我要把它做成一个能扛住真实用户请求的服务"，立刻卡壳。问题通常不在模型能力，而在工程决策——上下文怎么管、状态放哪里、工具调用失败了怎么办、并发一上来为什么全乱了。这篇文章想把 AI Agent 从概念到工程实现这条路上的坑整理成一张检查表：先把 Agent 拆成七个要素，再把从原型到生产必须做的取舍收敛成七个决策点。对想从零搭 Agent、或者要在现有系统里集成 Agent 的工程师来说，这份梳理应该能帮你省下不少试错时间。

1.1 一张检查表：七要素是什么，七个决策点又是什么

先直接给结论。七要素指的是一个完整 Agent 系统的七个组成部分：大模型（作为推理核心）、任务规划（目标拆解与步骤编排）、记忆（短期会话与长期知识）、工具（对外部能力的封装）、行动（真正执行某个操作）、观察（收集执行后的反馈）、循环控制（决定什么时候进入下一步、什么时候停下）。七个决策点则是我把 Agent 从 Demo 推向生产时总结出的关键取舍：编排模式、模型路由、上下文策略、记忆落点、工具契约、循环边界、可观测性。两者是不同维度的东西：七要素回答"它由什么构成"，七个决策点回答"每一步具体怎么做"。前者帮你理解 Agent，后者帮你实现 Agent。

我用一个生活化的类比帮你建立整体印象。Agent 就像一个刚入职的员工：大模型是他的大脑，负责思考和判断；任务规划是他手上的工作清单；记忆是便利贴加资料柜；工具是他的双手，用来操作电脑、调用系统、发邮件；行动是真正把手伸出去干活；观察是干完活之后检查结果；循环控制则是项目经理定的规矩——最多干几轮、干到什么程度必须停下来问人。这个员工如果只有大脑没有规矩，迟早会把公司折腾到预算爆炸。工程实现的核心，就是把每个环节都变成有边界、可观测、能收敛的代码。

2. 七要素拆解：Agent 不是"模型加提示词"那么简单

很多人第一次搭 Agent 时的想法是"一个循环里反复调用大模型，让它自己决定调用哪个函数"。这个理解方向没错，但过于粗糙。真正做工程时，每一个要素都有独立的处理方式，也有各自容易翻车的地方，越早看清越少踩坑。

2.1 大模型与任务规划：谁来思考，思考到什么粒度

大模型是 Agent 的核心推理部件，但很多团队会误以为"所有环节都上最强模型就行"。实际项目里我会把思考拆成两个层次：第一层是规划层，负责把用户目标拆成可执行的子任务；第二层是执行层，负责在具体步骤中推理"该调什么工具、怎么理解工具返回的结果"。规划不一定每轮都做。如果任务链条是固定的（比如查天气、看建议、生成穿搭文案），完全可以用工作流把流程写死；只有任务高度开放（例如"帮我调研这个行业近一年的动态"）才需要模型在每个步骤之间自主规划。

规划粒度也要克制。模型很容易把"写周报"拆成"列出项目、收集 git 记录、总结变更、生成草稿、检查格式"五步，但每一步本身可能又是一个复杂任务。如果不给每一步限定输入输出边界，整个 Agent 会在拆解上浪费大量 token。我的做法是：有确定性流程的任务先人工梳理成步骤，把规划权交还给代码；只有真正开放的任务才让模型自由规划，同时给它限定"思考深度最多两层"。规划结果出来后还应该做一层校验，模型可能拆出当前系统里根本执行不了的步骤，比如它规划了"访问内部系统 A"，但你的 Tool 列表里根本没有这个能力，这类情况要在规划阶段就拦截。

2.2 记忆：哪些该记住，哪些该扔掉，存在哪里

记忆是 Agent 工程里最容易被轻视的环节。七要素里的记忆要拆成短期和长期两个层面：短期记忆就是当前会话的上下文，通常表现为 message 列表，用户每次请求都要带着它；长期记忆是跨会话的知识，比如用户偏好、业务知识、历史决策，一般落到向量库或普通数据库。

关键教训是：不是所有记忆都值得保留。日志型内容（某次工具返回的网络耗时、某一步推理的中间草稿）塞进上下文只会污染模型注意力。我会给记忆打上标签：关键决策进入长期记忆，过程细节只存在当前会话，工具结果只留结论不保留原始返回。记忆读取长度也要控制，长期记忆检索回来的内容要做重排序和抽取，不能让模型对着二十条相似的旧记录推理。用通俗的说法：短期记忆是手上便利贴，长期记忆是办公室资料柜，便利贴贴满整面墙，就找不到真正有用的那张了。市面上常见的做法是把历史消息全部塞进 prompt，早期 Demo 这么做没问题，一旦会话超过 20 轮，token 消耗和模型注意力都会告急，这就是上下文策略要解决的矛盾，后面讲决策点时再展开。

2.3 工具与行动：让模型安全地碰到真实世界

工具是 Agent 和外部世界之间的握手协议。模型本身不执行任何操作，它只能通过函数调用机制表达意图："我要调用 get_order_status，参数是 order_id=12345"，真正执行动作的是你的代码。工具要被模型正确使用，必须满足三件事：名字足够说明用途、描述写明边界和前置条件、参数 Schema 严格定义。举个例子，一个"删除用户"工具，描述里必须注明"仅限管理员，且用户无未完成订单时可删除"，否则模型可能在用户抱怨"想注销账号"时真的调用删除接口。

行动层的工程实现同样容易被低估。工具入参要做校验，输出要做裁剪，超时要单独设置，调用失败要把错误信息整理成模型能理解的文本回传，而不是直接抛异常。我见过大量 Agent 在工具报错后进入无意义自我解释，原因就是错误信息没有结构化，模型根本不知道发生了什么。工具返回的原始数据也需要控制体积，比如一次数据库查询返回几百行，直接塞进上下文既浪费 token 又干扰判断，正确的做法是只给模型返回提炼后的结论和关键字段，原始数据存到临时存储里供后续步骤检索。

2.4 观察与循环控制：闭环收敛的最后一道闸门

观察是这个闭环的燃料。工具执行完，结果必须经过解析、提炼、标准化，再回到模型面前。观察层要做一次"转译"，把原始结果转成"任务相关结论 + 关键字段 + 可选原始数据引用"。这一步不做，Agent 就像一个人拿到了三百页的报告却不告诉他重点在第几页，推理质量完全随机。

循环控制则是整台机器的刹车系统。一个完整的 Agent 循环通常包括：模型决定调用工具、执行工具、观察结果、再次调用模型、再执行……直到模型认为任务完成。这个循环必须有硬性边界：最大迭代步数、单步超时、全局 token 预算、关键操作的人工审批节点。没有刹车，Agent 遇到模糊指令或工具故障时会在循环里空转，账单膨胀速度远超想象。我自己的习惯是：所有会修改外部状态的动作（发邮件、下单、转账、删除数据）必须加人工确认；只读类工具允许自动执行，但同样要设步数上限。这条原则已经帮我挡住了很多次线上事故。

3. 七个决策点：从上线的角度重新审视 Agent 的每一步取舍

七要素讲完，你对 Agent 有了结构化认知。但真正构建 Agent 服务时，难点在于每一项都有多种实现方式，没有任何一种组合是万能的。我在项目里反复做过的七个决策点，每一个都交过学费，下面按实际决策顺序讲。

3.1 决策点一二：编排模式与模型路由，先定骨架再定大脑

编排模式是 Agent 的骨架，决定它是走固定流程还是自由发挥。主流选择有三种：纯工作流、自治 Agent、图编排。区别可以直接看对比：

图编排是我在多数项目里的默认选择，LangGraph 这类框架允许你把确定性步骤写成固定节点，把需要判断的分支交给模型决策，既保留了效率，又不会完全失控。模型路由解决"哪一步该用哪种模型"的问题：意图识别、实体抽取、标题分类这类高频小任务，完全可以用便宜的轻量模型；多步推理、复杂生成才需要上强模型。这两者的成本可能差一个数量级，路由方式可以是规则、可以是一个便宜模型快速判断、也可以是对历史数据的统计。日常对话先分类，再决定走哪个 Agent 分支，这就是最基本的模型路由。

3.2 决策点三四：上下文策略与记忆落点，管理好每一寸 Token

上下文窗口不是无限可用的，即使模型支持 200K token，也不代表真的该把 200K 全塞进去。超过一定长度，模型对中段内容的注意力会明显下降，这就是常说的 lost in the middle。我常用的组合策略有三种：截断（保留最近 N 条消息）、摘要（每隔几轮把旧消息压缩成一段总结）、压缩（用一次轻量模型调用把冗长工具输出提炼成要点）。注意上下文策略要在会话层面执行，不是在单次请求层面执行，所以你还需要一个地方保存会话的"压缩后状态"。

这就引出了记忆落点选择。记忆落点是一个从简单到复杂的递进：单机 Demo 用进程内字典就行；正式服务至少把会话状态放到 Redis，设置好 TTL；跨用户共享的业务知识放数据库；需要语义检索的放向量库。最容易翻车的是用一个全局变量存所有人的状态——并发一上来，用户 A 的消息就出现在用户 B 的 Agent 里，这是我真实踩过的坑。向量库负责长期记忆时还要考虑 embedding 成本和召回质量，知识更新策略也很关键，旧数据不清理会让召回结果越来越偏。记忆落点选型看起来只是存储问题，实际决定了系统能否水平扩容，所以值得在架构阶段多花点时间。

3.3 决策点五六：工具契约与循环边界，别让 Agent 变成脱缰野马

工具契约是 Agent 工程里最容易被低估的细节。模型通过函数调用选择工具，本质上是在做结构化输出。工具的名字、描述、参数 Schema 若不清晰，模型就会填错参数或选错工具。我给每个工具设计接口时都会做三件事：参数严格校验（类型、范围、枚举值）；工具返回统一数据结构（status、data、error）；工具内部任何异常，都要在进入模型上下文之前转换成一段模型能看懂的说明，例如"查询订单失败：订单号不存在，请确认后重试"，而不是抛一个堆栈。

循环边界决定 Agent 的失控上限。我见过最贵的一次事故，是测试环境里 Agent 在循环里连续调了 80 次搜索工具，因为每次关键词都差一点，几分钟烧掉数万 token。那次之后，max_iterations、单步超时、总 token 预算成了所有 Agent 项目的强制配置。如果涉及交易类动作（比如有人问能不能用个人 AI Agent 做期货交易），边界和人工审批更是底线，没有熔断机制和人工确认就上线，那不是 Agent 项目，是事故预告。循环边界的数值没有黄金标准，按业务估算：一个检索任务通常 3 到 5 步内能收敛，超过就该怀疑 Agent 卡住了，宁可主动询问用户也不要硬跑下去。

3.4 决策点七：可观测性，没有追踪的 Agent 等于盲飞

Agent 是黑盒中的黑盒：模型为什么选了 A 工具而不是 B 工具？中间经历了哪几步？哪一步开始偏离预期？只看最终输出完全判断不了。可观测性必须成为工程的一部分。我现在做 Agent 项目至少会做三件事：第一，每一轮 ReAct 的输入输出（用户消息、模型思考、工具调用、工具结果）完整记入日志；第二，记录每轮 token 消耗和累计消耗，定位成本失控；第三，接入 OpenTelemetry 或 Langfuse 这类追踪工具，把一次用户请求的完整链路串起来。

评测集也要同步建。跑通不代表可用，把 20 条典型用户请求固定下来，每次改 Prompt、换模型、调工具描述之后都跑一遍回归，能拦截掉大部分隐性劣化。可观测性的价值在于：Agent 的能力边界是靠观察和评测磨出来的，不是靠一次上线定出来的。你只有知道每一步实际发生了什么，才有资格说这个 Agent 是"可控"的。

4. 并发与生产化：当"AI Agent 怎么扛并发"成为真问题时

"AI Agent 怎么扛并发"这个问题很常见，背后通常是三类情况：Demo 只服务一个人，稍微多人用就卡；模型调用是秒级耗时，同步框架明显撑不住；状态管理没做隔离，多个用户互相串台。先给结论：Agent 的并发瓶颈通常不在模型 API 的裸调用，而在状态管理和任务调度方式。

4.1 瓶颈不在模型 API，而在会话状态的管理方式

Agent 的一次请求不是单次问答，而是多轮循环，中间可能有多次模型调用和工具调用。这意味着服务端必须为每个会话维护一份独立状态：当前上下文、已执行步骤、剩余步数、临时中间结果。很多"扛不住并发"的现场，其实是共享了同一个状态，导致请求互相干扰，表现为响应内容串味、工具参数张冠李戴。正确做法是按 session_id 隔离状态，所有上下文变量从 session 维度存取，Agent 的编排逻辑保持无状态以便水平扩容，会话数据统一放 Redis。

我上线第一个 Agent 服务时就在这个点翻过车：用了模块级字典存上下文，单用户测没问题，压到 20 并发时用户之间开始互相看到对话历史。排查半天才锁定是共享变量，改成 Redis 存储后立刻恢复。如果你用 FastAPI 这类异步框架，请求处理本身不是瓶颈，真正的压力在模型 API 的并发连接数和下游工具限流。状态存内存只适合单机开发，多人协作或生产环境一定要能在独立存储里按会话维度恢复。

4.2 限流、队列与异步：分布式系统三板斧在 Agent 里的用法

Agent 服务本质上是 IO 密集型，瓶颈落在等待模型响应和工具响应上。我会做三层保护：第一层异步化，请求进来直接丢给异步任务处理，不阻塞线程；第二层信号量限流，控制同一时刻打到模型 API 的请求数量，超过阈值排队等待；第三层任务队列，对耗时长任务先落队，由 Worker 消费，前端通过轮询或 WebSocket 拿结果，避免请求长期占用连接。

并发量估算可以直接套公式：并发槽位数 = QPS × 平均处理时长。假如每个 Agent 任务平均耗时 10 秒，目标是稳定承接 5 QPS，那系统里同时存在的任务就有 5 × 10 = 50 个，也就是至少需要 50 个并发处理插槽，否则必然排队。很多 Demo 挂在同步线程模型下，不是因为代码差，而是没意识到 Agent 的"一次请求"相当于传统接口的好多次内部调用。模型 API 的限流也很重要，如果不做保护，一个用户的多轮循环就能把供应商的配额打满，其他用户全部受影响。

4.3 Python、Rust、Java：框定并发问题的边界，而不是争论语言

围绕 Rust 写 Agent 还是 Java 的 Spring AI 这类讨论，我的观察是：选什么语言取决于你要解决哪一层的问题。做高并发的调度网关，Rust 的 async 模型和低资源占用有优势，但 Agent 编排生态相对早期；在企业内部做 Agent 集成，Java 技术栈加 Spring AI，与内部系统做事务、权限、审计集成会很顺畅；快速迭代 Agent 逻辑并最大化复用社区框架，Python 仍是最稳的选择。工程上更务实的做法是分层：变化快的 Agent 编排层用 Python、稳定且性能敏感的状态层和网关层用 Rust 或 Java 补齐，两层间用标准协议通信。语言之争没有意义，先跑起来再在瓶颈处局部替换即可。

5. 从决策到代码：一个几乎可以照抄的最小 Agent 骨架

最后给一套我实际在用的最小落地组合，以及能直接改的骨架代码。技术栈是 FastAPI + LangGraph + Redis + 向量库（可选项），这套组合覆盖了前面几个关键决策：FastAPI 提供异步 Web 入口，LangGraph 提供带控制的编排能力，Redis 存会话状态，向量库存长期记忆。如果你团队已经选了 Rust 或 Java 生态，决策逻辑完全一致，换成对应语言的库就行。

5.1 FastAPI + LangGraph + Redis + 向量库：为什么是这个组合

选这套不是因为新，而是每个组件都恰好解决一个问题。FastAPI 天然异步，符合 Agent 请求的 IO 特性；LangGraph 把流程描述成节点和边的图，既能写死步骤，也能在指定节点上让模型自主决策，是当前少有的兼顾可控与灵活的编排层；Redis 的 TTL 和数据结构能力适合短期会话状态；向量库负责承接跨会话知识检索。比起动不动就引入整套框架，我更建议只取需要的部分，依赖越少，升级时互相打架的概率越低。如果你刚开始，可以不接向量库，先用 Redis 存一段 JSON 当"记忆"，跑通核心循环后再升级。

5.2 一个最小 Agent 的骨架代码与关键注释

下面这个骨架实现了一个简单的"订单查询 Agent"：用户问订单状态，Agent 判断需要调用 get_order_status，拿到结果后生成回答。代码里对应了前面几个关键决策：状态按 session 隔离、工具错误结构化回传、循环步数受限、每步记录日志。真实接入时把模型客户端和业务工具替换进去即可。

# main.py：FastAPI 入口 + LangGraph 编排的最小骨架 import json from typing import TypedDict from fastapi import FastAPI from langgraph.graph import StateGraph, END import redis app = FastAPI() r = redis.Redis(host="localhost", port=6379, decode_responses=True) TOOLS = { "get_order_status": { "description": "根据订单号查询订单当前状态，适合回答物流、发货类问题", "parameters": { "order_id": { "type": "string", "description": "用户提供的订单号" } } } } class AgentState(TypedDict): messages: list # 当前会话消息 order_id: str | None # 本轮提取出的订单号 remaining_steps: int # 剩余步数，对应循环边界决策点 def route(state: AgentState): # 判断是否继续：没有工具调用就收尾，步数用尽强制结束 if state["remaining_steps"] <= 0: return END last = state["messages"][-1] if last.get("tool_calls"): return "call_tool" return "respond" def call_model(state: AgentState): # 这里调用 LLM，按决策点二路由到合适的模型 # 响应格式需要包含是否有 tool_calls 参数 ... def call_tool(state: AgentState): # 执行 get_order_status，异常转成结构化文本回传 ... def respond(state: AgentState): # 生成最终回答给用户 ... # 构建图：call_model -> (route) -> call_tool 或 respond graph = StateGraph(AgentState) graph.add_node("call_model", call_model) graph.add_node("call_tool", call_tool) graph.add_node("respond", respond) graph.set_entry_point("call_model") graph.add_conditional_edges("call_model", route) graph.add_edge("call_tool", "call_model") graph.add_edge("respond", END) chain = graph.compile() @app.post("/chat") async def chat(session_id: str, user_message: str): # 按 session_id 从 Redis 恢复或初始化状态 raw = r.get(f"session:{session_id}") if raw: messages = json.loads(raw) else: messages = [{"role": "user", "content": user_message}] initial_state = { "messages": messages, "order_id": None, "remaining_steps": 5, } result = chain.invoke(initial_state) r.setex(f"session:{session_id}", 3600, json.dumps(result["messages"])) return {"reply": result["messages"][-1]["content"]}

列出的 api 只是一个最小语义，实际项目中你还需要接真实的模型客户端、工具执行逻辑和异常处理。但核心思想已经完整：状态从 Redis 进出、工具错误不能裸抛、步数必须封顶。这三点保证了即使模型决策异常，服务也不会被打穿。

5.3 上线前按这份清单过一遍，能省一半的线上事故

最后是我每次上线 Agent 前都会过的检查清单，不是全都要上，但标记"必选"的别省：

• 循环边界：max_iterations 是否设置？单步是否有超时？（必选）
• 工具契约：工具参数是否校验？错误是否结构化回传？返回是否裁剪？（必选）
• 上下文策略：长会话是否走摘要或截断？工具返回是否提炼？（必选）
• 记忆隔离：会话状态是否按 session_id 隔离，并存在 Redis 之类的外部存储？（必选）
• 成本控制：每轮和累计 token 是否有日志与告警？（必选）
• 并发保护：模型 API 是否限流？长任务是否走队列？（强烈建议）
• 人工确认：发邮件、下单、删除等敏感动作是否有审批节点？（按业务定）
• 回归测试：是否有一组固定测试用例，改 Prompt 或模型后自动跑一遍？（强烈建议）

这套清单是从我自己的事故里攒出来的，尤其是循环边界和工具错误处理，几乎九成线上事故都能归到这两类。先把骨架跑通，再按清单过一遍，再想功能扩展。Agent 工程实现这件事，做到"能收敛、能观测、可回溯"，就已经比大多数 Demo 级项目往前迈了一大步。