企业官网建设流程全解析

做了这么多年后端和系统设计，我一直有个固执的判断：AI Agent 真正难的不是“能跑通”，而是“能稳定地跑业务”。你可以两天搭出一个 demo，但要让它在生产环境里扛并发、不出错、可回溯、能停得住，背后是一整套工程问题。这篇文章想做的就是一件事：把 AI Agent 拆开。先拆成七个要素，回答“一个能落地的 Agent 由什么构成”；再拆成七个决策点，回答“工程实现时你在每个关键分叉口该怎么选”。这套框架是我踩了无数坑之后沉淀下来的，适合已经有基础概念、正准备把 Agent 从 demo 推进到生产环境的朋友。

1. 七要素拆解：Agent 不是“提示词套壳”

市面上很多对 Agent 的描述都在讲“智能体=LLM+工具+循环”，听起来很轻巧，但做工程的人都知道，概念一旦落到代码里就会长出无数细节。我习惯把 Agent 拆成七个必备要素，每个要素都是一个独立模块，缺一个都会在实际运行中露馅。

1.1 要素一：大模型底座（LLM Core）

大模型是 Agent 的“大脑”，但工程视角下，它更像一个你可以调用的推理服务。你不能只问“哪个模型聪明”，还要看推理成本、响应延迟、上下文长度、是否支持结构化输出。

在 Agent 场景里，我的经验是温度要调低。生成式聊天你可以用 0.8 甚至 1.0 的创造力，但 Agent 的每一步决策都依赖模型按照既定格式输出，温度太高会出现格式漂移。我自己常用 0.1 到 0.3，甚至有些工具调用场景直接设 0，换来的是输出格式的高度稳定。

另一个容易忽略的细节是上下文窗口的“实际可用长度”。很多模型标称支持 128K，但一旦塞满，推理时间会显著变长，费用也会非线性上涨。工程上要做的不是“尽量多塞”，而是“尽量少塞且不丢关键信息”，这是记忆模块的核心使命。

1.2 要素二：规划能力（Planning）

规划是 Agent 区别于普通 RAG 或聊天机器人的关键。它的本质是：面对一个复杂目标，把任务拆解为子步骤，并动态调整执行顺序。ReAct（Reason + Act）是最常见的范式，模型先在 thought 里推理，再调用工具，再根据结果决定下一步；Plan-and-Execute 则更偏向先制定完整计划再逐步执行，适合目标明确的场景。

工程实现中，规划不等于“模型自由发挥”。你需要定义好决策的出口和边界，比如规划结果必须是一个 JSON 数组，每一步必须包含步骤 ID、动作、参数和前置条件。我在很多失败项目里见过同样的问题：模型规划得很漂亮，但每一步都有歧义，代码只能疯狂补 if-else。规划模块的落地核心不是增强推理，而是“约束输出结构”。

1.3 要素三：记忆（Memory）

记忆是 Agent 工程里最容易被低估的要素。我审过不少团队的项目，他们所谓“有记忆”只是把每次对话都塞进 prompt，这是典型的错误姿势。

工程上，记忆至少分两层：

• 短期记忆：当前任务上下文，比如正在处理的工单信息、已执行的步骤。
• 长期记忆：跨会话的知识，比如用户偏好、历史决策、业务规则，通常存进向量数据库，按需检索。

真正难的是“什么该记、什么不该记、何时遗忘”。如果你的 Agent 要做企业级应用，记忆管理还涉及权限和数据合规。我见过一个客服 Agent，因为长期记忆里混入了上一个用户的身份证号，在回答新用户问题时泄露了隐私——这种事故一次就能毁掉一个项目。记忆模块的隔离和权限校验，绝不是可选项。

1.4 要素四：工具调用（Tools）

Agent 的价值在于“能干活”，工具就是它的手脚。工程上要解决的第一个问题是协议：你如何把外部 API、数据库、内部系统暴露给模型。目前业内最主流的是 OpenAI 兼容的 Function Calling 格式，模型输出一个结构化 JSON，里面包含函数名和参数，再由你的代码路由执行。

