企业官网建设流程全解析

做Agent开发一段时间下来，我最大的感受是：大模型本身不是瓶颈，怎么把一个“只会聊天”的大模型，变成能规划任务、调用工具、记住上下文、最后自己把活干完的Agent，才是真正考验工程能力的地方。这篇大模型Agent开发全指南，不画饼，直接从概念、架构、框架选型、完整实操到高频踩坑，一层层拆开讲。内容覆盖从基础原理到生产级落地，适合三类人看：刚入门想搞清楚Agent到底是什么的新手，写过Prompt但没做过完整Agent项目的开发者，以及已经踩了不少坑、想系统化梳理经验的老手。文里的代码和步骤都来自我实际跑过的项目，主案例是一个电商客服Agent（后面统一叫它AgentX），你可以直接照抄，再按自己的场景去改。

1. 先把概念揉碎了：Agent到底解决了什么问题

1.1 大模型和Agent之间，差的不止一个提示词

先把一个误区拆掉：把大模型接进对话框，加一段“你是一个智能助手”的System Prompt，这不叫Agent。

大模型本质是概率语言模型，能力边界是“生成下一个词”。你跟它说“帮我订一张明天去上海的机票”，它能给你写出一段像模像样的回复，但它没法真的查航班、比价、下单。因为它的训练数据里没有实时航班信息，也没有操作外部系统的接口。换句话说，大模型是“知道怎么说”，不是“知道怎么做”。

Agent的本质，是在大模型的“大脑”外面接上规划、记忆、工具、行动四个模块，让模型从“会说话”进化成“会办事”。我常打一个比方：大模型是刚毕业的高材生，聪明、知识面广，但没有工位、没有电脑、没有工作流程；Agent是给这个高材生配了工位、发了电脑、定了KPI，还配了个秘书（记忆系统）的完整组织。

这个差异直接决定了开发复杂度。做纯大模型应用，你只管Prompt和输出解析；做Agent，你得管任务分解、上下文管理、工具调用失败恢复、死循环兜底、多轮记忆持久化。这也是为什么Agent项目普遍比Chatbot项目难做，坑也多得多。

1.2 Agent的四种核心能力，缺一不可

我把Agent的能力拆成四块，每一块都要独立设计、独立测试：

• 规划能力：面对复杂目标，能拆成子任务，并决定先后顺序和依赖关系。比如“帮我策划一场线下读书会”，不能上来就写方案，得先拆成定主题、选场地、定时间、邀嘉宾、做物料、安排流程。
• 记忆能力：能记住当前对话的上下文（短期记忆），也能从历史交互中提取长期偏好和事实（长期记忆）。没有记忆的Agent，每轮对话都是“第一次见面”，体验非常割裂。
• 工具能力：能识别何时需要调用外部能力，通过函数调用、API、代码执行等方式完成操作，比如查天气、查数据库、发邮件、调内部服务。
• 行动能力：能把规划变成实际动作，并根据动作结果决定继续执行、调整方案还是终止。这是Agent闭环的关键，也是工程上最容易出问题的地方。

这四个能力不是四选一，而是层层叠加。最简Agent可能只有“工具能力”，复杂的企业级Agent则四者全要，而且每一块背后都是一堆工程细节。

1.3 先判断清楚：你的场景真的需要Agent吗

不是所有需求都值得上Agent，这个判断做错了，后面全是白干。

适合Agent的场景有几个共性：任务需要多步推理；必须调用外部系统或实时数据；输入是开放式的，没法用固定规则穷举；用户需要多轮交互，且上下文会影响后续决策。典型例子是智能客服、个人助理、数据分析助手、自动化运维、知识库问答加自动处理。

不适合的场景也很明显：单轮问答，传统检索加Prompt就够；流程完全固定，用状态机或工作流引擎更稳；对响应延迟极敏感，Agent每轮要多次调用模型，延迟天然偏高；容错率极低，比如直接操作支付、删除数据，这类动作让模型自主决定风险很大。

实操心得：判断标准就一句话——如果你的业务能用一张状态图画清楚，就别用Agent；只有当分支路径多到状态图画不完，或者用户输入无法预判时，Agent的“自主决策”才有价值。

