企业官网建设流程全解析

1. 先搞明白：Agent 到底和普通程序有什么区别

我见过太多人一上来就聊 Agent 的架构、框架、多智能体协作，结果连最基础的问题都没想清楚：Agent 和一段普通的代码逻辑，本质区别在哪里？

普通的程序是"确定性执行"：你写 if-else、写循环、写 API 调用，每一步都是预先定义好的。输入固定，输出基本可预期。而 Agent 的核心是"模型驱动决策"：它拿到一个目标后，自己决定先做什么、再做什么、用什么工具、怎么拆解任务。这个过程是概率性的、动态的，每一次运行的路径都可能不一样。

你可以把这个区别想象成两种员工：

• 普通程序是流水线工人，你告诉他"拧三下螺丝，然后搬到下一站"，他就照做，永远不出错，但也不会变通。
• Agent是拿底薪的实习生，你告诉他"把这块表修好"，他需要自己观察表哪里坏了、找螺丝刀还是找扳手、修完自己检查一下有没有装反。他可能干得很好，也可能把螺丝拧花了。

所以我们聊 Agent 的工程实现，本质上是在解决一个问题：怎么把"大模型的智能"稳定地封装成一个可以在生产环境里跑的业务系统。这不是写一个 prompt 的事，而是涉及模型选型、上下文管理、工具调用、状态持久化、异常处理、成本控制、安全边界等一系列工程决策。

我是从 2023 年开始接触 Agent 开发的，前后折腾过个人玩具项目、也给企业做过客服和内部提效的 Agent 系统。最早大家都用"一个 prompt + 一个循环"的方式糊弄事，后来发现往生产环境一放就崩，崩在各种各样的地方。这篇文章我想把这段时间踩过的坑和验证过的方法梳理出来，围绕标题里说的"七要素"和"七个决策点"展开，算是一份从设计到落地的工程笔记。

无论你是刚准备入门 Agent 开发、正在选型，还是已经写了几版但总觉得不可控，这篇文章都值得你花十分钟读完。

2. 七要素拆解：一个 Agent 最少需要哪些零件

很多人觉得 Agent 就是"模型 + 工具"。真上手做工程你就会发现，这个认知过于乐观。我习惯把一个完整的 Agent 系统拆成七个要素，缺任何一个，在开发环境里可能看不出来，一到线上就出事。

2.1 要素一：感知层（Perception）

感知层负责把外部信息接进来。别小看这一步，它决定了 Agent 能看到什么、看多准。

用户输入的原始内容往往是脏的：多模态数据要解析、文本要清洗、指令和闲聊要分流。比如你做客服 Agent，用户发来的一句话可能是"我想查一下我上个月的账单，哦对了顺便问问退货流程"，这句话里包含两个意图，感知层要先做意图识别，再决定是把任务全部传给 Agent，还是拆成两个子任务分别处理。

感知层还有个容易忽略的点：时效性。Agent 需要的很多信息不在 prompt 里，而在外部系统里。你需要在感知阶段就明确哪些信息实时拉取、哪些信息走缓存，否则 Agent 每轮对话都去查一遍数据库，延迟和成本都受不了。

2.2 要素二：规划（Planning）

规划是 Agent 的"大脑皮层"。模型收到任务后，要把一个模糊的指令拆成一个可执行的步骤序列。

现在市面上常见的规划方式有三种：

• 直接执行：任务简单，模型一次生成完整答案，不需要拆分。
• 逐步规划：模型先生成 Step 1、Step 2、Step 3，然后逐步执行，每一步都有独立的输入输出。
• 动态重规划：执行过程中根据中间结果动态调整计划。比如 ReAct 模式里，模型每走一步就思考一下"现在该用什么工具、下一步做什么"。

这里我强烈建议：不要让 Agent 一次性规划完所有步骤。以我的实测经验，一次规划完再执行的方式，在步骤超过三步之后就很容易出现"计划赶不上变化"——模型第一步执行的输出和它计划里预想的不一样，后面的步骤全乱套。相比之下，ReAct 这种"边做边想"的动态循环，稳定性要高得多。

2.3 要素三：记忆（Memory）

