AI Agent开发实战：从架构选型到工具调用优化的工程化指南

1. 从一条标题说起AI创业者正在做的Agent到底是什么第一次看到“AI Frontier This AI entrepreneur is developing agent”这个标题时我脑子里冒出来的第一个念头是又是一个做Agent的。但紧接着第二个念头是——2024年到2025年这段时间Agent这个词被用得太泛了泛到几乎任何一个带工具调用的LLM应用都敢叫自己Agent。所以真正值得聊的不是“有人在做Agent”这件事本身而是一个AI创业者选择做Agent时他到底在解决什么问题、踩过哪些坑、技术选型上做了哪些取舍。这篇内容我想从一个一线开发者的视角把“开发一个Agent”这件事从头到尾拆开讲一遍。不是那种“Agent LLM Memory Tools Planning”的教科书式定义而是真刀真枪做项目时会遇到的那些具体问题为什么你的Agent跑着跑着就死循环了、为什么加了记忆反而更笨了、为什么评测集跑分很高但用户一用就崩、为什么工具调用的成功率卡在70%上不去。如果你正在做Agent相关的项目或者准备入局Agent开发又或者你是个产品经理想知道Agent到底能落地到什么程度这篇内容应该能给你一些直接能用的东西。我会尽量把每个技术决策背后的“为什么”讲清楚因为Agent这个领域抄代码容易理解为什么这么写难。而恰恰是那些“为什么”决定了你的Agent是能上线还是只能demo。先给个结论性的判断当前阶段做Agent工程复杂度远大于模型能力本身。很多人以为Agent做不好是因为模型不够聪明实际上我见过的失败案例里八成以上是工程问题——状态管理混乱、工具描述写得稀烂、错误处理缺失、上下文窗口管理失控。模型能力是天花板但工程能力决定了你能不能摸到那个天花板。2. Agent开发的核心架构选型为什么大多数方案都绕不开这几个模块2.1 Agent的本质是一个带状态的循环决策系统把Agent拆到最底层它就是一个循环观察当前状态 → 决定下一步动作 → 执行动作 → 更新状态 → 再观察。这个循环听起来简单但每一个环节都有大量的工程细节。我见过很多初学者写的Agent本质上就是一个while循环里套一个LLM调用然后把工具结果拼回prompt里。这种写法跑简单任务没问题一旦任务步骤超过5步基本必崩。原因很简单没有显式的状态管理。LLM的上下文窗口是有限的当你的对话历史加上工具返回结果超过窗口限制时你要么截断丢失关键信息要么压缩引入信息损失要么就等着报错。所以一个能用的Agent架构至少需要这几个模块状态存储层不只是对话历史还包括任务进度、中间结果、已尝试过的方案。我通常会用结构化的方式存而不是一股脑塞进messages数组。规划模块决定下一步做什么。可以是ReAct式的边想边做也可以是先规划再执行。两种方式各有适用场景。工具执行层负责实际调用外部工具包括参数校验、超时处理、重试逻辑、结果格式化。记忆模块短期记忆当前任务上下文和长期记忆跨会话的知识积累要分开设计。评测与监控没有评测的Agent就是盲盒你永远不知道它为什么成功或失败。2.2 ReAct vs Plan-and-Execute选错了会很难受这是Agent架构选型里第一个大分叉。ReActReasoning Acting的思路是让模型每一步都先思考再行动适合步骤不确定、需要根据中间结果动态调整的任务。Plan-and-Execute是先让模型生成完整计划再逐步执行适合步骤相对固定、可以提前规划的任务。我的经验是任务步骤少于10步且路径不确定的用ReAct步骤多但流程相对固定的用Plan-and-Execute。但实际项目中纯用某一种往往都不够我一般会做一个混合方案——先让模型生成一个粗粒度的计划然后每个计划步骤内部用ReAct的方式执行。这样既有全局的方向感又有局部的灵活性。这里有个坑要提醒ReAct模式下模型很容易陷入“思考-行动-思考-行动”的循环出不来。我遇到过最夸张的一次Agent在“搜索资料”和“整理资料”之间来回跳了17次。解决办法是在prompt里加一个步骤计数器超过阈值就强制进入总结阶段。这个阈值我一般设15-20步具体看任务复杂度。2.3 工具设计Agent能力的天花板由工具决定很多人把精力全花在prompt调优上却忽略了工具设计才是Agent能力的真正瓶颈。一个设计糟糕的工具模型再聪明也用不好。工具设计的核心原则就一条让模型一眼就知道什么时候该用这个工具、怎么用、会得到什么。具体来说工具名称要语义明确search_web比tool_1好一万倍参数描述要写清楚格式和约束比如date: 格式必须是YYYY-MM-DD返回值要结构化不要返回一大坨自然语言让模型自己解析错误信息要有指导性告诉模型“参数错了应该传什么”而不是“Error 400”我实测下来光是优化工具描述这一项就能把工具调用的成功率从60%多提升到90%以上。这个投入产出比远比换模型高。3. 记忆系统Agent从“金鱼脑”变成“有经验”的关键3.1 短期记忆与长期记忆要分开设计短期记忆就是当前任务的上下文这个相对简单主要问题是窗口管理。长期记忆就复杂了它要解决的是“Agent如何从过去的交互中学习”。我见过最常见的错误做法是把所有历史对话都塞进向量数据库然后每次检索top-k。这种做法的问题在于检索出来的记忆往往是碎片化的、缺乏上下文的模型拿到这些碎片反而会被误导。更靠谱的做法是分层记忆记忆类型存储内容检索方式更新时机工作记忆当前任务状态、中间结果直接注入prompt每步更新情景记忆完成的任务摘要、成功/失败经验语义检索时间衰减任务结束时语义记忆领域知识、用户偏好向量检索定期整理情景记忆我一般会存成结构化的“任务卡片”任务描述、执行步骤、最终结果、成功与否、关键教训。这样检索出来的是完整的经验而不是碎片。3.2 记忆检索的时机比检索算法更重要很多人花大量时间调embedding模型和检索算法但忽略了什么时候该检索记忆这个更根本的问题。我的做法是不是每一步都检索记忆而是在这几个时机检索——任务开始时找类似任务的经验、遇到错误时找类似错误的处理方式、需要做关键决策时找相关领域知识。这样既减少了检索开销又避免了无关记忆干扰模型判断。还有一个细节检索到的记忆要带上时间戳和置信度。模型需要知道这条记忆是三天前的还是三个月前的是成功经验还是失败教训。这些元信息对模型的决策质量影响很大。3.3 记忆的遗忘机制不遗忘比遗忘更可怕这是我在实际项目里踩过的最大的坑之一。早期版本我们没有做记忆淘汰结果跑了两个月后Agent的行为变得越来越奇怪——它会引用一些过时的、甚至矛盾的信息来做决策。后来我们加了遗忘机制低频访问的记忆逐渐降低权重超过一定时间的低权重记忆直接归档。同时当新记忆和旧记忆冲突时保留新的但标记冲突让模型知道这里有过变化。这个机制加进去之后Agent的决策一致性明显提升。所以如果你在做长期运行的Agent记忆淘汰机制不是可选项是必选项。4. 工具调用与执行从70%到95%成功率的实战优化4.1 工具调用的失败模式分析我把工具调用的失败原因归为四类每一类的解决思路完全不同参数格式错误占比约40%模型传的参数格式不对比如该传JSON传了字符串该传数字传了文字。解决办法是在工具描述里给明确的格式示例同时在执行层做参数校验和自动修正。工具选择错误占比约25%模型选错了工具或者该用工具的时候没用。这通常是工具描述不够清晰导致的。执行超时或异常占比约20%外部API挂了、网络超时、返回了预期外的格式。这需要执行层有完善的重试和降级逻辑。结果解析错误占比约15%工具返回了结果但模型理解错了。这通常是返回值格式不够结构化导致的。针对这四类问题我的优化策略是参数校验前置、工具描述细化、执行层加retry、返回值强制结构化。这四招下去工具调用成功率基本能稳定在95%以上。4.2 参数校验与自动修正的实操方案参数校验我一般用Pydantic做定义好每个工具的参数schema模型传过来的参数先过一遍校验。校验失败的不是直接报错而是把错误信息返回给模型让它重新生成。这个“校验-反馈-重试”的循环一般设2-3次超过就放弃并记录日志。自动修正这块我写了一些常见的修正规则比如日期格式统一转成ISO格式、字符串数字自动转数字、缺失的可选参数填默认值。这些规则看起来不起眼但能省掉大量无谓的重试。from pydantic import BaseModel, validator from datetime import datetime class SearchParams(BaseModel): query: str date_from: str None max_results: int 10 validator(date_from) def parse_date(cls, v): if v is None: return v # 尝试多种日期格式 for fmt in [%Y-%m-%d, %Y/%m/%d, %m-%d-%Y]: try: return datetime.strptime(v, fmt).strftime(%Y-%m-%d) except ValueError: continue raise ValueError(f无法解析日期格式: {v}) validator(max_results) def cap_results(cls, v): return min(max(v, 1), 50)这段代码看着简单但它把参数错误率降低了至少一半。核心思路是能自动修的就别让模型重试能容错的就别报错。4.3 工具执行的超时、重试与降级外部工具调用一定要设超时这个不用多说。但重试策略有讲究不是所有错误都值得重试。网络超时、限流这类临时性错误可以重试参数错误、权限错误这类确定性错误重试也没用。我的重试策略是临时性错误重试2次间隔用指数退避1秒、2秒确定性错误直接返回错误信息给模型让它决定下一步。同时每个工具都要有降级方案——比如搜索工具挂了能不能用缓存结果或者换一个搜索源。还有一个容易被忽略的点工具执行要有幂等性保证。有些工具比如发邮件、下单重复执行会有副作用这类工具必须加幂等键防止重试导致重复操作。5. Agent评测没有评测就没有迭代方向5.1 评测集的设计比评测本身更重要Agent评测和传统LLM评测最大的区别是Agent的输出是一个过程不是一个结果。所以评测不能只看最终答案对不对还要看过程合不合理。我一般会从四个维度评测任务完成度最终目标达成了吗步骤效率用了多少步有没有绕弯路工具使用正确性该用的工具用了吗参数传对了吗鲁棒性遇到错误能恢复吗能处理边界情况吗评测集的设计要覆盖这三类任务简单任务3步以内、中等任务3-10步、复杂任务10步以上。每类任务至少20个case而且要包含一定比例的“陷阱case”——比如工具会返回错误、信息不完整、有干扰项等。5.2 自动化评测与人工评测的结合纯自动化评测的问题是很多Agent的行为质量很难用规则判断。比如“Agent的思考过程是否合理”这种规则根本没法写。纯人工评测的问题是太贵、太慢、不可复现。我的做法是自动化评测做初筛人工评测做精评。自动化评测用规则LLM-as-judge的方式把明显失败的case筛出来。然后人工重点看那些自动化评测通过但实际体验不好的case这些case往往暴露了评测集的盲区。LLM-as-judge这块要注意judge模型的选择很关键我一般用比被测模型更强的模型来做judge同时judge的prompt要写得非常具体明确评分标准和扣分项。实测下来judge和人工评分的一致性能到80%左右作为初筛足够了。5.3 线上监控与bad case回流评测集是静态的但用户的实际使用是动态的。所以线上监控和bad case回流机制必不可少。我一般会监控这几个指标任务完成率、平均步数、工具调用失败率、用户中断率、用户重试率。其中用户中断率和用户重试率是最灵敏的指标——用户中断说明Agent卡住了或者跑偏了用户重试说明结果不满意。bad case回流就是把这些异常case自动收集起来定期整理进评测集。这样评测集会随着产品迭代不断进化覆盖越来越多的真实场景。6. 常见问题与排查技巧实录6.1 Agent陷入死循环怎么办这是最高频的问题。表现是Agent在几个步骤之间反复横跳永远不结束。排查思路先看是不是工具返回了空结果或错误结果导致模型一直在重试再看是不是prompt里缺少终止条件模型不知道什么时候该停最后看是不是任务本身无解模型在硬撑解决办法加步骤计数器强制终止、在prompt里明确终止条件、给模型一个“放弃”的选项。我一般会在system prompt里写“如果连续3次尝试都失败或者任务明显无法完成请直接说明原因并结束不要继续尝试。”6.2 工具调用成功率突然下降如果之前好好的突然成功率掉了大概率是这几个原因外部API变了返回格式变了、接口地址变了、认证方式变了模型版本更新了行为变了工具描述被改了引入了歧义上下文变长了模型注意力被分散了排查顺序先看API日志再看模型版本再看最近的代码变更最后看上下文长度。我遇到过最隐蔽的一次是上下文里混入了一个特殊字符导致模型解析工具描述时出错。这种问题只能靠日志和对比实验来定位。6.3 记忆检索出来的内容不相关这个问题通常是这几个原因embedding模型不适合当前领域、检索的query写得不好、记忆存储时没有做清洗。我的优化顺序是先优化记忆存储的结构化程度存的时候就把关键信息提取出来再优化检索query的生成方式用LLM来生成检索query而不是直接用用户输入最后才考虑换embedding模型。因为前两步的投入产出比远高于换模型。6.4 常见问题速查表问题现象可能原因排查方向解决手段死循环缺终止条件/工具返回异常看步骤日志加计数器明确终止条件工具调用失败率高参数格式/描述不清看失败日志分类参数校验描述优化记忆不相关存储结构/检索query看检索结果结构化存储LLM生成query响应变慢上下文过长/工具超时看耗时分布上下文压缩超时设置行为不一致记忆冲突/温度过高看历史记忆记忆淘汰降低温度7. 一些关于Agent开发的个人体会做Agent这一年多最大的感受是这个领域没有银弹只有一堆trade-off。模型能力强了工程可以简单点但成本和延迟上去了工程做得重了稳定性好了但迭代速度慢了。每个项目都要根据自己的场景找平衡点。另一个体会是Agent的能力上限由模型决定但能力下限由工程决定。我见过太多demo很惊艳但一上线就崩的Agent问题几乎都出在工程上。所以如果你刚开始做Agent我建议先把工程框架搭扎实再考虑怎么把模型能力榨干。最后一个建议不要追求一步到位要追求快速迭代。Agent的行为太复杂了你不可能在写代码之前就想清楚所有情况。最好的方式是先做一个能跑的最小版本然后通过评测和线上反馈不断迭代。我现在的项目基本保持每周一次小迭代、每月一次大迭代的节奏每次迭代都有明确的优化目标。这个方向后续还可以往多Agent协作、Agent自我进化这些方向扩展但那是另一个话题了。先把单Agent做扎实比什么都重要。