2. Agent架构拆解：四大模块逐个讲透

2.1 规划模块：让模型学会“先想后做”

规划是整个Agent的龙头。现在工业界最主流的规划模式有三种，我按实际落地频率排序。

第一种是ReAct模式，让模型交替输出思考（Thought）和动作（Action）。它的好处是简单直接，一个循环就能实现，模型每走一步都能看到工具返回结果，再决定下一步。缺点则是长任务容易走偏，需要外部兜底。

第二种是Plan-and-Execute模式，先让模型产出一份完整计划，再按计划逐步执行。它的优点是全局视角更好，任务分解清晰，尤其适合步骤明确的流程。缺点是环境一旦变化，原计划可能失效，所以要加“重新规划”的触发机制。

第三种是更复杂的树状或图状规划，模型同时探索多条路径再择优。效果上限高，但实现成本也高，目前在多数生产项目里用得还不算多，更多出现在研究原型里。

规划模块的工程核心，是给模型足够明确的“思考脚手架”。我见过很多失败案例，不是模型能力不行，而是Prompt里只写了一句“请帮我完成任务”，模型根本不知道该怎么思考。正确做法是在System Prompt里把规划规则写死：任务拆解粒度、步骤上限、什么时候该用工具、什么时候该放弃、输出格式是什么。

2.2 记忆模块：短期、长期、工作记忆三层联动

记忆是Agent区别于普通对话模型的核心之一。我习惯把记忆分成三层。

短期记忆就是当前对话的上下文，直接塞进模型输入，对应的是模型上下文窗口。它的管理重点是控制长度，后面实操部分我会重点讲。

长期记忆是跨会话的持久化信息，比如用户的收货地址、之前的订单偏好、项目背景资料。常规做法是把这些信息结构化存储，或者切块后做向量化，在需要时检索相关片段拼进上下文。

工作记忆则是Agent在单次任务执行过程中产生的中间结果，比如工具返回的数据、已完成的子任务结论、待办清单。工作记忆通常放在Agent运行时的状态对象里，不进向量库，任务结束就清理。

三层记忆的分工，我总结成一句话：短期记忆管“当前话题”，工作记忆管“执行进度”，长期记忆管“用户是谁、背景是什么”。很多Agent做出来像个“健忘患者”，就是因为只做了短期记忆，而后两层完全没设计。

注意：长期记忆不是越多越好。检索出来的信息如果和当前任务无关，反而会干扰模型决策。检索阶段一定要做相关性过滤和去重，宁可少给，不要给脏。

2.3 工具模块：Function Calling的机制与Schema设计

工具是Agent的“手脚”。现在主流大模型都支持函数调用：模型根据用户问题和工具定义，输出一个结构化的调用请求，应用层解析后执行真实函数，再把结果返回给模型。

核心机制可以理解成：工具定义是一份“说明书”，模型在说明书里挑一个合适的函数，填好参数，然后你的代码负责执行。模型不直接操作任何系统，所有权限和控制都在你这边。

工具定义（Schema）怎么写，直接决定调用成功率。我踩过不少坑，总结出几个关键点。函数名和参数名要语义清晰，一个叫get_order_info的函数，比叫query_xxx的调用成功率高得多。参数描述要写清楚边界，比如status参数，要说明“仅支持pending、paid、shipped、cancelled四种取值，其他值返回错误”。描述含糊会导致模型乱填参数。同一时间暴露给模型的工具数量要控制，一屏超过20个工具，模型选择准确率会明显下降。能合并的合并，不常用的工具要分页或分层暴露。

工具返回结果也要讲究。返回给模型的内容应当结构清晰、精简，不要把整个数据库原始记录都怼回去。一般做法是：用自己的代码把原始结果清洗成摘要，再交给模型做下一步决策。

2.4 行动模块：循环控制与终止条件

行动模块是承接规划和工具的“发动机”，核心是一个循环：模型产出决策，系统执行工具，结果回填，再让模型继续决策，直到满足终止条件。