记忆是 Agent 工程里最容易被低估的要素。通常需要区分三个层次：

• 短期记忆：当前会话的上下文，存储在 prompt 的上下文窗口里。这是最直接的内存，但也最容易爆。
• 长期记忆：跨会话的知识，存在向量数据库或外部键值存储里，需要时检索出来塞回上下文。可以类比成人的长期记忆，不会每次都浮现在脑海里，但需要时能想起。
• 工作记忆：Agent 在执行多步骤任务时的中间状态，比如"这个任务我已经做到第几步了、已经拿到了哪些数据"。这个通常需要程序化地管理，不能全依赖模型自己记住。

我见过太多项目把向量数据库当成万能药，动不动就把所有历史都灌进 prompt，然后 token 成本爆炸、模型在无关信息里迷失。我的经验是：记忆要分层，检索要带条件。能放在程序状态里管理的就放程序里，只有真正需要模型"理解"的内容才放进上下文。

2.4 要素四：工具使用（Tool Use）

工具是 Agent 能力的延伸。没有工具的 Agent 只是一个能用嘴皮子聊天的模型，有了工具它才能查数据库、调接口、发邮件、操作软件。

工具使用在工程上有三个关键词：定义、注册、容错。

定义是指用 JSON Schema 或函数签名描述工具的入参出参、用途、触发条件。注册是把这些描述交给模型，让模型知道"我有哪些工具可用"。容错则是处理工具调用失败的情况——工具接口超时、返回格式错误、权限不够，都是常态。

一个很重要的点是：工具数量不要贪多。模型在太多工具之间做选择时，准确率会明显下降。我实测过，一次性暴露超过 15 个工具给模型，它就经常选错工具或者编造不存在的参数。更合理的做法是分场景注册，用路由层先把任务导向某个工具子集。

2.5 要素五：行动执行（Action）

规划告诉 Agent 该做什么，行动执行则真正去"做"。这里的工程点在于：谁来执行？

有两种典型模式：

• 模型调用工具：模型直接生成工具调用指令，由 Agent 框架或代码来执行这个工具，然后把结果返回给模型。这是最主流的模式，简单直接。
• 代码驱动行动：Agent 规划出任务后，由预编写的代码逻辑去执行，模型只负责决策和异常情况处理。这种模式更可控，但灵活性稍差。

我的建议是：凡是确定性的操作，能用代码写死就用代码写死，不要交给模型去"自由发挥"。比如 Agent 需要按照固定格式写文件，这种操作就应该由程序直接执行，模型只用填充内容参数。模型负责"怎么决定"，程序负责"怎么执行"，各司其职才不会崩。

2.6 要素六：反思修正（Reflection）

反思是让 Agent 从错误里爬出来的能力。没有反思的 Agent，一旦中间某一步出错，会带着错误一路狂奔到终点，最后给你一个一本正经但完全错误的结果。

工程上实现反思有两个层次：

• 内置循环：像 Reflexion 框架那样，在任务执行过程中增加一个评估节点，检查中间结果是否合理，不合理就回退重来。
• 外置评估：用另一个模型（或规则引擎）来 review Agent 的输出，打分或标记问题，再交给主 Agent 修正。

外置评估的效果通常更好，因为"自己检查自己"天然就有盲区。我常用的做法是：用一个小模型或者规则集做输出校验，比如日期格式、金额计算、敏感词过滤，不合格就重新生成。成本低，效果立竿见影。

2.7 要素七：安全与边界（Safety & Guardrails）

安全不是上线前才考虑的东西，而是从设计第一天就要想清楚的约束条件。

Agent 的边界至少包括：

• 权限管控：Agent 能调用的工具要有最小权限，不能拿一个拥有全库权限的数据库账号。
• 输出审核：Agent 生成的内容发送给用户之前，要过敏感信息检测、合规校验。
• 任务范围限制：有些任务不能开放给 Agent，比如对外发消息、删除数据，这些操作要么禁止执行，要么必须经过人工确认。