工具设计里最核心的准则是“每个工具做且只做一件事”。比如你给 Agent 一个函数叫query_user_info(user_id)，就不要让它同时承担修改用户信息的责任，否则模型会困惑。工具的描述也要极其精确，相当于给模型的说明书。我通常会要求团队为每个工具写：

• 功能描述：什么时候用、什么时候别用
• 参数清单：类型、必填、取值范围
• 返回值样例：让模型知道能拿到什么
• 错误约定：什么情况抛错、错误码是什么

1.5 要素五：执行环境（Execution Environment）

Agent 做出决策后，动作在哪里执行？这是纯工程要素，却决定了系统的安全边界。简单场景下，工具函数跑在你的应用进程里；复杂场景下，Agent 可能需要生成代码、操作浏览器、读写沙箱文件系统，这时候就必须引入隔离的容器或子进程环境。

我强调一个在真实项目中反复出现的原则：默认拒绝。Agent 在执行动作时，只允许访问它明确需要的资源，不能给它一个能访问全库的数据库账号。也许你会觉得 Agent“聪明”，知道什么不该做，但在面对 prompt injection 攻击时，模型可以被诱导去执行危险操作。执行环境就是把安全边界落到基础设施层面，而不是赌模型的判断力。

1.6 要素六：反馈与评估（Feedback & Evaluation）

没有评估体系的 Agent 项目，就像没有测试的软件项目，迟早出事。但 Agent 的评估比传统软件复杂得多，因为它输出的是自然语言，没法简单地断言“对或错”。

我的做法是把评估分为三层：

• 单步评估：每一步决策的格式是否正确，工具参数是否合法
• 整体评估：任务的最终结果是否达成，用 LLM-as-a-Judge 或规则检查
• 回归评估：维护一个标准评测集，每次改模型或 prompt 后全量跑一遍，防止优化 A 问题破坏 B 能力

没有评测集的 Agent 项目，我一般建议不要上线。这不是保守，而是因为你根本无法回答“它最近变好了还是变坏了”。

1.7 要素七：安全与护栏（Safety & Guardrails）

最后一个要素，也是 Prompt Injection 风险高发的重灾区。Agent 在工具调用过程中会接触外部输入——网页内容、用户消息、API 返回值，这些内容里可能藏着恶意指令，试图劫持 Agent 的决策。

护栏要从两层入手：一是输入侧的过滤层，比如对工具返回内容做敏感词检查和指令检测；二是输出侧的约束层，比如禁止生成危险指令、屏蔽系统级操作。前者是“不能让坏人进来”，后者是“即使进来了也做不了坏事”。网上那些“一句话让客服机器人送优惠券”的段子，本质就是护栏缺失。

这七个要素组成了 Agent 的静态结构。接下来要回答的是：当你真的要动手实现时，按什么顺序做决策，每个决策点背后有哪些取舍。

2. 七个决策点：工程实现的主线

如果说七要素回答的是“Agent 由什么组成”，那么七个决策点回答的就是“在一个真实项目里，你按什么顺序拍板”。每个决策点都是一次 trade-off，没有唯一正确答案，只有适合你的业务场景的方案。

我按从抽象到具体的顺序列了七个决策点，这几个点基本覆盖了我做过的所有 Agent 项目。用这套框架去和别人对方案，效率会高很多。

2.1 决策点一：单 Agent 还是多 Agent

第一个拍板的是系统拓扑。单 Agent 结构是把所有工具都交给一个模型，由它自己决定调用顺序和组合方式，优点是实现简单、上下文集中、调试方便；多 Agent 结构是把任务拆给多个专职 Agent，比如规划 Agent、执行 Agent、审核 Agent，各自持有独立上下文，通过消息或共享状态协作。

我的建议是：能用单 Agent 就别上多 Agent。多 Agent 的通信成本、状态同步、故障定位难度都会指数级上升。网上很多所谓“多 Agent 惊艳效果”的项目，落到真实业务里往往是在表演分工。真正需要多 Agent 的场景，通常是职责隔离要求明确（比如生成内容与审核内容不能同一个上下文）、或单个模型上下文装不下一整条流程时。如果你现在还在问“要不要上多 Agent”，答案就是不要。