这个循环至少要有四道保险。最大迭代次数，防止模型陷入无限循环，一般单任务设10到20轮，超过就强制终止并提示用户。终止条件判定，即当模型认为任务已完成的信号出现时，必须能准确识别并退出，不能继续没话找话。异常回退，工具调用报错时，要把错误信息结构化成模型能理解的文本，让它决定重试、换方案还是向用户求助。权限拦截，凡是涉及支付、删除、修改等敏感操作，必须走人工确认，不能由模型直接执行。

行动模块最常见的失败模式是“模型自嗨”：它以为自己调了某个工具，实际上你的代码根本没收到调用请求，它只是在文本里编造了调用结果。这个问题的排查方法很朴素——在日志里把每一次模型输出、工具调用、返回结果全部打点，一眼就能看出模型是不是在编。

3. 框架选型的思路：别被“全家桶”绑架

3.1 先看清框架的四个层次

Agent开发工具链现在非常热闹，但归纳起来是四个层次，很多人选型混乱就是因为没分清自己在哪一层。

第一层是模型接入层，只负责把大模型API包一层，提供对话和流式输出。第二层是Prompt编排层，提供模板管理、链式调用、输出解析，适合做固定流程应用。第三层是Agent运行时层，内置了规划循环、工具调用、记忆管理、多轮对话状态机，这是我现在做生产项目最常待的一层。第四层是可视化多Agent平台，拖拽节点就能编排多个Agent协作，适合快速验证，但深度定制时会碰壁。

选型最大的误区，是拿第四层的预期去选第二层的工具，然后发现大量底层逻辑要自己补。我建议反过来：先用第三层的框架把业务跑通，跑通之后再决定要不要换。

3.2 不同规模项目的选型参考

我用一个表格把选型思路整理出来，这个表是按我真实项目的经验总结的，不是官方指标：

我自己的偏好是：能不用框架就不急着用框架，先用原生代码跑通一个最小Agent循环，再去选框架。因为只有亲手写过循环，你才知道框架帮你省了什么、又替你藏了什么，出问题时才不会抓瞎。

3.3 模型选择的几个关键指标

选模型比选框架更影响最终效果。我重点看五个指标。

函数调用能力是第一位的，直接决定工具模块靠不靠谱，这个必须用你自己的工具集做评测，不能只看榜单。上下文长度决定了短期记忆窗口的上限，但别迷信长上下文，越长越贵，越长越慢，优先考虑压缩而不是无限加长。指令遵循能力影响Agent能否严格按你的规划规则执行，这个和函数调用一起测。推理成本和延迟是经济账，高频场景下成本和延迟往往比效果更先卡脖子。最后是稳定性，同一个模型在线上反复调用的输出一致性，决定了你要不要加大量重试逻辑。

关于小模型，我的观点是：开源小模型做Agent不是不行，但要非常克制。简单工具调用、单轮任务可以胜任，复杂规划、长链路推理目前还是大模型更稳。先用商用大模型把业务跑通，再把高频子任务切给更小更便宜的模型，是很多团队实际在走的降本路径。

4. 完整实操：从零搭一个电商客服Agent

4.1 需求拆解与AgentX的整体设计

AgentX要处理的场景非常典型：用户咨询订单状态、申请退货、咨询优惠券、投诉物流。这些任务看起来是FAQ，但背后要查真实数据，而且不同意图的处理路径完全不同。

我把需求拆成三块。意图识别与路由：判断用户是想查订单、退货还是投诉，这决定后续走哪条工具链。信息查询：根据用户提供的订单号，去订单系统里查状态和物流。业务动作：退货申请要校验条件、写工单、给用户回执。

整体设计上，AgentX采用ReAct循环，记忆用短期上下文加长期用户画像两层，工具侧暴露三个函数：查订单、查物流、申请退货。系统提示词里写死了两条铁律：涉及金额和地址修改时必须二次确认；查不到真实数据时绝不能编造物流状态。

4.2 系统提示词与工具Schema示例

系统提示词我习惯拆成四段：角色与目标、可用工具清单、处理规则、输出格式约束。核心代码如下，这是简化版，但结构可以复用：