我见过一个很经典的翻车案例：某公司给 Agent 接了内部运维工具，Agent 在排查问题时"灵机一动"直接执行了数据库删除操作，生产数据没了。后来他们花了很大精力加了"高危操作需人工审批"的护栏，才解决问题。安全边界不是限制 Agent 的能力，而是保护你不被 Agent 的能力反噬。

3. 七个决策点：工程实现中真正决定成败的选择

七要素解决的是"有什么"，七个决策点解决的是"怎么选"。这些决策不写在教科书里，但它们决定了你的 Agent 是玩具还是生产力工具。

3.1 决策点一：模型选型——一个"全能王"还是多个"专项工"？

这是整个工程里最基础也最关键的决策。

现在的模型市场供给很丰富：有超大参数模型（GPT-4o、Claude 最高档位等），有小模型（Llama-3-8B、Qwen-2.5-7B 等），还有专门做分类、摘要、代码生成的各种微调模型。你面对的选择不是"哪个模型最强"，而是"什么样的模型组合最划算"。

我的经验是：永远不要只用一个大模型做所有事。成本模型完全不一样，且超大模型在某些简单任务上的表现并不比小模型好多少。现在的标配做法是："大模型做规划和小模型做垃圾分类"——主 Agent 负责复杂推理和任务拆解，分类、抽取、格式化这些子任务全交给小模型跑。这样做的好处是，小模型响应快、便宜，还能并行处理。

结合我开始说的"实习生"类比：你不会让一个高级工程师天天去给文档排版，对吧？里面的控制逻辑是一样的。

3.2 决策点二：上下文管理——是"全塞进去"还是"按需检索"？

上下文管理直接决定你的 token 成本和模型输出质量。

常见的方式有三种：

• 全量上下文：把对话历史、知识库内容全部塞进 prompt。适合短对话、信息量少的场景。
• 滑动窗口：只保留最近 N 轮对话作为上下文。适合长对话的场景，但会丢失早期信息。
• RAG（检索增强生成）：按需从知识库检索相关内容，然后拼进 prompt。适合知识密集型场景。

我的实际用法是"滑动窗口 + RAG"组合：对最近几轮对话全量保留，对更早的内容只保留摘要或向量索引，需要时检索。这里给一个具体建议：在你的上下文里加一个"记忆压缩"节点，每过几轮或者当上下文快要满的时候，让模型把之前的对话压缩成一个简述，然后丢到长期记忆里。这个技巧在长对话场景中能省下海量 token。

3.3 决策点三：工具调用的技术方案——Function Calling、MCP 还是纯手工解析？

工具调用是 Agent 和外部世界交互的通道，选择什么样的技术方案直接关系到开发效率和兼容性。

• 原生 Function Calling：OpenAI、Anthropic 等模型都原生支持结构化工具调用。模型直接输出一个 JSON 格式的函数调用指令，你说"调用 search_products，入参是 参数"，它就在代码里执行这个函数。这种方式最稳定，是目前的主流。
• MCP（Model Context Protocol）：这是 2024 年底开始火起来的一个开放协议，它把工具调用标准化了：服务端把工具暴露成统一接口，客户端通过协议和它交互。好处是生态互联互通，一个 MCP Server 可以被多个 Agent 公用。如果你准备做一套 Agent 平台、要对接多种外部系统，MCP 值得认真考虑。
• 纯手工解析：让模型输出文本描述，你用正则匹配去解析操作关键词。这是最早期的做法，但现在基本不建议用——模型输出稍微带点歧义，解析就会翻车。

我的建议是：如果你只做单机场景、用主流云厂商模型，直接用原生 Function Calling，别自己造轮子。如果你要打通多个内部系统、有多种 Agent 共享工具的需求，再引入 MCP 层做标准化。个人项目和企业级项目的边界不一样，不要为了追新技术给自己加复杂度。

3.4 决策点四：任务编排架构——单 Agent、多 Agent 还是 Workflow？

任务编排是 Agent 工程中最容易过度设计的地方。

我见过很多人一上来就搞"主管 Agent + 多个子 Agent"的架构，结果系统复杂、调试困难，产出却不比单个 Agent 好多少。我的经验是：先单后多，能用最小方案解决就绝不上复杂架构。