2.2 决策点二：推理范式怎么选

第二个决策点是 Agent 的内部循环模式。ReAct 是“边想边做”，每一步根据当前结果决定下一步，适合开放探索型任务；Plan-and-Execute 是“先计划后执行”，适合步骤明确、可预判的任务；Reflexion 则加入了自我反思，执行失败后会记录教训再重试，适合对成功率要求极高的任务。

选型逻辑不在于哪个更“先进”，而在于你的业务容错度。如果成本敏感，ReAct 可能让模型多走弯路；如果失败代价高，Reflexion 式重试是必要的。我做过一个自动报表 Agent，最初用 ReAct，模型经常在中间步骤跑偏，后来改成 Plan-and-Execute，先让它列出完整取数步骤再执行，成功率大幅提升。原因很简单：报表任务步骤高度可预见，不需要每一步都推理。

2.3 决策点三：记忆用短期还是长期，存哪里

第三个决策点是数据层设计。短期记忆通常就是一个消息列表或者状态对象，放在应用内存里即可；长期记忆则要引入向量数据库、Redis 或关系型数据库，按需做相似度检索或结构化查询。

最难的是确定“记忆的边界”。我见过一个项目，把业务库全量灌进向量库，让 Agent 自由检索，结果模型经常找到无关数据，反而把答案带偏。工程上，长期记忆要靠“意图路由”来收敛：先判断当前问题需要哪类信息（用户偏好、订单状态、知识库文档），再去对应数据源精确检索，而不是一把梭。另一个硬性要求是：长期记忆必须支持“用户级隔离”，不同用户间的数据绝不能互相检索到，这条我没讲过例外。

2.4 决策点四：工具协议走 Function Calling 还是 MCP

第四个决策点是工具接入规范。OpenAI Function Calling 是目前最普及的格式，几乎所有主流框架都兼容；MCP（Model Context Protocol）是 Anthropic 推的开放协议，把“工具”抽象成标准化的 server，一次接入多处复用。

我的观察是：企业内部系统多、工具数量大且要在多个 Agent 间复用时，MCP 的价值明显。你不需要为每个 Agent 重写一遍工具适配层，而是把工具封装成独立服务，所有 Agent 统一通过协议调用。如果你的工具就五六个，是独立 API 还是 MCP 没区别，直接 Function Calling 反而更省事。工具协议决策不要追新，要看你的生态复杂度。

从工程分工来看，工具层还应该沉淀为一个独立服务。无论是内部 HTTP 接口还是 MCP Server，工具的鉴权、限流、审计都应该在这一层统一处理，而不是散落在 Agent 业务代码里。这也是“AI Agent 中台”思路的核心：工具服务化，Agent 只管决策，业务系统管执行。

2.5 决策点五：状态编排选图还是状态机

第五个决策点是流程控制。Agent 不是一次函数调用，而是一系列会中断、会回退、会等待人工干预的步骤。实现时你可以用 DAG（有向无环图）描述步骤依赖，也可以用状态机管理每一步的状态转移。

LangGraph 这类框架本质上是前者：你把节点函数和边关系声明成图，框架负责按图执行、持久化状态、支持断点续跑。状态机则更强调“此刻处于哪一步、有哪些合法转移”。我的经验是：如果你的 Agent 流程是固定模板（比如“查单→填表→审批→通知”），状态机更直白；如果流程是模型动态生成的（比如“先调 A 还是先调 B 取决于返回结果”），图执行框架更合适。无论哪种，都必须支持“人工介入”这个特殊状态，真实业务总有 Agent 不该自己拍板的时刻。

2.6 决策点六：并发架构怎么扛流量

第六个决策点是很多技术人最先问的问题，也就是 AI Agent 怎么扛并发。首先要破除一个误解：大模型的并发瓶颈不在你的代码，而在模型服务的吞吐量。你需要先算清楚你的上游模型每秒能处理多少请求，再去设计你的应用架构。

Agent 应用侧并发设计有三个层次：