你是某电商平台的客服AgentX。 你的目标：解决用户在订单、物流、退货方面的真实问题。 可用工具：查询订单信息、查询物流轨迹、提交退货申请。 处理规则： 1. 用户没有提供订单号时，先询问，不要猜测。 2. 所有工具返回的数据必须如实转述，查不到就明确说查不到。 3. 退货申请必须核对订单状态和退货原因，条件不符时拒绝并说明原因。 4. 涉及地址、金额变更的操作，必须向用户二次确认后再执行。 输出格式：采用Thought/Action/Action Input/Observation格式执行，最终答案必须是对用户友好的自然语言。

工具Schema长这样，注意每个字段的描述都写清了取值边界：

[ { "name": "get_order_info", "description": "根据订单号查询订单基本信息，包括订单状态、商品、金额、收货地址。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "用户提供的完整订单号，形如ORD-2025-001234，必须是有效格式" } }, "required": ["order_id"] } }, { "name": "get_logistics_track", "description": "查询订单的物流轨迹，返回揽收、转运、派送等节点信息。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "关联的订单号" } }, "required": ["order_id"] } }, { "name": "apply_return", "description": "提交退货申请，仅当订单状态为已签收且未超过七天时可用。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号" }, "reason": { "type": "string", "description": "退货原因，限填：质量问题/七天无理由/发错货" } }, "required": ["order_id", "reason"] } } ]

实操心得：函数描述里那句“形如ORD-2025-001234”不是废话。模型对格式的理解完全依赖描述里的例子，你给什么样的示例，它就按什么样去解析，这是提升工具调用成功率成本最低的一招。

4.3 ReAct主循环实现

主循环是所有Agent的发动机，我用的简化实现如下。这段代码不依赖任何第三方框架，目的是让你看清循环的本质：

import json import time MAX_STEPS = 10 def run_agent(user_message, memory, tool_executor): messages = [{"role": "system", "content": SYSTEM_PROMPT}] messages.extend(memory) # 历史上下文 messages.append({"role": "user", "content": user_message}) for step in range(MAX_STEPS): # 调用模型，要求它输出Thought/Action格式 response = model_chat(messages) content = response["content"] print(f"[Step {step}] {content}") # 解析模型的Action字段 action = extract_action(content) # 模型认为任务已结束 if action is None: final_answer = extract_final_answer(content) return final_answer # 模型想调用工具 if action["name"] in tool_executor: result = tool_executor[action["name"]](**action["arguments"]) observation = {"observation": result} else: observation = {"observation": "tool_not_found"} # 把模型这轮的输出和工具结果都追加到消息序列 messages.append({"role": "assistant", "content": content}) messages.append({"role": "tool", "content": json.dumps(observation, ensure_ascii=False)}) return "抱歉，这个问题比较复杂，已经转人工处理。"

model_chat是统一封装的模型接口，tool_executor是工具注册表，extract_action负责从模型文本里解析结构化动作。这里最关键的细节是消息序列的累积方式：模型的每一轮输出和每一次工具返回都要按顺序追加，模型才能看到完整的思考链路。丢一环，后面的决策就断了。

4.4 记忆与上下文压缩

ReAct循环跑几轮之后，上下文会快速增长。长对话里，用户的问题可能很简单，但前面的思考过程、工具返回日志全都在，输入很快就臃肿了。AgentX上线第一周就遇到上下文超限，我当时的处理方案是“摘要压缩”。

每经过N轮，就把之前的对话交给模型生成一段摘要，用摘要替换掉原文，只保留最近两轮完整对话。代码如下：

def compress_history(messages, keep_last=2): # 找出可以压缩的历史部分（从system之后到倒数keep_last轮之前） history = messages[1: -keep_last * 2] if len(messages) > keep_last * 2 else [] if len(history) < 4: return messages # 让模型把history压成一段摘要 summary_prompt = "请把以下Agent运行日志压缩成一段摘要，保留用户诉求、已执行的动作、关键结论，不超过200字：\n" + json.dumps(history, ensure_ascii=False)[:6000] summary = model_chat([{"role": "user", "content": summary_prompt}])["content"] # 用摘要替换历史部分 new_messages = [messages[0], {"role": "system", "content": f"对话历史摘要：{summary}"}] new_messages.extend(messages[-keep_last * 2:]) return new_messages

