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 CallingOpenAI、Anthropic 等模型都原生支持结构化工具调用。模型直接输出一个 JSON 格式的函数调用指令你说调用 search_products入参是 参数它就在代码里执行这个函数。这种方式最稳定是目前的主流。MCPModel 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_keyyour_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( modelqwen-plus, messagesmessages, toolsTOOLS, tool_choiceauto ) 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_asciiFalse) }) 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然后在代码层校验当前会话角色允许调用的权限标签列表一旦模型试图调用不在权限列表里的工具直接拦截并返回错误你没有权限执行该操作。这个校验要写在框架层不能指望模型自己判断。我把上面这些场景整理成一个速查表方便你对照排查症状根因排查方向解决方案无限循环调用工具工具返回信息不足或不可理解检查工具返回的结构化程度给工具返回增加 status data error_message模型编造参数工具描述不清晰检查工具 description 是否覆盖参数细节像写接口文档一样写工具描述带格式和取值范围长对话质量下降上下文被无关信息污染检查历史消息中是否有冗余内容实现记忆压缩把旧对话压成保留关键信息的摘要越权调用工具工具暴露范围过大、缺少权限校验检查工具注册层和调用链路的权限控制在框架层加白名单校验不等模型自我约束6. 聊聊我现在对 Agent 工程实践的整体感受文章写到这里主体内容就结束了。最后想聊点不那么教程的东西。我 2025 年以来接触到的 Agent 项目里真正成功的那些没有一个是在炫技路线上去追求最复杂的架构恰恰相反它们都有一个共同特征把每一步都做简单但把边界条件全都想清楚。把 Agent 想象成一个花瓶模型只是一部分原料真正的工程是在给它搭架子。架子搭得稳模型才有机会发挥智能架子搭得松模型再强也站不住。在实操中我的体会是Agent 这个领域最反直觉的地方在于它越接近工程化你就越要回归工程常识。状态管理、日志、权限、容错、缓存、成本核算——这些传统软件工程里的老生常谈在 Agent 项目里一样也没有少只是多了模型决策这个不确定因素。最后再分享一个小技巧开发 Agent 的时候永远用一个专门的日志文件来记录模型的每一个决策及其理由不要和普通业务日志混在一起。因为这个决策轨迹既是排障的关键也是你不断改进提示词和工具描述的重要依据。你看着那一条条日志会慢慢发现模型的决策模式和你的预期在哪些地方发生了偏移而那些偏移点往往就是整个系统真正的优化空间。
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 CallingOpenAI、Anthropic 等模型都原生支持结构化工具调用。模型直接输出一个 JSON 格式的函数调用指令你说调用 search_products入参是 参数它就在代码里执行这个函数。这种方式最稳定是目前的主流。MCPModel 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_keyyour_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( modelqwen-plus, messagesmessages, toolsTOOLS, tool_choiceauto ) 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_asciiFalse) }) 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然后在代码层校验当前会话角色允许调用的权限标签列表一旦模型试图调用不在权限列表里的工具直接拦截并返回错误你没有权限执行该操作。这个校验要写在框架层不能指望模型自己判断。我把上面这些场景整理成一个速查表方便你对照排查症状根因排查方向解决方案无限循环调用工具工具返回信息不足或不可理解检查工具返回的结构化程度给工具返回增加 status data error_message模型编造参数工具描述不清晰检查工具 description 是否覆盖参数细节像写接口文档一样写工具描述带格式和取值范围长对话质量下降上下文被无关信息污染检查历史消息中是否有冗余内容实现记忆压缩把旧对话压成保留关键信息的摘要越权调用工具工具暴露范围过大、缺少权限校验检查工具注册层和调用链路的权限控制在框架层加白名单校验不等模型自我约束6. 聊聊我现在对 Agent 工程实践的整体感受文章写到这里主体内容就结束了。最后想聊点不那么教程的东西。我 2025 年以来接触到的 Agent 项目里真正成功的那些没有一个是在炫技路线上去追求最复杂的架构恰恰相反它们都有一个共同特征把每一步都做简单但把边界条件全都想清楚。把 Agent 想象成一个花瓶模型只是一部分原料真正的工程是在给它搭架子。架子搭得稳模型才有机会发挥智能架子搭得松模型再强也站不住。在实操中我的体会是Agent 这个领域最反直觉的地方在于它越接近工程化你就越要回归工程常识。状态管理、日志、权限、容错、缓存、成本核算——这些传统软件工程里的老生常谈在 Agent 项目里一样也没有少只是多了模型决策这个不确定因素。最后再分享一个小技巧开发 Agent 的时候永远用一个专门的日志文件来记录模型的每一个决策及其理由不要和普通业务日志混在一起。因为这个决策轨迹既是排障的关键也是你不断改进提示词和工具描述的重要依据。你看着那一条条日志会慢慢发现模型的决策模式和你的预期在哪些地方发生了偏移而那些偏移点往往就是整个系统真正的优化空间。
