企业官网建设流程全解析

聊AI Agent的人越来越多了。这个标题里最容易被跳过、也最值得停下来细看的，其实是最后四个字：工程实现。概念文章会告诉你Agent有规划、有记忆、能调用工具，但等你真去写代码的时候，问题完全不是这回事——规划怎么触发？记忆到底存在哪？工具以什么协议暴露出来？模型答非所问的时候，这个循环怎么收场？这些问题，概念文章几乎都不正面回答。

我把这几年做Agent的落地经验收拢成两套框架：一套叫"七要素"，解决的是"Agent到底由什么组成"；另一套叫"七个决策点"，解决的是"实现这个Agent时，工程上需要在哪些岔路口做选择"。前者帮你建立完整的认知地图，后者帮你少走弯路。这篇文章不只讲概念，还会给到一个最小可运行的ReAct式Agent骨架、生产化改造思路、以及我踩过的坑。

1. 先把两件事分开：七要素回答"Agent能干什么"，决策点回答"项目怎么落地"

1.1 为什么概念看懂了，代码却写不下去

我看过太多刚转Agent开发的工程师，论文读了一堆，张嘴就是规划、记忆、工具、反思，一到自己搭系统就卡住了。

卡住的原因不是概念不对，而是概念和代码之间隔了一层"翻译"。学术界讲的Planning，在工程上可能是一个任务列表、一个状态机、或者一张图；论文里的Memory，在代码里可能是向量数据库的collection、Redis里的KV、又或者是塞进上下文窗口的一段摘要。你脑子里如果没有这层翻译，写出来的东西就会很飘，要么全都堆在System Prompt里让模型自由发挥，要么把简单任务硬拆成多Agent协作，最后被不可控的复杂度拖死。

所以我一直觉得，理解Agent的第一步不是学某个框架，而是先搞清楚：一个Agent系统里，哪些能力是必须的，每一项能力在工程上由什么模块承担。这就是本文说的"七要素"。

1.2 七要素与决策点的映射：先看全貌再动手

七要素是我自己归纳的Agent能力清单：目标与任务定义、环境感知、规划与任务分解、记忆系统、工具调用、行动执行、反思与迭代。每项要素都不只是"一种能力"，而是对应一组工程问题。七个决策点则是从能力到系统的桥梁：你知道了Agent需要记忆，那就要决定记忆放在哪；你知道了Agent要调工具，那就要决定用Function Calling还是别的协议。

下面这张表是我讲课时常画的，直接把两套框架串起来看：

看这张表你会发现，要素是"要什么"，决策点是"用什么、怎么用"。没有要素清单，你不知道系统缺什么；没有决策点，你不知道怎么把要素变成能跑的代码。接下来的两章，我分别展开。

2. 七要素逐个落地：把论文里的"能力"翻译成代码里的"模块"

2.1 要素一：目标与任务定义

这个概念最容易被当成一句废话，但绝大多数Agent翻车的起点，恰恰是任务定义模糊。

论文里讲Goal是让Agent"知道要做什么"，工程上的做法完全不同：你要把任务写进结构化的描述里，让模型既知道目标，也知道边界、格式和验收标准。比如"帮我写一篇关于AI Agent的博文"这种描述就是不合格的，因为模型不知道字数、不知道面向谁、不知道要不要包含代码示例。工程化的做法是把任务拆成字段：目标、输入材料、输出格式、约束条件、验收标准。

我在实践里会把这些字段直接拼进System Prompt，同时给一份JSON格式的任务定义。这一步看起来简单，但能把模型输出的稳定性提升一大截。很多团队花大价钱调模型，却不愿意花十分钟把任务描述写严谨，属于典型的捡了芝麻丢了西瓜。

2.2 要素二：环境感知

Agent不是活在真空里的。它要完成任务，就得上游的数据、有的还要感知外部系统的状态。

工程上，环境感知这一层做的事情是：把外部世界转成模型能理解的文本。比如做一个RAG型Agent，感知层负责把用户查询、检索到的文档片段、当前系统时间、用户身份这些信息打包进上下文；比如做一个自动操作外部系统的Agent，感知层负责把目标系统的当前状态拉回来，转成一段状态描述。