长期记忆我另建了一张简单的用户画像表，当用户在对话里提到偏好（比如“我一般用顺丰”），会抽出来写进用户画像，后续会话开始前自动注入。这里要注意：抽取偏好也要走模型，但触发条件必须严格控制，不能在每轮对话都做抽取，否则成本会失控。

4.5 部署与监控：一个被很多人忽略的环节

AgentX上线前，我把很大精力花在监控上。Agent的输入输出不是固定结构的，传统接口监控根本不够。

我给整个系统加了三层日志。第一层是完整链路日志，记录每一次模型请求的输入、输出、工具调用、返回结果、耗时和Token数，一条都不能漏。第二层是运行时状态快照，每轮循环结束后记录当前的消息长度、累计Token、步数，用于事后复盘。第三层是用户反馈埋点，在对话结束时让用户点“满意/不满意”，不满意的话自动保存全链路日志供人工分析。

监控数据积累一周后，你会非常直观地看到：哪类问题导致Agent频繁重试，哪些工具调用失败率最高，哪些Prompt场景下模型输出格式经常解析失败。没有这套数据，后续优化全部靠猜，这是Agent项目里最要命的事。

5. 实战中高频踩坑与排查技巧实录

5.1 模型幻觉与编造工具结果

Agent开发里最可怕的问题不是工具调用失败，而是模型“假装调用成功”。它可能在文本里输出“已完成退货申请”，但实际上你的代码根本没收到apply_return的调用请求。

解决思路有三层。第一层是输出约束，要求模型严格按照结构化格式输出动作，凡是解析不到合法动作的一律视为“未执行”，不给用户承诺。第二层是结果校验，工具执行函数返回时必须带状态码，异常状态要原样反馈给模型，禁止模型自己脑补成功。第三层是话术兜底，在System Prompt里写明“只有收到工具执行成功回执，才能告知用户操作完成；否则必须说‘系统正在处理，请稍后’”。

5.2 上下文爆炸与Token成本失控

单个会话在长任务中轻松消耗几万甚至几十万Token，这在Agent项目里非常普遍。成本失控通常不是模型的错，而是工程没做好。

我常用的三板斧：压缩，按前面说的摘要策略定期压缩历史；检索，长期记忆和资料不要全量塞，而是向量化后只召回Top K；分流，低频子任务用便宜的小模型执行，只有需要复杂推理时才上大模型。另外，工具返回结果也要做裁剪，按接口只把当前决策需要的字段返回给模型，能省下大量重复Token。

注意：千万别用“截断”代替“压缩”。简单地把上下文从末尾砍掉，等于让Agent失忆，前面的任务信息全丢了，后面它就会开始胡言乱语。截断只用于兜底，压缩才是常规手段。

5.3 Agent死循环与任务漂移

Agent死循环有两种：一种是字面意义的无限循环，模型反复调用同一个工具或重复同一个动作；另一种是任务漂移，模型做着做着把最初的目标忘了，开始回应与任务无关的内容。

字面循环用最大迭代次数兜底就能解决，问题不大。任务漂移要靠两件事：一是把初始任务目标固化在System Prompt里，并且每一轮都让模型自行核对“当前动作是否与目标一致”，不一致就拉回；二是在压缩摘要时必须保留“原始任务目标”这一项，不能摘要一压就把任务初衷压没了。

我在AgentX里就在压缩模板里强制加了“原始用户诉求”字段，实测下来任务漂移率降了不少。

5.4 没有评测体系，上线就是裸奔

这是我最想强调的一点。很多团队把Agent做完就上线，觉得“反正有AI兜底”，结果线上事故频出。Agent的自主性意味着不可预测，不可预测的系统的唯一防线就是评测。

我从第一天起就建了一个评测用例集，目前有几百条，覆盖正常路径、异常路径、边界输入和对抗输入四类。每次改Prompt或换模型，都在这个集上跑回归，对比输出质量和工具调用准确率。选模型时的函数调用能力测试，也用的是这同一套用例。