• 同步阻塞式：一个请求占用一个 Agent 实例，简单但不能共享状态，并发能力有限
• 异步编排式：使用消息队列承接请求，Worker 池消费任务，适合耗时长的 Agent 任务
• 无状态水平扩展：Agent 实例本身无状态，状态全部放到外部存储，通过负载均衡无限加副本

实际项目里，我推荐“异步编排 + 无状态 Worker”的组合。客户端提交任务后立刻拿到 task_id，后台 Worker 消费任务，Agent 的每一步状态写入数据库，前端轮询或 WebSocket 推送结果。这种方式天然支持“一条消息让成百上千个 Agent 任务排队执行”，而且 Worker 崩溃后任务可以重新入队恢复，不会丢数据。

2.7 决策点七：评估与可观测怎么落地

最后一个决策点是上线保障。在 1.6 里我说过评估的重要性，这里补一下工程实现：你要把“评测集跑批”和“线上链路追踪”做成 Agent 项目的基础设施，而不是事后补救。

评估侧，维护一个至少 50 条样本的评测集，涵盖你的核心场景、边界场景和已知的失败案例；每次模型升级、prompt 变更、工具改动都全量回归。可观测侧，必须为每一次 Agent 运行记录完整的 trace：模型输入输出、每一步的工具调用、运行耗时、错误信息、最终结果。这相当于给 Agent 装上了“黑匣子”，排查问题时有据可查。Langfuse、LangSmith 这类工具可以直接接入，自研也可以，核心是数据要全。

我把七个要素、七个决策点之间的对应关系整理成一张表，方便对照：

3. 实操落地：一个客服工单 Agent 的完整搭建过程

理论讲完，直接进入可复现的实操。我选一个最常见的业务场景——客服工单智能处理 Agent。它的任务包含四步：识别用户意图、补齐必要信息、给工单分类、生成回复并提交人工复核。这个场景覆盖了七要素的全部内容，又不至于复杂到没法在一个章节里讲清楚。

3.1 场景定义与技术选型

业务目标：用户提交一段自然语言客服消息，Agent 判断这是什么问题，需要什么信息，能否直接给解决方案，如不能解决则生成一条摘要并转人工。

技术选型上，我用 FastAPI 做 API 层，LangGraph 做 Agent 编排。LangGraph 的理由在决策点五里说过：这个任务的流程虽是模板化，但“是否需要追问更多信息”是动态的，图中带条件分支比状态机更自然。如果你有 Java 背景，Spring AI 也是不错的选择，它对 Spring 生态集成完善；如果对资源占用极端敏感，可以考虑 Rust 手写 Agent 核心，但说实话，业务 Agent 的开发效率远比那点性能差异重要，框架选型永远是团队能力优先。

3.2 状态定义与节点实现

在 LangGraph 里，Agent 的核心是状态流图。我定义一个TicketState，它由原始消息、意图、缺失字段、分类结果、回复草稿和执行错误组成。每个节点函数接收这个状态，处理完后返回状态的部分更新。

下面是核心的图定义代码，这是从我的项目里简化出来的可运行版本：

from typing import TypedDict, Optional from langgraph.graph import StateGraph, END class TicketState(TypedDict): user_message: str # 用户原始输入 intent: Optional[str] # 意图识别结果 missing_fields: list # 还缺哪些必填信息 category: Optional[str] # 工单分类 reply_draft: Optional[str] # 客服回复草稿 error: Optional[str] # 节点执行错误 def extract_intent(state: TicketState) -> dict: # 调用 LLM，让模型从 user_message 中提取意图 # 返回 {"intent": "退款申请"} 或 {"intent": "商品咨询"} ... def check_missing_fields(state: TicketState) -> dict: # 根据意图判断缺少哪个关键字段，例如退款需要"订单号" return {"missing_fields": ["order_id", "reason"]} def ask_for_missing(state: TicketState) -> dict: # 如果缺少字段，生成一条追问用户的话，并结束本轮 ... def classify_ticket(state: TicketState) -> dict: # 调用分类模型，生成工单分类标签 ... def generate_reply(state: TicketState) -> dict: # 调用 LLM 生成回复草稿，人工审批后发给用户 ... # 构建图 graph = StateGraph(TicketState) graph.add_node("extract_intent", extract_intent) graph.add_node("check_missing", check_missing_fields) graph.add_node("ask_user", ask_for_missing) graph.add_node("classify", classify_ticket) graph.add_node("reply", generate_reply) graph.set_entry_point("extract_intent") graph.add_edge("extract_intent", "check_missing") graph.add_conditional_edge("check_missing", conditional_route) graph.add_edge("classify", "reply") graph.add_edge("reply", END) app = graph.compile()