这一层最容易被低估，因为它不产出"看起来智能"的东西，只产出上下文。但Agent表现得好不好，七成取决于感知层喂给它的上下文质量。工具返回了5万字，你全塞进去，模型的注意力就会被稀释；你把关键字段抽出来做成摘要，模型反而能抓住重点。记住一句话：感知层的核心职责不是"多给"，而是"给对"。

2.3 要素三：规划与任务分解

规划是Agent区别于普通聊天机器人的核心能力之一，但工程实现上，我不建议让模型完全自由地"想"。

业界常用的路线有两条：一是ReAct模式，让模型在思考、行动、观察之间循环，每一步自己决定下一步干什么；二是Plan-and-Execute模式，先让模型产出一个完整计划，再逐个执行计划项。两条路线没有绝对优劣，ReAct适合开放性强、路径不明显的中小任务，Plan-and-Execute适合步骤清晰、执行链路长的大任务。

工程落地时，规划要落到数据结构上。我常用的是一个任务列表：每个任务项包含任务描述、依赖的前置任务、执行状态、输出结果。模型负责往这个列表里填内容、调整顺序，程序负责任务项的状态流转。这里有个非常重要的经验：规划是可以被中断和修正的。不要让模型生成一个计划就当成圣旨，每一步执行完都要回头核对计划是否还成立。计划是动态的，不是静态的。

2.4 要素四：记忆系统

记忆这个词在Agent语境里被滥用得厉害。工程上，Agent的记忆至少要分成三层：

这里必须说清楚一个很多人困惑的问题：AI Agent里的Token是什么？Token是模型处理文本的基本单位，一个Token大约对应0.7个英文单词或0.5个汉字。你给模型发消息、模型回消息，消耗的都是Token，而这正好是短期记忆的物理上限——上下文窗口能装多少Token，短期记忆就有多大。

所以工程上记忆选型的核心逻辑是：高频低延迟的状态读写，用Redis或内存；中低频的语义检索，用向量库；结构化的长期事实，用PostgreSQL这类关系库。不要一上来就上向量数据库。很多项目连短期上下文都整理不清楚，就急着把历史对话全部扔进向量库里，结果检索一堆噪音回来，效果更差。

2.5 要素五：工具调用

工具是Agent从"会说话"到"会办事"的分水岭。没有工具的模型只会生成文本，有了工具，模型才能查天气、操作数据库、调第三方API、甚至向外部系统自动发布消息。

工程上，工具调用的标准做法是给模型一份工具清单，每个工具用JSON Schema描述清楚：工具叫什么、参数是什么、返回值是什么。模型不直接执行代码，它只是"决定"调用哪个工具、传什么参数，执行动作由程序完成。现在主流方案有OpenAI的Function Calling、Anthropic的Tool Use，以及越来越多的MCP（Model Context Protocol）。

我对工具层的建议是：先做一个统一工具注册表，所有的工具都注册进去，由注册表负责Schema管理、参数校验和权限控制。你的业务代码不需要直接和模型交互，只需要向注册表注册函数，模型层通过注册表感知有哪些工具可用。这样做的好处是，以后不管是换模型还是换协议，工具层不需要跟着动。

2.6 要素六：行动执行

行动执行是Agent真正"碰世界"的那一下。到了这一步，工程上的技术含量反而不在AI，而在健壮性设计：超时、重试、幂等、权限。

举个例子，Agent调用一个HTTP接口，接口超时了怎么办？很多初版代码直接把这个异常抛给模型，让模型"自己看着办"。这种做法不是完全不行，但很浪费Token，而且模型不一定能正确处理异常。我更推荐的做法是：执行层统一封装重试策略，网络错误重试两次，业务错误直接返回错误码，只有不可恢复的错误才触发模型重新规划。

另一个容易踩的坑是幂等。Agent执行一个创建订单的工具，第一次调用超时但订单其实已经创建成功了，重试之后就会创建两条订单。解决方法是给工具调用带上唯一的trace_id，服务端做幂等处理。这类问题在Agent里比传统后端更严重，因为Agent的每次行动都可能是不可预知的。