线上还要设两个指标：任务完成率和人工介入率。任务完成率是“Agent在无人工干预下成功解决用户问题的比例”，人工介入率是“用户在对话中主动要求转人工的比例”。这两个指标一升一降，就是Agent质量最真实的体检表。

下面是我整理的高频问题速查表，基本覆盖了Agent项目最常见的故障：

6. 进阶：多Agent协作和复杂任务编排

6.1 多Agent的三种协作模式

单Agent能解决的业务终究有限，复杂一点的场景就要上多Agent。基于我的项目经验，多Agent协作有三种常见模式。

第一种是路由模式，一个入口Agent负责理解用户意图，把请求分发给下游专业Agent，比如订单Agent、售后Agent、优惠券Agent各管一段。好处是每个Agent的上下文很干净，互不污染；缺点是路由判断一旦出错，整个链路就歪了。

第二种是编排模式，一个主Agent当“项目经理”，拆解任务并调度多个执行Agent。执行Agent各自完成子任务，把结果汇总给主Agent做最终输出。这种模式适合跨系统协同，但主Agent本身可能成为瓶颈。

第三种是群体协作模式，多个Agent带着各自的视角互相讨论、评审，最后达成共识。适合方案生成、代码评审这类需要多视角的场景，但成本高、延迟高，生产环境慎用。

6.2 状态管理与数据流转

多Agent最核心的工程问题，是状态和数据怎么在多个Agent之间流转。我见过最乱的做法，是把一个Agent的全部消息历史直接塞给另一个Agent，美其名曰“交接上下文”，结果下游Agent收到一堆无头无尾的日志，效果一塌糊涂。

正确做法是定义清晰的任务上下文对象。每个Agent只接收结构化输入和产出结构化输出，中间数据放在共享状态容器里。比如入口Agent产出{"user_intent": "return", "order_id": "ORD-..."}，售后Agent只消费这个对象，不关心入口Agent之前的内心戏。这样既隔离了上下文，也方便每个环节单独测试和替换。

另外，多Agent之间的通信格式必须提前定好。JSON Schema是基本操作，字段命名要全组统一，最好再有版本号，不然以后字段一变，所有下游全部崩掉。

6.3 成本与延迟：多Agent的代价

多Agent不是银弹，它的代价非常具体。每多一个Agent，就多一轮甚至多轮模型调用，延迟和成本线性上升。一个四Agent协作的场景，用户等一个答案可能要几十秒，这在客服场景里几乎不可接受。

我的优化思路是把多Agent用在“后台异步任务”上，而不是用户实时交互链路上。比如用户提交申请后，后台由一个几个Agent组成的流程去处理，处理完再通过消息推送结果，用户不需要一直干等。实时对话链路能单Agent解决就单Agent，这是我从成本和体验两个维度反复权衡后的结论。

7. 落地过程中的几个原则性体会

写到最后，我不打算做什么宏大总结，就说几条在项目一线反复验证过的原则。

第一，Agent的可靠性不是靠模型“变聪明”堆出来的，而是靠工程结构控制的。规划规则、工具Schema、日志、评测、兜底循环，每一环都值得花时间打磨，这些比换更强的模型更能提升整体表现。

第二，先跑通最小闭环，再叠加记忆和多Agent。我见过太多项目一上来就设计六个Agent，结果连单Agent的循环都没跑顺。一个稳定、可控、能部署的单Agent，远比一个华丽但随时失控的多Agent体系有价值。

第三，不要把用户当测试者。Agent上了线，每一句话都是对真实用户的承诺。宁可多转人工，也不能把幻觉和错误结果直接甩给用户。给所有关键动作加权限校验层，这是Agent工程里没有妥协空间的底线。

最后分享一个小经验：把每一条失败的线上案例都倒回你的评测集里。每遇到一次翻车，就把它沉淀成一条回归用例，再修Prompt、修逻辑，直到这条用例通过。这样做的结果是，你的评测集越跑越厚，Agent的可靠性越修越稳——比起任何理论框架，这一套笨办法才是最值得长期坚持的。