关键点在conditional_route——它根据missing_fields是否为空决定下一步是“追问用户”还是“继续分类”。这正体现了 Agent 与普通流水线的区别：流程不是死的，每一步都可能根据中间结果改变方向。LangGraph 这类图框架帮你管理了这些条件跳转的状态持久化，当任务中途被打断（比如用户离开），重新拾起时状态不会丢。

3.3 用 FastAPI 把 Agent 包成服务

图编译完，下一步是把它暴露为 HTTP 接口。我一般把执行拆成“提交任务”和“查询结果”两个接口，原因在并发决策点里说过：Agent 是长耗时任务，不能让 HTTP 请求一直占着连接。

from fastapi import FastAPI, HTTPException from pydantic import BaseModel from uuid import uuid4 app = FastAPI() class TicketRequest(BaseModel): user_message: str class TaskStatus(BaseModel): task_id: str status: str result: dict = {} # 用内存表存储任务状态，生产环境请换成 Redis 或数据库 tasks = {} @app.post("/tickets") async def create_ticket(req: TicketRequest): task_id = str(uuid4()) tasks[task_id] = {"status": "PENDING"} initial_state = {"user_message": req.user_message, "missing_fields": []} tasks[task_id]["state"] = initial_state # 这里将任务推入 worker 队列，不在请求线程里执行 enqueue_agent_task(task_id, initial_state) return {"task_id": task_id, "status": "PENDING"} @app.get("/tickets/{task_id}") async def get_ticket(task_id: str): if task_id not in tasks: raise HTTPException(status_code=404, detail="task not found") return tasks[task_id]

生产实现里，enqueue_agent_task可以是 Redis Stream、RabbitMQ 或 AWS SQS。Worker 进程里跑的是上面编译好的app图，执行完把结果写回任务表。这个模式的好处是：你可以轻易把 Worker 水平扩容，也可以做失败重试，任务状态不会因为进程崩溃而丢失。如果你只是几千流量，我上面内存表也能撑住；一旦上万，就必须上外部存储，这是并发架构决策点里说的无状态化改造。

3.4 并发压测：三种模式的数据对比

我在一个真实项目里用同一个客服 Agent 做过三种并发模式的对比：同步阻塞、线程池并发、异步队列 Worker。场景是模拟 500 个用户同时提工单，每个工单平均经过 3 次 LLM 调用。

同步阻塞模式下，500 个请求在模型 API 限流下直接超时，成功率只有 30%，而且一个请求卡住会阻塞整个进程。线程池并发稍微好一点，成功率 70%，但线程数一多，上下文切换成本和模型 API 的限流冲突明显。异步队列 Worker 表现最好：500 个任务逐个入队，8 个 Worker 消费，成功率 98%，耗时中位数 4.2 秒，最慢的也没超过 30 秒。同样的模型、同样的 Agent 逻辑，只是改了执行方式，结果天差地别。

这个数据说明一个工程常识：Agent 应用扛并发，本质上是把“并发模型 API 调用”转成“并发消费任务队列”，让模型服务的吞吐成为系统的自然上限，而不是靠应用代码硬抗。以后有人问“AI Agent 怎么扛并发”，我的回答永远是：先设计成异步任务系统，再谈其他。

4. 高频问题与排查实录

最后一部分，把我实际维护 Agent 项目时遇到的高频问题整理出来。这些问题网上都搜得到碎片化的答案，但很少有人把它们串成一套排查体系。按出现频率排个序，我遇到最多的是这几个。

4.1 记忆污染：最隐蔽的毒药