2.7 要素七：反思与迭代

反思是七要素里听起来最玄的一个，因为论文里描述的反思很像人类的自省。工程上别搞这么玄。把反思翻译成工程语言，就是三件事：校验、重试、反馈。

第一步校验：模型返回结果后，程序先校验格式对不对。该输出JSON却输出了一句话，该返回数组却返回了对象，都会引发后续流程崩溃。第二步重试：校验失败时，把错误信息拼进上下文，让模型重新生成一次。这一步在业内有个通俗叫法"带错误重试"，成本低、效果好。第三步反馈：把这次执行的完整轨迹记下来，用于评测和后续优化。

我见过太多团队做"反思"，就是在Prompt里写一句"请你检查你的答案是否正确"，让模型对着自己的回答反复自我确认。这是心理安慰，不是工程。真正的反思必须有外部校验器参与：格式校验器、规则校验器、单元测试、甚至另一个模型来打分。一句话：反思的权威不在模型，在校验器。

3. 七个决策点：从Demo变成系统，每次选型都是一笔账

七要素告诉你Agent需要什么，七个决策点告诉你每一样东西到底怎么做。这些决策没有标准答案，只有取舍。

3.1 决策一：Agent跑在脚本里、服务里，还是调度器里

第一个决策往往最不起眼，但影响最大。Agent的运行形态直接决定了你能拿它干嘛。

一次性任务，比如"把这份文档翻译成英文"，用一个Python脚本跑完就退出，完全没问题。需要对外提供接口，比如网页输一个任务、后台跑一个Agent，那就要包成HTTP服务。需要定时批量执行，比如每天早上汇总报表，那就要落到调度器上，可以是Cron，也可以是Celery Beat这类任务队列。

如果你的Agent运行在一个成熟项目里，最自然的做法是把Agent循环封装成一个纯函数，然后通过Django或FastAPI暴露成接口。我之前帮人改造过一个Django项目，就是在app里加一个独立的agent模块，路由层拿到请求后调用Agent函数，同步返回或异步轮询结果。核心循环不关心上游是HTTP还是队列，它只接收一个任务对象，返回一个结果对象。保持Agent的业务无关性，是生产化的前提。

3.2 决策二：模型走API、本地部署，还是级联

模型是Agent的大脑，这个问题躲不开。三类路线各有适用场景：

我个人的建议是：验证期无脑用API，先跑通业务流程；上生产后如果成本敏感，再把高频简单路径切到本地模型，复杂路径继续走API。所谓级联，就是用一个轻量模型先判断任务难度，简单任务直接回答，复杂任务再转发给大模型。这个模式能把成本压到原来的三分之一，但前提是你的路由规则要可靠。

顺带说一句，现在有人在用Rust重写Agent的执行引擎，目的就是压低单步调度的延迟和内存占用。高并发场景下这确实是个方向，但对大多数项目来说，瓶颈根本不在框架性能，而在模型调用和工具执行上，不用过早优化。

3.3 决策三：单Agent、编排式还是多Agent

这个决策很容易被带偏。我的经验是：能用单Agent解决的事，绝对不上多Agent。

单Agent就是"一个大脑+一堆工具"，绝大多数任务到这一步就够了。比如帮用户查资料、汇总信息、操作接口，本质上都是单Agent加工具的组合。编排式Agent是一个规划器负责拆任务，然后调度多个子Agent分别执行，适合任务链特别长、子任务边界清晰的场景。多Agent协作则是多个Agent各自有角色、互相讨论协作，比如AutoGen里的群聊模式，适合需要多视角讨论的开放问题。

多Agent的坑是成本爆炸式增长、状态难同步、错误难排查。你让三个Agent互相对话，任何一个Agent上下文被污染，整条链路就乱了。我经手的项目里，真正需要多Agent的场景不到两成。先单Agent起步，跑通了，确实现阶段不够用，再演进到编排式。一上来就上多Agent，基本都会死得很惨。

3.4 决策四：记忆存哪：窗口、向量库还是状态库