• 如果任务是一个线性的步骤序列，用 Workflow（工作流）就够了：定义好步骤，每一步按顺序执行，不需要"决策"环节。
• 如果任务需要动态拆分、需要并行探索不同的策略，再考虑多 Agent 架构。
• 如果任务只需要"一个大脑 + 几个工具"，那就老老实实写一个单 Agent 循环。

典型的反模式：做一个简单的"总结今天工作"的 Agent，非要拆成"收集信息 Agent + 总结 Agent + 写作 Agent"三个，每个 Agent 还要有自己的系统提示词。最后结果和单 Agent 没区别，却多了两次模型调用和两次上下文传输的延迟和成本。

多 Agent 协作是 2025 年的热词没错，但工程的第一原则是"做最少的事达成目标"，而不是"把所有热门概念都塞进来"。你后面还打算维护这个系统，维护成本是被很多人忽视的隐性成本。

3.5 决策点五：状态管理——Agent 不是无状态的，你的会话状态存在哪？

Agent 和普通 API 的一大区别是：Agent 是有状态的。它需要在多轮对话中记住话题，需要在多步骤任务中记录中间状态。

工程实现上有三个层级的持久化：

• 对话级状态：存在 Redis 或数据库里，用 session_id 关联。多轮对话之间需要共享的上下文，从数据库加载。
• 任务级状态：一个任务可能经历多个步骤，这期间产生的中间变量（"已经查到用户 ID、已经确认订单号"）需要保存在工作内存里。
• 外部状态同步：Agent 调用了外部系统，外部系统也可能改变状态，比如它通过工具下了一个订单并把状态改成"待支付"。这时候需要在 Agent 的框架层做状态反射。

我推荐至少用一套持久化方案：把会话状态存进 Redis，任务状态存进操作系统的临时存储或内存 cache，外部系统状态靠"查询核对"而不是"盲信本地缓存"。

3.6 决策点六：可观测性与调试——你打算怎么给 Agent 做"事后复盘"？

Agent 的可观测性比传统软件难得多。传统软件你能打印日志、看调用栈，但 Agent 的行动路径是模型生成的，每次都不一样，出了错很难复现。

我的痛点记忆很深刻：一个 Agent 在生产环境里偶尔会把用户的用户名搞丢，但本地怎么试都正常。后来我看了日志才发现，某些情况下用户的输入短导致模型跳过了"提取用户名"这一步——这种问题没有完整的行动轨迹日志，根本不可能定位。

所以我的建议是：

• 给每一轮 Agent 循环打详细的日志，包括：当前 prompt、模型输出、工具调用参数、工具返回结果、Agent 下一轮决策。
• 用 trace 工具把整个执行链路串起来。Langfuse 或 Phoenix 这类工具是 Agent 工程师的必备武器。你要能看到每一步的耗时、token 消耗和结果。
• 为 Agent 增加一个"回放模式"：把某次运行的完整 trace 存下来，下次调试时可以直接回放那个执行序列，模拟输入。这个特性在生产环境排障时极其有用。

3.7 决策点七：成本与延迟控制——你的 Agent 是"实时交互"还是"异步处理"？

成本与延迟是这个工程的最终关卡。一个 Agent 方案如果在技术上完美，但每次响应要 30 秒、成本要 5 毛钱，那它大概率无法落地。

控制成本有几个方向：

• 模型路由：先让一个小模型做意图分类，简单问题直接回答，复杂问题才路由到强模型。这类路由可以省掉 30%-50% 的超大模型调用。
• 缓存：对重复的、可语义匹配的请求做结果缓存。用 embedding 做近似匹配的缓存可以有效覆盖客服、FAQ 类常见问题。
• 减少无效循环：给 Agent 设置"最多执行 N 轮"的上限，防止它在失败路径上反复横跳烧 token。

延迟控制的思路正好相反：不能只缓存简单问题，复杂问题的执行链条要并行化。比如一个任务需要同时查库存、查价格、查物流信息，那就拆成并行的工具调用，而不是串行逐个调用。实测下来，合理的并行设计能把整体响应时间压缩 40% 以上。