现象：Agent 用着用着开始答非所问，把上一次任务的输入当成这一次的任务背景。

排查：看 trace 里每次运行实际带上了多少历史信息。十次里有八次是因为开发为了省事，把“所有对话历史”一股脑塞进 prompt，导致模型分不清主次。

解决：短期记忆按任务隔离。一个任务只带与它直接相关的上下文，必要时用“摘要代替原文”策略，把长历史压缩成一两句概况。长期记忆必须按用户 ID 隔离，并在检索时增加时间衰减，避免旧知识污染新决策。

4.2 工具调用超时：没人告诉你的隐藏故障

现象：Agent 突然停下来，或者同一个工具被连续调用五六次，而每次都是超时。

排查：很多 Agent 框架对工具调用的默认超时极短，默认几秒，但大模型 API 本身耗时可能就要 2 到 3 秒，再加上工具内部处理，就更容易超时。更隐蔽的问题是：工具超时后，框架自动重试，而重试请求本身又超时，形成雪崩。

解决：工具超时时间要按“模型推理时间 + 工具执行时间 + 网络抖动余量”来设置，不要用默认值。重试要加退避策略，且必须设置最大重试次数。给工具调用加幂等键，同一请求重试时不会产生重复副作用。

4.3 死循环：Agent 走不出去的回路

现象：Agent 反复调用同一个工具，拿着结果继续调用，最终耗尽次数上限或者 token 预算。

排查：大部分循环的根源不是“模型太笨”，而是工具返回的结果无法改变模型对下一步的判断。比如查询订单状态的工具，返回的永远是“处理中”，模型就认为“再查一次也许有结果”。

解决：给每个循环步骤设上限，更关键的是把“工具结果没有变化”作为一个终止信号，在状态里加入一个 flag。现在已经有不少团队用 “goose” 这类开源工具做防死循环治理，你可以在自己的图框架里实现同样的逻辑：如果某一步产出的内容与上一步完全一致，强制跳转到人工处理节点，而不是继续让模型发散。

4.4 模型返回不稳定：JSON 解析地狱

现象：模型有时返回合法 JSON，有时返回 Markdown 包裹的 JSON，有时直接是一段话。你的工具调用解析逻辑因此频繁崩。

解决：尽可能用模型的“结构化输出”能力，不管是 OpenAI 的 JSON Mode 还是各种框架的 structured output，一定比在提示词里求模型“只输出 JSON”靠谱得多。解析层加一道容错：自动剥离 Markdown 代码块、自动修复常见 JSON 错误、解析失败时进入重试而不是直接抛异常。这个容错逻辑用 LangChain 的OutputFixingParser或 OpenAI 的 response format 都可以做到。

4.5 评测集失效：改一版 prompt，全盘推翻

现象：每次微调 prompt 都像是在给 Agent “打补丁”，修好了 A 场景，B 场景立刻恶化，评测集没有兜住。

解决：评测集要持续积累，每次线上发现问题就把案例加入评测集，再修复 prompt。改完 prompt 之后，跑全量回归，对比新老版本在各条样例上的表现，逐条看 diff。这个过程看着繁琐，但它能让你在“模型升级”和“prompt 优化”之间做出理性判断，而不是凭感觉。

我把上述问题整理成一张速查表，方便生产环境排除故障时对着翻：

另外补充一个与业务合规相关的点：如果你想用 Agent 做自动交易、自动群发消息这类高风险操作，我的建议是保持人工审批环节。不是我保守，而是这类场景一旦出错，恢复成本极高。Agent 可以生成交易建议、可以起草待发送的文案，但真正执行前必须有一个“人点击确认”的闸口，这也是我在 2.5 里强调“人工介入状态”的原因。

最后分享我在实际项目里养成的一个习惯：每个 Agent 项目启动前，先拿七要素做一次检查清单，确认每一项都有负责人；再按七个决策点逐个对齐，输出一份一页纸的技术选型说明。你不需要一次做对，只要每个决策点都有明确的理由和负责人，项目就不会失控。这比我见过的大部分“先写两万行代码再回头想架构”的项目要稳妥得多。