记忆方案的选型在2.4已经讲过机理，这里直接给决策建议。

第一，短期记忆就是上下文窗口，你不需要额外存储，但你需要控制长度。模型的上下文是有上限的，而且超过一定长度后，中间部分的信息会被模型"遗忘"（其实是注意力的稀释）。工程上常见的做法是：给上下文设一个软上限，超过之后，把最老的对话做摘要，释放空间。

第二，长期记忆如果用向量检索，先想清楚检索的质量。向量库不是万能的，对时间敏感的事实、精确的数值查询，向量检索远不如关系型数据库。比如"用户上周三买了什么"，用Redis或PostgreSQL查精确得多。只有"哪些历史结论和当前问题语义相关"这种需求，才适合上向量库。

第三，工作记忆是很多人忽略的一层。Agent执行到一半被打断，恢复时要能拿到进度。这个状态不要放在模型上下文里，程序层面用一个JSON对象或者数据库行存进度即可。不要在Prompt里问模型"我刚才做到哪了"，自己记录远比让模型回忆可靠。

3.5 决策五：工具协议：Function Calling、MCP还是自研

工具调用协议选错了，后期会很难受。

OpenAI的Function Calling是目前最成熟的方案：模型在生成回复时，会额外输出一个函数调用请求，包含函数名和JSON格式的参数。服务端执行完函数后，把结果以tool消息的形式回传给模型。简单、稳定、文档多。如果你主要用OpenAI系列模型，直接用Function Calling就好。

MCP是这几年快速普及的标准协议，它的思路是把工具、资源、提示词统一成标准化接口，让Agent应用和外部能力解耦。好处是生态互通，一个MCP服务可以被多个Agent客户端复用；代价是协议本身有学习成本，并且多一层网络调用。如果你要给多个Agent共享工具能力，或者工具团队和Agent团队是分开的，值得上MCP；如果是自己产品内部的几个工具，直接Function Calling就行，没必要自找麻烦。

自研协议是最后的选择。只有当现有协议满足不了需求，比如你需要复杂的权限模型、多级审核流程，才考虑自己定义工具协议。

3.6 决策六：可观测性：日志、Trace和评测

做Agent开发的工程师，迟早会面对一个场景：模型干了一堆事，最后结果不对，你想知道它到底在哪一步跑偏了。

如果Agent就是一个函数，不加观测，你只能看到输入和输出，中间全是黑盒。所以可观测性不是锦上添花，是Debug的刚需。我通常在Agent循环里埋三类数据：一是事件日志，每一步模型思考、工具调用、返回结果都记一条带时间戳的事件；二是完整的Trace，从任务开始到结束，把每一步的依赖关系串起来；三是结构化轨迹，把每轮对话、工具结果整理成一个列表，可以直接回放。

工具方面，开源的Langfuse、商业的LangSmith都能做这事，它们支持OpenTelemetry协议，能接入已有的监控体系。就算你不想引第三方，也要自己用一个列表结构把每步记录下来。没有Trace的Agent系统，出了问题只能靠猜，而靠猜排错，在这个领域基本等于坐以待毙。

3.7 决策七：安全边界、成本预算和终止条件

最后一个决策点，是决定系统"不会出大乱子"的关键。

首先是安全边界。Agent能调用的工具，权限要最小化。一个负责查天气的Agent，没有任何理由拿到数据库的管理员账号。我在工具注册表里给每个工具做了三样配置：允许的调用者、允许传入的参数范围、是否允许执行写操作。宁可配的时候麻烦一点，也别给Agent一个万能API。

其次是成本预算。Agent不是一个函数调用，它是一连串Token消耗。不给预算，一次失控的循环就能烧掉几美元。工程上要设置三层控制：单次任务最大步数（比如10步）、单步最大Token数、整个任务的Token总预算。超出即终止。

最后是终止条件。Agent什么时候算"完成"？不是模型说"我干完了"就算，而是程序确认了终止条件成立：最终答案通过格式校验、或者达到最大步数、或者用户取消。终止条件必须是程序判断的，不能全交给模型自觉。