决策点本身没有标准答案，但有一点是确定的标准：你的方案必须能算得过来经济账。一个 Agent 再怎么聪明，如果跑一次要一块钱，而业务上它产生的价值只有两毛钱，那这个方案就是个失败品。

4. 实操现场：从零搭一个最小可用的 Agent 系统

说完了理论，接下来是你们最想看的实操环节。我会用一个非常精简的示例，带你从零搭一个最小可用的 Agent。不要被"最小"两个字迷惑——它能跑通完整闭环，后续你只需要往里面加零件。

4.1 技术选型：我为什么这样选

技术栈的选择直接决定了开发的舒适度，我的选择如下（基于我个人习惯，你有更熟悉的技术栈可以平替）：

• 语言：Python。生态最全，做 AI 相关开发首选。
• Agent 框架：直接用模型原生的 Function Calling + 自己写循环逻辑，不用 Agent 框架。原因很简单：用框架确实方便，但框架会把模型的决策逻辑包在它的封装里，出了问题你不好调试。自己写的循环也就两百行代码，完全可掌控。
• 模型：我用的是 OpenAI-compatible 接口的 Qwen 系列模型（通义千问）。Rust 和 Django 是热搜词，但 Python 做原型验证足够快。如果你对性能有极致要求，Rust 是个好选择；如果你用 Django 开发业务系统，那把你的 Agent 集成成 Django 的一个 Service 层即可，两种场景我都做过，开发路径是通用的。
• 存储：Redis 存会话状态、SQLite 存用户数据。演示场景够用了。

4.2 代码骨架：一个最小 Agent 循环

我先把核心代码骨架贴出来，然后一行一行讲为什么是关键。

from openai import OpenAI from typing import Dict, List import json client = OpenAI(api_key="your_api_key", base_url="...") # 1. 工具定义池 TOOLS = [ { "type": "function", "function": { "name": "search_product", "description": "根据关键词搜索商品库存信息", "parameters": { "type": "object", "properties": { "keyword": {"type": "string", "description": "商品关键词"} }, "required": ["keyword"] } } }, { "type": "function", "function": { "name": "get_weather", "description": "获取指定城市的天气信息", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名称"} }, "required": ["city"] } } } ] # 2. 工具的具体实现 def search_product(keyword: str) -> str: # 实际项目中这里会查数据库或调库存服务 simulated_db = {"手机": "华为 Mate 60 有现货，4999 元", "电脑": "MacBook Air 有现货，7999 元"} return simulated_db.get(keyword, f"很抱歉，没有找到 {keyword} 的相关商品") def get_weather(city: str) -> str: simulated_weather = {"上海": "晴，25 度", "北京": "多云，20 度"} return simulated_weather.get(city, f"暂时拿不到 {city} 的天气数据") TOOL_DISPATCH = { "search_product": search_product, "get_weather": get_weather, } # 3. 核心 Agent 循环 def agent_loop(user_input: str, history: List[Dict]) -> str: messages = history + [{"role": "user", "content": user_input}] while True: response = client.chat.completions.create( model="qwen-plus", messages=messages, tools=TOOLS, tool_choice="auto" ) msg = response.choices[0].message if msg.tool_calls: messages.append(msg) for tool_call in msg.tool_calls: func_name = tool_call.function.name args = json.loads(tool_call.function.arguments) result = TOOL_DISPATCH[func_name](**args) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(result, ensure_ascii=False) }) else: return msg.content history = [ {"role": "system", "content": "你是一个智能客服助手，回答问题简洁、准确。"} ] print(agent_loop("帮我查询一下手机库存", history))

这段代码虽然只有几十行，但它已经完整覆盖了前面七要素里的核心部分：

• 感知层：user_input进来了，直接作为用户消息传进循环。
• 规划与行动：模型根据TOOLS的描述决定是否调用工具、调用哪个工具、传什么参数。这就是"决策"环节。
• 工具使用：TOOL_DISPATCH这个字典把函数名映射到真实函数上，工具调用结果通过tool角色的消息回传给模型。
• 循环控制：只要模型输出tool_calls就继续循环，直到模型给出最终的文本回答。

