Agent系统怎么搭过去一年里我被问过不下几十次。不少团队拿着一个“跟大模型对话”的Demo就称之为Agent然后跑来问怎么优化——我的回答通常是你还没有Agent你只是给聊天框加了一层自动回复。真正意义上的Agent系统“搭”出来的不是一个模型调用封装而是一条从目标到结果的完整生产线。前阵子我帮某交付团队把一个合同审查流程改造成Agent驱动的自动化管线才把“方法论”和“理想形态”这两件事从书本里拖出来变成了能交付、能评估、能上线的东西。这篇文章想讲的不是某个框架的用法而是我自己搭建一套Agent系统时的思考顺序、目标形态和实际踩坑过程希望能给正在做类似事情的朋友省点弯路。1. 先搞清楚一件事Agent系统和“接个大模型接口”不是一回事1.1 为什么大多数人搭出的第一个Agent只是高级聊天框最常见的“伪Agent”长这样一个写好的超长提示词一个while循环几个工具函数再加一个“继续回答”的兜底逻辑。用户丢一句话进来循环就去调模型模型说“我需要查一下”代码就去调工具拿到结果再塞回模型如此反复直到模型说“完成了”。看起来是Agent实际上这只是在模拟一个“会使用搜索功能的人”并没有真正引入任务状态、执行反馈和收敛条件。典型症状是同一个任务跑十次有三次结果完全跑偏模型在一个工具报错之后反复重试同一个动作某个子任务已经做完了模型还继续“补充发挥”整个过程没有任何环节可以让人介入。本质原因很简单——这个系统没有“任务意识”。它只有“对话意识”模型每生成一句话系统就当一次新的开始。真正意义上的Agent系统至少要回答四个问题现在这个任务处于什么阶段下一步应该由谁来执行模型还是代码执行结果是否符合预期失败之后往哪里退这四个问题一旦答不出来就不叫系统叫玩具。1.2 把Agent看成一条生产线而不是一个AI组件我更喜欢用一个传统软件工程里的类比流水线。输入是原材料用户任务输出是成品最终结果。流水线上有不同的工位有的工位是规则引擎干固定活有的工位是大模型干需要理解的活有的工位是人干最终拍板的活。工位之间靠传送带连接传送带就是任务状态和数据结构。生产线上任何工位都可能出错所以要有质检工位和废品通道。这个类比的好处是把大模型从“神坛”上拉下来了。在Agent系统里大模型只是一个能力较强的工位它不负责全流程更不负责背锅。它负责的那道工序是“理解语义、生成方案、产出结构化判断”其余部分尽量用确定性代码完成。我在实际落地时始终坚持一个原则能写代码的环节就不要用模型。模型是概率系统概率系统意味着不可控代码是确定性系统确定性系统意味着可测试。Agent系统不是越智能越好而是“该智能的地方智能该死板的地方死板”。这个原则贯穿了后面提到的全部设计。2. 方法论先自顶向下拆任务再自底向上选工具2.1 把任务分三级先决定“智能水位”搭建Agent前第一件事不是选模型而是把目标任务拆开看看这里面到底哪些环节需要“智能”哪些环节只是体力活。我习惯把任务粗略分成三个层级任务层级典型特征例子建议方案L1 固定流程输入输出明确规则可穷举从发票图片里抽金额、按模板批量生成周报框架纯代码或规则引擎不需要AgentL2 半开放任务主流程稳定但内容多变需要理解和判断合同审查、售后工单分类、简历初筛Agent 工具 规则兜底最优解L3 开放任务目标模糊路径不唯一需要大量探索“帮我想一个新品上市策略”现阶段只适合人机协同不适合全自动Agent很多项目失败的根子在于硬要把L1任务做成Agent。发票抽金额这个事规则代码跑得又快又准一个大模型调用一次要几百毫秒还可能抽错成本高还不可控。我在合同审查项目里遇到的最初版本就犯过这个错误后面会提到。反过来L3任务也不要指望全自动。目标都不明确你怎么定义“完成”没有完成定义的系统本质上就是无限循环。对这类任务我认为现阶段最务实的形态是人制定大方向Agent做信息收集和方案候选人来拍板执行。2.2 规划与执行分离大脑和手脚别混在一起方法论里最关键的一条我认为是规划Planning与执行Execution分离。这也是我从早期失败经验里换来的教训。最早我试过让模型自己决定每一步该做什么然后直接去执行工具调用。表面上看很“智能”实际运行起来问题重重模型在规划时会把精力放在“怎么组织语言”上而不是“怎么分解任务”模型在上一步结果还不完整时就急着执行下一步更致命的是一旦出问题你完全不知道是规划错了还是执行错了。后来我把系统改成两层结构。规划层由大模型负责它的唯一产出是一份结构化的任务分解描述执行层由代码负责严格按任务分解描述去调用工具、解析结果。规划层写出来的不是“回答”而是一个JSON{ task_id: contract_audit_20250117, plan: [ {step: 1, action: parse_document, params: {doc_id: doc_1024}, expect: plain_text}, {step: 2, action: extract_fields, params: {doc_text: $step1.output}, expect: structured_contract}, {step: 3, action: risk_check, params: {contract: $step2.output}, expect: risk_list} ], fallback: notify_human_review }代码拿到这份JSON后按步骤逐个执行每执行一步就把结果回填到对应的“$stepN.output”位置。如果某一步工具调用失败直接走fallback而不是让模型自己“灵机一动”换个方案。这件事带来的直接收益有三个第一每一步都能单独测试第二任务做到一半人可以清清楚楚看到当前进行到哪一步手动干预非常方便第三出问题的时候复盘极其容易——到底是模型规划错误还是某个工具返回了脏数据一眼就能定位。2.3 人机协同边界必须留给人来做的三个环节讨论Agent系统时大家总喜欢聊“人机协同”但很少说清楚哪些环节必须留给人。我的经验是有三类环节无论如何都要留一道人工复核一是高风险动作。任何会对真实世界产生不可逆影响的操作比如发送付款指令、对外发正式邮件、删除数据都不应该由Agent直接执行。合同审查项目里Agent只生成审查意见绝不自动发送“同意签署”的结论。最后一步永远是法务人员点确认。二是最终结果判定。模型给出的“完成”可以作为候选但作为最终交付物必须有人负责判定。尤其当这个结果要发给外部客户或用于审计时人工把关不仅必要而且是法律合规层面的硬要求。三是异常退路。所有Agent流程都要在开始之前就设计好“人工接管”的入口。比如任务连续失败三次、输出格式校验五次不过、或者是风险等级达到阈值系统应当自动把任务状态改成“需人工处理”把已收集到的所有上下文打包成摘要推送给人工审核队列。人机协同不是一个理念而是一套写在状态机里的条件分支。后面落地部分我会展示这些分支到底长什么样。3. 理想形态一个可控Agent系统的骨架长什么样3.1 五个核心模块意图入口、规划器、执行器、记忆、观测层我心中比较务实的Agent系统——不是那种论文里演示多聪明的Agent而是能稳定跑在生产环境里的系统——长这样模块职责实现方式意图入口接收用户任务把自然语言转成结构化任务描述大模型 固定Schema规划器把任务拆解为有序步骤定义每步的工具和产物大模型尽量只输出计划不执行执行器按计划调用工具函数、处理结果、做判定回填纯代码不允许模型直接调工具记忆模块记录任务上下文、历史决策、工具输出摘要供规划器后续参考向量库 KV缓存按任务ID隔离可观测层记录每一步的耗时、token消耗、工具调用入参出参并支持回溯结构化日志 trace_id其中最容易被人忽略的是“可观测层”。很多Agent系统跑起来之后你问它“这个任务为什么花了3分钟中间调了几次模型每次花了多少token”——答不上来。答不上来的系统是不可能被优化的。我在落地时宁可功能砍掉一点也要把可观测层做扎实因为后期调优全靠它。3.2 把状态机当骨架别让大模型自由发挥Agent任务的运行绝对不能是“模型想到哪走到哪”。我的习惯是给每个任务定义一套有限状态集合比如合同审查项目用的是pending → parsing → structuring → risk_checking → reviewed → done/failed ↘ ↘ need_more_info need_human_review任何时刻任务一定落在某个确定状态上。状态转移由代码控制大模型只是状态转移过程中负责“产出判断”的执行者。这样做的直接效果是产品经理问“现在这个任务跑到哪了”你可以用一句话回答而不是“模型正在思考”。状态机同时也天然构成了一个护栏。如果模型连续五次解析失败状态机的重试计数会触发“failed”转移操作日志里会记下“解析失败5次转人工”。这个机制防止了最常见的Agent失控形态——无意义地重试同一个坏动作。3.3 结构化输出是Agent与外部系统的通用语言大模型输出的“自然语言”是给人看的不是给系统用的。在Agent系统里模型的结果要对接工具调用、要写数据库、要触发状态转移所以必须把输出约束成机器可读的结构化数据。我在所有Agent项目里都坚持让模型输出严格Schema。哪怕是中间步骤的思考过程如果不需要被外部消费就单独用一个字段承载凡是需要被后续逻辑消费的内容全部走结构化字段。{ risk_items: [ { risk_type: payment_term_mismatch, severity: high, clause_ref: 第4.2条, quote_text: 买方应在合同签订后3日内支付全部货款, reason: 与模板第3.1条付款周期不一致, suggestion: 建议改为验收后15日内付款并保留质量异议期 } ], missing_fields: [争议解决方式], summary: 本合同主要风险集中在付款方式及争议解决条款缺失 }为了让模型稳定输出这种结构我一般采取两个措施一是把输出Schema完整写进提示词并配上两个few-shot示例二是解析阶段做严格校验JSON格式不对、字段缺失、枚举值非法直接判为解析失败触发重试。宁可让模型多生成一次也不让脏数据流到下一个环节。4. 一次真实落地合同审查Agent的从0到14.1 业务问题与约束为什么选合同审查这次落地的背景是某企业服务商内部要做一套销售合同预审工具。他们每天要处理几十份销售合同合同类型相对固定但细节千差万别——付款方式、违约责任、保密条款、争议解决每个客户谈出来的东西都不一样。传统做法是业务员提交合同法务人工逐条审一份合同平均耗时40分钟左右法务团队常年被淹没在低风险合同里。他们最初的目标其实很简单把模型用起来给法务减负。但真正梳理业务需求之后约束条件比想象的多不能漏风险。漏掉一个高风险条款比多报十个温和风险严重得多。漏报意味着法务根本没机会看。每条风险必须可追溯。模型说“这里有问题”法务必须能在原文上找到对应位置核验否则没人敢信。输入格式不统一。PDF排版五花八门有些还有扫描件和表格。输出要能归档。审查结论要进流程系统供后续审计查询。综合评估后我给出的方案是把合同审查拆成L2任务做成“Agent 工具 规则引擎”的组合体而不是单纯丢给模型“审一下”。4.2 方案设计从“调模型”到“调流程”整个流程被拆成四段第一段是文档解析。这一步我坚持不用大模型完全用解析服务处理。原因很简单解析是确定性问题规则代码做得又快又准让模型去“读PDF”既慢又贵还可能把段落顺序搞乱。解析服务的输出是带段落编号的纯文本。第二段是合同结构化。这一步才上大模型。把纯文本切成片段逐段交给模型让模型按前面说的Schema抽取合同关键信息签约主体、标的、金额、付款节点、交付时间、违约条款、争议解决等。这一步是Agent系统里规划器与执行器配合的典型场景——规划器把“审一份合同”拆成了“抽字段”“查条款”“判风险”三个子任务执行器按顺序流转。第三段是风险初筛。这里用了一个混合策略规则引擎先跑一遍把能确定性判断的问题全部捞出来比如“金额大小写不一致”“合同日期早于签订日期”“结算方式为外币但没有税率条款”模型再做语义层面的识别比如“付款周期描述和公司模板不一致”“违约责任仅约束单方”。规则引擎的结果直接可信模型的结果必须附带原文引用。第四段是报告生成。所有结果汇总后执行器生成一份结构化审查报告附上每个风险点的引用文本和修改建议。最后推送给法务人工确认。4.3 工具链搭建解析、检索、规则引擎这套Agent系统的工具层实际由三个工具组成。文档解析工具封装了PDF和Word两类文件解析能力输出统一为带段落序号的文本块。这里踩过几个坑比如扫描版PDF必须走OCR、表格会被拆成碎片所以我额外做了一个表格还原逻辑如果某一段文本解析出来全是竖排的零散数字就先尝试按表格结构重组重组失败才退回模型。条款库检索引擎负责给模型提供“参照系”。我们把公司过去三年法务给出的修改意见整理成条款级别的风险库每条记录包含“风险条款原文”“风险类型”“修改建议”“引用法条”。检索时用向量相似度召回Top 5相关条款塞进模型上下文。这一步本质上是给模型喂参考资料让它的判断有依据而不是凭空发挥。规则引擎用来做所有确定性检查和一致性校验。我把规则写成一个一个可配置的检查项每个检查项是一个函数契约很清晰输入结构化合同字段输出风险项列表。规则引擎的检查结果直接进入最终报告不经过模型改写确保确定性输出不被模型“润色”掉。三个工具都包了一层标准化的函数调用接口执行器通过统一接口去调用它们入参出参都记录日志。4.4 提示词与输出约束让模型按Schema说话提示词设计这块我花的时间最多。第一版我写了一个大而全的提示词要求模型一次审完整份合同结果输出质量起伏很大——短合同还行长合同经常漏条款。后来改成“先拆后审”以后提示词也跟着变成“小步走”每一段只负责任务里的一个环节。以“合同结构化”这一步为例我的提示词结构大致是这样的你是合同审查流程中的结构化抽取模块。你的任务是从给定的合同文本片段中抽取合同关键信息。要求只抽取文本中真实存在的内容不得补充或推测。金额统一转换为数字币种保留原字段。日期统一转换为YYYY-MM-DD格式。输出必须是一个合法JSON对象字段严格遵循如下Schema不得增删字段。如果片段中不包含某字段信息置为null不要编造。Schema{contract_party_a: string, contract_party_b: string, total_amount: number|null, currency: string|null, sign_date: YYYY-MM-DD|null, effective_date: YYYY-MM-DD|null, delivery_terms: string|null, payment_terms: array|null, arbitration_clause: string|null}配合温度参数调到0.1左右并给一个参考示例。实测下来字段抽取的格式合规率能到95%以上。剩下的格式错误靠解析重试机制兜住不直接进入下游。我建议所有做Agent的人都在提示词里强调“只抽取原文真实存在的内容”。模型太容易顺着你的Schema“补全”信息了你让它输出total_amount它看见一篇文章里有个价格数字就塞进去但这个价格可能根本不是合同总额。这是幻觉的根源之一不是模型瞎编而是它太想“完成任务”了。4.5 评估体系没跑过50份历史合同别谈上线Agent系统上线前评估是绕不开的生死关。我的做法是从已审结的历史合同里抽了50份作为评测集请两位业务人员对每份合同标出了“正确的高风险点清单”和“字段抽取参考答案”然后系统逐个跑算三个核心指标。指标定义我们的要求字段抽取准确率抽取字段与人工标注完全一致的比例不低于90%高风险点召回率系统识别出的高风险点占人工标注高风险点的比例不低于95%漏一个都算事故平均每份合同耗时从上传到报告生成的时间不超过2分钟评测跑完之后问题立刻暴露50份里有6份高风险点召回率不达标追查发现主要原因是长合同的“违约责任”条款在第30页以后而分块策略要求模型只审“与付款相关的片段”导致责任条款被漏掉。修复方案是调整切分策略一次解析全额文本定位“违约责任”段落并作为独立分块单独送检。改完之后召回率提升到96%。这一步给项目管理带来的最大价值是我们可以拍着胸脯说“这个Agent能上线”而不是“我觉得效果还行”。没有评测体系的Agent项目改起来就像在黑屋子里调琴——调了这根弦不知道另一根是不是也跑了。5. 落地踩过的坑比想象中多但大部分可绕开5.1 长合同token爆炸整个解析流程反复超时第一版系统最离谱的问题是用户丢进来一份40页的合同我们把全文塞进模型上下文要求产出完整审查报告。理论上可行实际跑起来——单次调用token上限直接打穿报错、重试、再报错一份合同能折腾一刻钟。后来痛定思痛改成合同分块 子任务聚合的模式。先按章节把合同切成若干块每块各自做结构化抽取抽取结果汇总后再进入风险审查环节。这样单次调用的token消耗从几万降到了几千速度明显提升成本也降了一个量级。分块带来一个副作用跨章节的语义被切断了。比如付款条款在第10页违约条款在第28页模型可能看不出这两处表述互相矛盾。解决方案是在聚合阶段加一个“交叉检查”子任务把各块抽出的关键字段汇总后再让模型专门检查字段之间的一致性。这一步不能省。5.2 幻觉的可怕之处它“看起来很专业”合同审查Agent运行到第三周我们遇到一个让人后背发凉的Case模型识别出一个“合同金额与附件报价单不一致”的高风险点引用文本看起来非常通顺但法务人员去原文定位时根本找不到这句话。查日志发现模型在输出风险项的“quote_text”字段时自己组合了一段“看起来像原文”的文本。这就是系统性幻觉而且比“瞎编一个答案”更危险因为它出现在一个以严谨为核心的业务场景里。我给的修复方案是双保险。第一层提示词里强约束风险项的引用文本必须是原文中连续出现的原文片段禁止拼接和改写。第二层程序校验执行器在收到模型输出后做一个“引用文本是否存在于原文”的检索校验如果引用文本在原文里找不到整条风险项标记为“引用异常”退回模型重新生成。两步做完引用伪造的情况彻底杜绝。这件事给我的教训是不要相信模型的自述。模型说“我引用了原文”你必须在程序层面把它输出的引用和你手里的原文做比对验证。Agent系统的每一步可信都是靠校验桩撑起来的不是靠模型的自律。5.3 规划器死循环一次失败重试把成本放大十倍系统上线前压测时发现一个恐怖场景某次文档解析工具临时故障返回了一个5xx错误结果规划器检测到“步骤失败”之后不是按既定方案走fallback而是“灵机一动”重新规划了一套方案——换个参数重新调用同一个解析工具然后又失败了又生成了一个新计划又调用……整个过程在30秒内连续调用了十几次模型接口花费的token比正常任务还高。这个坑让我彻底确认了一件事高级智能不能滥用。最终修法很朴素但非常有效在规划器外部包了一个“步数上限”和一个“单步重试次数”。任何任务最多执行20步任何工具调用最多重试2次超过就走人工队列。上限不是拍脑袋定的而是从评测集50份成功任务的步数分布里取的P95值。既然Agent系统的行为终归要收敛那就直接用硬编码把这个收敛条件写死。5.4 可观测性日志不是为Debug设计的是为排查线上问题设计的早期版本的日志只记录模型调用的响应时间遇到问题排查非常费劲。真正的问题往往藏在细节里某个工具返回了空数组、某个字段值超出预期范围、某一步的token消耗突然暴涨。这些信息在普通日志里根本找不到。后来我把可观测性升级了一版。每个任务有一个全局trace_id从入口请求到每一次工具调用、每一次模型API调用全部打上这个trace_id模型调用的入参出参都做摘要记录出参记录完整的JSON返回工具调用记录“耗时”“入参摘要”“出参摘要”“错误信息”。这样排查线上问题时的路径就很清晰先按trace_id拉出全链路日志然后定位到具体某一步直接看入参出参。有一次用户反馈某份合同审查结果“缺了争议解决条款的判断”就是靠这套日志链路定位到的模型确实抽出了“争议解决约定为仲裁”但下游为规避规则引擎把“仲裁”误判为风险项将整段内容丢弃。如果没有trace日志这种问题靠肉眼翻聊天记录根本找不到。6. 真要搭Agent系统的话我给你这三条建议6.1 从“最小可行Agent”开始别一上来做完整平台我见过太多团队一开始就想着搭一个“Agent平台”内置十几个工具、可视化编排、多模型切换、用户权限系统。结果搞了三个月还没跑通过一个真实业务。我的建议恰恰相反先选一个边界清晰、价值明显的业务场景用最小的闭环把“模型工具状态机人工复核”跑通哪怕流程很简陋也要先有端到端的体验。有了这个基础再去抽象平台能力。平台是做出来的不是设计出来的。6.2 流程是一等公民模型只是其中一个节点Agent系统里真正值钱的设计是对业务流程的理解和编排而不是“用哪个大模型”。模型会换、会更强、成本会更低但业务流程的拆解和状态机的设计是稳定资产。在合同审查这个项目里最核心的资产是“哪些环节必须由人确认”“风险引用如何校验”“分块策略怎么切”——这些和大模型本身没有直接关系。6.3 能和规则引擎共存就别互相替代千万不要因为上了Agent就把原有规则引擎全部推倒重来。规则引擎在确定性检查上永远优于大模型它快、稳、可解释。Agent的正确角色是补规则引擎的缺口——处理那些规则穷举不了的长尾语义场景。我们当时保留了所有历史规则新模型只做增量判断两套结果合并输出。经验法则是凡是能用50行代码解决的问题就不要写进提示词里让模型猜。Agent系统的搭建本质上是在“智能”和“可控”之间找平衡。从方法论到理想形态再到真实落地这一路走过来我的体感是真正决定系统上限的不是模型有多聪明而是你把业务流程拆得多清楚、把状态机设计得多严谨、把校验防线铺得多密。希望这篇分享能帮到正在搭Agent的你。