4. 最小骨架跑起来：一个ReAct式Agent的工程实现

4.1 Agent主循环：先把循环写对

说了这么多，最后还是得落到代码。下面这个骨架是我常用的最小实现，去掉所有框架依赖，一个Python文件就能跑通ReAct循环。

from dataclasses import dataclass from typing import Callable, Optional @dataclass class AgentConfig: model: str = "gpt-4o-mini" max_steps: int = 10 max_tokens_per_step: int = 2000 context_keep_last: int = 6 SYSTEM_PROMPT = """你是任务执行助手。 你可以调用工具完成任务。 当得到最终答案时，直接以纯文本返回，不要调用工具。 每一步只能调用一个工具。""" def run_agent(task: str, tools: dict[str, Callable], cfg: AgentConfig) -> str: messages = [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": task} ] for step in range(cfg.max_steps): # 调用模型，同时把可用工具的描述传给模型 reply = call_model(messages, tools=tools, max_tokens=cfg.max_tokens_per_step) messages.append({"role": "assistant", "content": reply["content"], "tool_calls": reply.get("tool_calls")}) # 模型没有请求调用工具 -> 任务结束 if not reply.get("tool_calls"): return reply["content"] # 当前骨架只支持单工具调用，多工具并行调用需要循环处理 call = reply["tool_calls"][0] fn_name = call["function"]["name"] fn_args = json.loads(call["function"]["arguments"]) # 查看工具是否存在，避免模型瞎编函数名 if fn_name not in tools: messages.append({ "role": "tool", "tool_call_id": call["id"], "content": f"错误：工具 {fn_name} 不存在" }) continue # 执行工具，并把结果传回给模型 result = execute_tool_safely(tools[fn_name], fn_args) messages.append({ "role": "tool", "tool_call_id": call["id"], "content": truncate_for_context(result, max_length=1500) }) raise TimeoutError(f"达到最大步数上限 {cfg.max_steps}，任务终止")

这个主循环里，真正关键的就三件事：把工具描述传给模型、模型决定调用工具、程序执行并回传结果。循环的退出条件有两个：模型认为任务完成，或者步数用尽。理解了这个骨架，LangChain、LangGraph这些框架对你而言就只是工具，不再是不可绕开的黑盒。

4.2 三个工程补丁：结构化输出、上下文截断、失败重试

骨架能跑，但要变得可靠，还需要打三个补丁。

第一个是结构化输出。让Agent直接返回自由文本，解析时一定会踩坑。更稳的做法是要求模型返回JSON，并在解析失败时重试。下面这段是我常用的JSON修复函数：

def extract_json(text: str): try: return json.loads(text) except json.JSONDecodeError: # 很多模型会在JSON前后包一堆废话，先尝试抽取大括号部分 start = text.find("{") end = text.rfind("}") if start != -1 and end != -1: return json.loads(text[start:end+1]) raise

第二个是上下文截断。Agent跑久了，消息列表会膨胀到模型窗口装不下。最简单的截断策略是：系统消息永远保留，前面的历史消息做摘要，保留最近几轮完整消息。这一步是记忆系统里短期记忆管理的简化版，但实际效果很好。

第三个是失败重试。当模型输出解析失败、或者工具报业务错误时，不要把异常直接抛给用户，而是把错误信息附到消息列表里，让模型重新生成一次。注意重试次数要有限制，我的习惯是同一个环节最多重试两次，再失败就整体终止并报警，避免死循环烧钱。

4.3 生产化路径：从函数到HTTP接口再到任务队列

骨架跑通之后，下一步就是把run_agent挂到真实业务上。最简单的方式是包成一个HTTP接口：

from django.http import JsonResponse from .agent import run_agent def agent_api(request): if request.method != "POST": return JsonResponse({"error": "Method Not Allowed"}, status=405) task = request.POST.get("task", "").strip() if not task: return JsonResponse({"error": "task is required"}, status=400) try: result = run_agent(task, GLOBAL_TOOL_REGISTRY, PROD_CONFIG) return JsonResponse({"answer": result}) except TimeoutError as e: return JsonResponse({"error": str(e)}, status=424)

再进一步，如果你的Agent任务动辄跑一分钟以上，HTTP同步接口就不合适了。这时候把任务丢进Celery或RQ，接口立刻返回一个task_id，前端轮询结果。Agent本身不需要改造，只是调用方式从同步变成了异步。

工具层到生产化的阶段，我强烈建议至少把工具注册表做成统一的。这样以后接入MCP也好、拆成微服务也好，Agent主循环都不用动。架构上先做到"主循环稳定、工具可扩展"，这比任何炫技都重要。

5. 同样是Agent，为什么你的在打转、别人的在交付

5.1 最常见的停滞模式：上下文污染、无终止反射、规划与执行脱节

同一个模型，有人搭的Agent稳定交付，有人搭的Agent在循环里打转。差别不在于模型选得好不好，而在于对三个经典停滞模式的处理。

第一个是上下文污染。工具返回了一大段原始数据，全被塞进了对话历史，模型后续的判断被噪音干扰。这个问题我在2.2已经讲过，解决思路是感知层控制上下文质量。第二个是无终止的反思。模型每轮都说"我再检查一遍"，检查完又说"发现一个小问题，再改一下"，理论上可以永远循环下去。这就是我强调终止条件必须由程序控制的原因，没有步数上限就没有开发效率。第三个是规划与执行脱节。规划器生成的计划和执行层能用的工具对不上，模型计划调用一个工具，执行器根本没有。这通常是因为规划器和工具注册表没有共用同一份工具列表。遇到这种情况，先把工具Schema标准化，再让规划器基于Schema生成计划，问题很快就会消失。

5.2 稳定性来自三层保障：结构化、校验、降级

我观察下来，稳定的Agent系统高度依赖三层保障，缺一层都不行。

第一层是结构化。模型的所有中间输出都尽量限定为JSON或限定格式，不要让它自由输出大段文本再让程序去猜语义。第二层是校验。每个关键节点都要有校验器，模型输出完之后，程序先校验再做下一步。校验器可以是规则、JSON Schema，也可以是精心设计的验收测试。第三层是降级。当Agent走不通逻辑时，要有明确的降级路径：调用备用模型、切换更便宜但更稳的模型、或者直接转人工处理。降级方案要提前想，别等生产事故了再临时凑。

我自己的经验是，这三个保障的优先级是：先保格式结构，再保内容校验，最后才考虑性能优化。很多人一上来先优化Prompt、调模型温度，结果格式都没锁死，越调越乱。

5.3 一笔成本账：一次Agent任务到底要花多少钱

很多人对Agent成本没概念。我算一笔账给你看。

假设一次任务平均需要8次模型调用，每次调用的输入是6000个Token、输出是800个Token。以现在主流的入门级大模型API价格为例，输入大约0.15美元每百万Token，输出0.6美元每百万Token。那么单次调用的成本是：6000×0.15/1000000 + 800×0.6/1000000 = 0.0009 + 0.00048 ≈ 0.00138美元。8次调用合计约0.011美元，折合人民币不到一毛钱。

看着很便宜对吧？但如果你把模型换成更强的大模型，输出价格翻几倍，步数上限从8放宽到30，再加上多Agent互相调用，成本瞬间从一毛钱跳到几美元。这就是为什么我在决策三里反复强调别乱上多Agent。成本失控的第一原因永远是决策时拍脑袋，而不是模型单价太贵。

6. 给刚转向工程实现的你一句老实话

最后，作为一个被Agent工程毒打过很多次的人，我给你一句老实话：别从框架入门。LangGraph、AutoGen这些都很优秀，但如果你连一个Python函数实现的ReAct循环都没亲手调通过，直接用框架会让你分不清"是代码问题"还是"是概念理解问题"。

先把七要素记在脑子里，当成检查清单；再沿着七个决策点一步步选型。不要一次性全部想清楚，也不要指望第一版架构就是终版。Agent这个领域变化太快，今天的最优解，三个月后可能就是反面教材。你真正需要训练的，是走到每个岔路口时，能看清自己在选什么、放弃了什么。这笔账，迟早会值回来。