这个骨架最大的优点是：你看得见每一步发生了什么。模型决定调用什么工具、工具返回了什么，你都可以在循环里加日志打印出来。

4.3 把 Agent 从开发环境搬到生产环境的四个改造

上面的代码只是骨架，直接上生产肯定不行。我在不同项目里反复使用过四种改造手法，你照着做就行。

首先是加状态持久化。agent_loop 里的history是纯内存的，进程一重启就全没了。生产环境你要把 history 存进 Redis，用 session_id 做 key，每次用户发消息先把历史 load 出来，对话结束再把新的消息追加进去并写回。注意别把整个 list 无脑存，要设置一个 TTL（比如 24 小时），防止 Redis 里面囤积一堆僵尸会话。

然后是加工具返回的校验层。真实世界的工具返回不是那么干净，拿到的可能是"接口超时""权限不足"这类异常。我写了个safe_call包装器，工具函数统一经过它执行，异常会被捕回来转成一个标准错误格式返回给模型，让模型决定是换个工具重试、还是告诉用户"当前服务不可用"。这样一来，工具方面的任何状况都不会让整个 Agent 崩溃。

这四个改造里我最重视的是加迭代上限。不加max_iters = 10之类的限制，你迟早会看到生产环境里某个 Agent 陷入无限循环烧 token 的惨状。我的做法是在循环外面套个计数器，达到上限就把当前状态写日志，然后给用户返回一句"抱歉，我没能完成你的请求"。这个设计很多人觉得没必要，直到他们半夜收到一条几千块 token 账单的告警。

最后是加安全护栏。在这个最小系统里，唯一的护栏是"我把工具列表暴露给了模型"。现实中你要考虑：哪些工具走人工审批、哪些数据不能返回给模型（比如其他用户的信息）、模型的输出是否需要二次审核。这些护栏不写在循环代码里，而是写在工具注册层的权限判断里。

4.4 关于"Agent 的 token 是什么意思"：算清楚你的账

标题下面有一批热搜词是关于 token 的，很多新手问"Agent 的 token 到底是什么"。我顺手说清楚。

Token 是模型处理文本的最小单位。英文里一个 token 大约是 4 个字符，中文里一个字大约 1-2 个 token。Agent 在跑一轮任务时产生 token 的地方不止一处：

• 输入的 prompt：系统提示词、对话历史、检索到的知识，都要算 token。
• 模型的输出：最终回答和中间推理过程，都算 token。
• 工具调用的参数和返回结果：这部分也全部算 token，而且往往是最容易被低估的。

你算账的时候不能只看"模型输出"，要看整条链路。我给你一个经验值：一个典型的多轮 Agent 对话，工具调用产生的中间流量常常是最终输出的 3-5 倍。所以做成本控制一定要盯紧工具调用这个环节，尤其是你给模型返回的工具结果，能精简就从源头精简。

比如get_weather返回{"city":"上海","temp":25,"humidity":60,"wind":"东北风3级","warning":null}，这个 JSON 里有十几个字段，但实际回答用户"上海今天 25 度"只需要温度和城市。工程上的优化方向就是：尽量让工具本身的返回精简，同时可以让模型对长返回做摘要后再放入上下文。

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

Agent 开发十个星期，有九次时间都在排查问题。这一节我把最常遇到的四类问题整理成速查表，并附上我的定位思路。大部分问题不是我独有的，很多 Agent 初学者都会踩到。

5.1 症状：Agent 陷入"调用工具 → 返回异常 → 重新调用"的死循环

这是最常见的问题。现象是日志里全是同一个工具调用的重复记录，token 消耗飞速上涨，但 Agent 就是不给出最终答案。

定位思路：先看工具返回是不是"不可理解的错误"。你要站在模型的视角看问题——它拿到的工具返回如果是{"error": "Internal Server Error"}但没有任何细节，它很难判断是应该重试、换工具、还是直接把错误告诉用户。一个好的工具返回应该像给同事的反馈："订单查询失败，原因是订单号格式不正确，请检查订单号是否包含字母。"

解法：给工具结果做一个结构化标准，强制要求工具返回包含status（成功/失败）、data（成功数据）、error_message（人类可读的错误说明）三个字段。模型看到这个结构之后，就不用瞎猜了。

5.2 症状：模型开始"胡编"工具参数，调用明明不存在的函数

模型在"自由发挥"的场景下，会把工具的入参编造得看起来合理，但实际执行根本不可能成功。

典型的翻车场景是搜索工具的参数带了sort_by，但你定义的 description 里根本没提这个字段。模型的云想象会自行补全，而这个补全往往和你接口定义不一致。

定位思路：这是工具定义的语义不够清晰导致的。很多人写工具的description时只写一句"搜索商品"，但没告诉模型"这个工具支持哪些参数、参数取值范围是什么、什么时候该用这个参数"。

解法：把工具描述当作你在给一个初级程序员写接口文档。每一个参数都要写清楚格式（比如"date 格式 YYYY-MM-DD"）、取值范围（"type 只有 sale / regular 两个值"）、空值处理（"如果 keyword 为空，返回最近 10 条商品"）。描述写得越细，模型胡编的概率越低。

5.3 症状：对话历史越长，Agent 的响应质量反而下降

你也许遇到过这种状况：和 Agent 聊到十几轮之后，它开始答非所问，甚至忘记最开始给它的指令。

根源：上下文里塞进了太多无关信息。对话久了，历史消息里有一堆"哦""好""谢谢"之类的冗余内容，模型在这些噪音里找不到真正重要的约束条件。

解决思路：带"压缩"的滑动窗口。我的方案是写一个compress_history函数，当窗口里的消息超过 N 轮时，触发一次记忆压缩：让模型把之前对话的核心信息整理成一段摘要，然后把摘要替换掉原始消息。摘要的 token 消耗远低于原始对话，但关键信息一条都不会丢。

我踩过最大的坑是：压缩时只保留了用户的需求，丢了用户说过的偏好语气，导致后续回答风格突变了。所以现在我在压缩指令里会特别注明"保留用户的语气偏好和情感倾向"。

5.4 症状：Agent 作出了越权操作（调用了一个不该调用的工具）

这是安全层面的严重事故。比如一个客服 Agent 应该只查订单，却默默调用了用户管理接口。

定位思路：Agent 会不会越权，完全取决于你给它发了什么工具。你一旦把工具清单暴露给模型，它就有概率"自行发挥"。这不是模型坏，而是它的决策边界太宽了。

解法：在工具注册层加白名单约束。具体做法是给每个工具打一个"权限标签"（比如read:order、write:user），然后在代码层校验：当前会话角色允许调用的权限标签列表，一旦模型试图调用不在权限列表里的工具，直接拦截并返回错误"你没有权限执行该操作"。这个校验要写在框架层，不能指望模型自己判断。

我把上面这些场景整理成一个速查表，方便你对照排查：

6. 聊聊我现在对 Agent 工程实践的整体感受

文章写到这里，主体内容就结束了。最后想聊点不那么"教程"的东西。

我 2025 年以来接触到的 Agent 项目里，真正成功的那些，没有一个是在"炫技"路线上去追求最复杂的架构，恰恰相反，它们都有一个共同特征：把每一步都做简单，但把边界条件全都想清楚。

把 Agent 想象成一个花瓶，模型只是一部分原料，真正的工程是在给它搭架子。架子搭得稳，模型才有机会发挥智能；架子搭得松，模型再强也站不住。

在实操中我的体会是，Agent 这个领域最反直觉的地方在于：它越接近工程化，你就越要回归工程常识。状态管理、日志、权限、容错、缓存、成本核算——这些传统软件工程里的老生常谈，在 Agent 项目里一样也没有少，只是多了"模型决策"这个不确定因素。

最后再分享一个小技巧：开发 Agent 的时候，永远用一个专门的日志文件来记录"模型的每一个决策及其理由"，不要和普通业务日志混在一起。因为这个决策轨迹，既是排障的关键，也是你不断改进提示词和工具描述的重要依据。你看着那一条条日志，会慢慢发现模型的决策模式和你的预期在哪些地方发生了偏移，而那些偏移点，往往就是整个系统真正的优化空间。