从Demo到生产：AI Agent开发路线、框架选型与安全排查实战

2026年9月28号这天Agent和LLM的讨论热度明显比上周更高。早上刷开技术社区AgentPoison的论文解析挂在热榜下午又有好几个群里在问ADK和Spring AI Agent怎么选晚上还有人在调Codex的沙盒更新问题——整个生态给人一种感觉Agent终于从炫技Demo走向了生产环境随之而来的是框架、记忆、并发、安全这些“地基问题”被翻到台面上。这期日报就是围绕这些真实问题整理的我自己是搞Agent落地和LLM应用开发的文章里会把我认可的方案、踩过的坑和排查思路一起写出来希望能给正在搭Agent的朋友提供一点参考。1. 今日架构热点Agent 从“Demo”走向“生产”1.1 别再把 Harness 当 Agent两者差在哪很多人把Harness和Agent混着用其实它们是两层东西。Agent是那个负责“想”和“决定”的主体它拿到任务、拆解计划、调用工具、汇总结果Harness则是承载Agent运行的外部骨架包括工具注册表、上下文窗口管理、沙盒环境、事件循环、与模型API交互的运行时。你可以把Agent理解成司机Harness理解成车辆框架——司机决定怎么走车辆提供方向盘、刹车和执行机构。判断一个开源项目是Harness还是Agent就看它是否自带决策循环。如果它只是把工具挂在一棵树上等模型来调用那是Harness如果它有规划器、反思器、多轮校验那才是Agent。今天热词里反复出现“harness和agent区别”说明很多人正在从“会调API”过渡到“会搭Agent”。这个区分非常重要因为选型时如果只盯着Agent的名头却不知道底层Harness的能力边界很容易把框架的天花板当成Agent的天花板。1.2 记忆是 Agent 的“缓存”但别倒进内存就完事记忆设计直接影响Agent的可用性。简单的聊天式Agent不需要长期记忆但一旦涉及“昨天你让我监控那个服务的告警”没有记忆就只能靠用户在提示词里粘贴历史。当前比较靠谱的做法是把记忆外部化——不在模型上下文里堆无用信息而是存到向量库、KV数据库、甚至本地Markdown文件里。今天热词里出现“Hermes Agent”和“Obsidian”就是把Obsidian当外部记忆库Agent检索时先走文件索引把相关内容拉进上下文再让模型回答。这个做法的好处是记忆可见、可编辑、可审计。我实际使用时发现最容易出问题的不是存不进去而是检索召回太杂。解决办法是给每篇笔记加front matter标签检索时用元数据过滤召回精度明显提升。另一个经验是记忆写入要比读取更克制。不是每轮对话都值得永久保存我一般设定两条规则只有包含用户明确偏好、项目决策、任务结果的内容才写入长期记忆临时状态放进短期缓存隔天自动过期。否则记忆库很快就会变成一锅粥Agent反而被自己的“过去”带偏。1.3 并发才是分水岭AI Agent 怎么扛住几十路请求AI Agent要扛并发跟普通API加个缓存不一样。每个Agent会话有独立状态但模型调用入口和工具执行共用有限的资源。生产环境至少要解决三件事请求排队、速率限制、状态隔离。请求排队是把所有Agent任务丢进任务队列用固定worker数消费避免瞬时打爆模型配额速率限制要按token和分钟两个维度做因为有些供应商同时限制了请求数和tokens/min状态隔离要求每个会话的上下文、会话快照、工具调用记录分开存不能像单机脚本那样用全局变量。我之前帮一个团队排查过Agent偶发串话最后发现就是会话状态存在本地静态Map里并发一上来就互相覆盖改成Redis存session之后才算彻底解决。还有一次是工具调用超时设置得太激进35秒超时对一个外部API来说根本不够导致Agent频繁中断。后来把超时拆成“连接超时”和“读取超时”两段配合指数退避重试成功率才上来。并发场景下日志里一定要带request_id和session_id不然出问题根本没法追踪到是哪个会话在调用哪个工具。1.4 Agent 架构怎么画一张图想清楚今天好几个讨论串都在问Agent架构我给一个自己常用的分层图画法不用工具纯文字描述。最下面是模型层包括LLM、Embedding、以及评测或重排模型往上是记忆层分短期上下文、工作记忆、长期知识库再往上是工具层数据库、搜索、浏览器、业务API、第三方服务都放这里最上面是编排层负责规划、反思、任务分解、并管理多Agent协作。每层之间只暴露接口不跨层调用。比如记忆层不直接知道工具层怎么实现工具层也不关心编排层用什么策略。这个架构的最大优势是每一层都能独立测试和替换模型层换了工具层不用动记忆存储从向量库换成Postgres编排层也无感。很多框架之所以越改越乱就是因为层与层之间互相渗透最后一个小改动都要动全身。2. Agent 开发学习路线与框架选型四条路怎么选2.1 从零到一Agent 开发到底要学什么Agent开发的学习路线我把它分成四段。第一段是把LLM API用熟搞清楚system prompt、function calling、temperature这类参数对输出的影响。第二段是学会写工具一个Agent本质上就是把业务系统里的操作封装成模型可调用的函数所以JSON Schema、参数校验、错误返回格式是基本功。第三段是编排包括ReAct循环、plan-and-execute、多Agent协作这里要理解为什么需要循环执行、什么时候必须停下来问用户。第四段是生产化涉及重试、超时、可观测性、权限控制。如果你按这个顺序学大概六到八周能在实际项目里跑通一个中等复杂度的Agent。很多新人一上来就啃LangGraph或AutoGen源码反而把自己劝退了。我的建议是先手写一个二十行的while循环把“模型返回→解析工具调用→执行工具→结果回填”跑通再去用框架你会突然发现框架只是帮你封装了这些循环而已。今天热搜词里“agent开发学习路线”“agent学习路线”“ai agent搭建”扎堆出现说明这个领域已经过了靠概念唬人的阶段大家开始认真搞技能栈了。2.2 框架选型Spring AI Agent、ADK、Rust 与自研框架选型没有银弹。今天热搜里的Spring AI Agent适合Java技术栈且已经使用Spring Boot的团队因为它把模型客户端、工具调用、对话记忆都整合进了Spring生态写起来像写Service一样自然。ADK则是另一个方向它更强调跨模型、可控性和内置的并发原语用Kotlin在JVM上写Agent很顺畅Google的SDK迭代也快。Rust写AI Agent的更多是为了极致性能和低资源占用适合边缘设备或对延迟敏感的场景但开发效率天然低一些。还有一个不该被忽略的方案是自研编排如果你的需求就是“根据规则调两三个固定API”完全不需要引入重型框架自己写一个几十行的while循环加工具映射就够反而省心。框架的作用是帮你处理通用复杂问题而不是给你增加一份框架学习成本。我今天给团队选型的判断标准就三条第一团队主力语言是什么第二Agent的复杂度是否值得上框架第三框架的抽象是否符合业务直觉。符合就上不符合就自研不要因为社区热就盲目引进。2.3 实操在 JVM 上用 ADK 五分钟跑通一个 Agent以ADK为例在JVM上跑通一个最小Agent步骤很清晰。第一步建一个Gradle工程引入ADK依赖第二步定义一个工具函数比如查询本地数据库第三步用AgentBuilder绑定模型和工具设置系统提示词第四步启动一个Session执行任务。以下是我整理过的示意代码API签名以你实际的SDK版本为准。import com.google.agentsdk.Agent import com.google.agentsdk.Session import com.google.agentsdk.Tool fun searchOrder(orderId: String): String { // 这里连接数据库并返回订单状态 return 订单$orderId 已发货 } fun main() { val agent Agent.builder() .name(orderAgent) .model(gemini-2.5-flash) .systemPrompt(你是订单查询助手只能查询订单状态。) .addTool(Tool.fromFunction(searchOrder, ::searchOrder)) .build() Session.start(agent) { ctx - val reply ctx.run(订单A10086现在到哪了) println(reply.text) } }这段示例跑起来后你会发现模型其实不会直接执行函数而是先返回一个tool_call由ADK的harness去调度你的函数再把结果回填给模型。理解这个循环后再看网上各种Agent框架源码都会轻松很多。第一次跑通的时候我建议把日志级别调到DEBUG亲眼看一遍tool_call和tool_result的流转比看十篇教程都有用。2.4 用聊天记录精调 LLM数据清洗比模型选型更重要今天热词里还有“使用聊天记录模型精调llm”和“基于llm的单元测试”这两件事我放在一起说。用真实聊天记录微调模型最大的坑不是模型选型而是数据清洗。很多团队直接把日志导出来喂给模型结果模型学到一堆重复回答、半截话、甚至客服发脾气的内容。我建议微调数据至少要过五道关去掉身份信息、去掉超长上下文、统一系统提示词格式、修正错误答案、抽样人工复核。至于“基于LLM的单元测试”现在越来越多团队用LLM生成测试用例甚至测试断言。这个方向有潜力但别指望它能完全替代人工测试。我的做法是让LLM生成边界值用例但断言逻辑还是由人来写因为模型生成的断言经常带上“参考答案”的偏见反而测不出回归。3. 大模型层的几个关键细节Token、评测与本地部署3.1 Token 三角Key 认身份Query 找目标Value 供内容热词里那句“Key 我是谁、Query 我在找什么、Value 我能提供什么”本质是Transformer注意力机制的三个向量。你可以把一次注意力计算当成一场会议室讨论Key是座位上每个人的名牌Query是你想找某个话题时提出的问题Value是每个人针对这个问题实际说出的内容。模型先把你的Query和所有人的Key做相似度打分再用分数加权求和Value从而把注意力集中在相关词上。这个理解对Agent开发特别有用因为设计外部记忆检索时你本质上是把用户问题转成Query把知识条目当成Key和Value检索效果好不好取决于你怎么构造这段“名牌”。比如在知识库文档的标题里写清“适用于什么场景”就等于给Key加了一枚好名牌检索命中率会大幅提升。反之如果文档标题全是泛泛的“笔记1”再好的向量模型也救不回来。3.2 LLM as Judge让模型当裁判怎么防止“黑哨”LLM as Judge已经是评测Agent输出质量的主流方式但直接用会翻车。我自己踩过的坑包括位置偏差——裁判模型倾向于给前后位置的答案更高分自优先——大模型偏爱自家的输出以及长度偏好——回答越长分越高。要缓解至少做三件事使用盲评格式随机交换两个答案的位置再取平均给裁判提供明确的评分Rubric而不是让它自由打分每隔几条用一份人工标注的黄金集做校准计算裁判判断与人工判断的一致性。如果一致性掉到0.7以下评测结果基本只能当参考。我最近在跑一个Agent工具的评测集第一次一致性只有0.52后来把评分标准从“5分制”改成“四维评分正确性、完整性、可操作性、格式合规”再把裁判的temperature调到0一致性才升到0.81。所以“LLM as Judge”不是拿来就能用的它本身也需要被调教。3.3 把 GGUF 塞进安卓本地模型部署的取舍在安卓上本地跑GGUF格式的LLM这两天讨论也不少尤其是有人问有没有支持安卓8的软件。模型格式上GGUF就是最适合CPU推理的量化格式之一配合llama.cpp系的推理后端可以在手机上跑1B到7B的小模型。关键点是选对量化等级安卓8设备内存普遍不大建议优先用Q4_K_M或Q5_K_M的量化效果和体积比较均衡还要关闭系统动画省电、加一个散热背夹防止温度墙导致降频。实际跑起来的体验是3B模型打字速度勉强可看7B模型单轮回复可能要十几秒适合离线演示和隐私敏感场景。另外注意现在不少安卓软件只支持8.0以上API标题说支持安卓8是加分项。如果你需要的是细分领域的知识本地base模型加上小尺寸的LoRA微调比直接拉一个超大模型更现实。3.4 Spatial LLM 和榜单读法别被热门名词带节奏今天还有“spatial llm”这个词上了热搜空间大模型开始往机器人导航、室内设计这类场景渗透。如果你做的是物理世界相关Agent这类模型值得关注但也别把空间理解能力当成通用能力。目前多数Spatial LLM在复杂空间推理上仍然不稳定我在测试它做室内路线规划的时候单看文字描述好像没问题一旦结合具体坐标和障碍物就经常出现自相矛盾。所以这类模型更适合当“顾问”而不是“决策者”。说到模型选择Open LLM Leaderboard这类公开榜单当然值得看但要会读。榜单分数只反映它在固定评测集上的表现不能覆盖真实业务中的指令遵循、长上下文、工具调用能力。挑模型时把榜单当初筛条件再用你业务里最典型的20条Prompt做一次盲测对比输出质量和成本。今天还有个“LLM Studio”的词也进了热搜这类工具适合快速对比模型输出但别长期依赖它做自动化评测因为它的可控性远远不够。4. Agent 安全与故障排查今天最值得抄作业的两个问题4.1 AgentPoison投毒记忆库比提示注入更隐蔽安全这块今天最关键的词是AgentPoison。它来自一项针对LLM Agent红队测试的研究思路是往Agent的外部记忆或知识库里投毒而不是直接注入提示词。我们习惯防的是“用户把prompt注入到工具参数里”但AgentPoison说明一个更隐蔽的风险当Agent检索外部知识时攻击者可以把一小段恶意文本伪装成常见信息混进知识源一旦被召回模型就可能被带偏进而执行错误操作。应对方法首先是不信任所有外部知识——凡是来自知识库/记忆的内容在送进模型前先做一遍隔离渲染把指令类内容剥离同时给知识片段加来源水印在Agent决策链路上记录“本步使用了哪些外部片段”方便事后审计。我建议所有接入了RAG记忆的Agent在生产前一定要跑一遍投毒对抗测试不要等到上线后才看日志。对抗测试可以模拟三种攻击在知识库插入恶意指令、修改已有条目的关键词、在文档标题里藏诱导文本。跑完你基本就能知道自己的检索链路到底有多“好骗”。4.2 当日错误实录tool payload 被拒、sandbox 更新失败今天两个报错在群里出现频率很高。第一个是“LLM request failed: provider rejected the request schema or tool payload”这类错误基本是工具参数Schema与模型返回的tool_call不匹配。模型返回的参数里多了一个字段、或者类型不匹配供应商校验时会直接拒绝整个请求。排查步骤把provider返回的原始tool_call打印下来和你的工具JSON Schema逐字段比对如果是必填参数缺失就在系统提示词里强调“参数必须完整”如果模型频繁瞎猜参数考虑改用强约束解码。第二个报错是Codex无法发送消息显示更新Agent沙盒。这多半是沙盒进程被旧版本占用、或临时目录权限不对导致的。我自己会先杀掉残留进程再重开如果还不行就重置沙盒目录注意不要手动改沙盒内部文件。“agent execution terminated due to error”这个报错也常被提及它不是单一原因而是所有Agent执行中断的通用提示。遇到它先别慌按“看日志—查工具调用—看模型返回—查配额”的顺序来九成问题都能定位。4.3 给 Agent 做体检一张安全排查清单给Agent做安全检查我的通用清单是六项。第一所有外部输入都视为不可信包括用户消息、网页内容、工具返回值、RAG片段。第二工具权限最小化Agent只需要读就坚决不给写权限涉及资金的工具必须二次确认。第三对Agent的一举一动做日志记录尤其是工具调用参数和返回值。第四设置任务超时和步数上限防止Agent陷入无限循环。第五敏感操作做人和机器双重审批比如删除数据、发邮件、转账。第六定期更新模型和框架版本公开漏洞库扫一遍依赖。这六条看着简单但能做到的团队不多很多时候是上线前临时补一条降级预案结果出事的恰恰是漏掉的那条。我见过一个项目给Agent开了数据库写权限理由是“方便它记录中间状态”结果一次prompt注入让Agent批量改了线上数据。后来规则改为所有写操作必须走一个审批工具才把风险堵住。安全排查不是一次性的每次改工具、换模型、调记忆库都要重新过一遍清单。4.4 遇到“执行终止”按这套顺序排查“Agent Execution Terminated Due to Error”这个报错我今天至少看了三次。它的排查顺序我总结为四步。第一步看Agent的step trace确认是死在模型调用还是死在工具调用第二步看工具返回的异常信息重点看超时、鉴权、数据格式第三步看模型侧有没有配额超限或内容审核拦截第四步看编排层的循环条件是否在正常步数内退出。如果是工具抖动加个带jitter的重试就好如果是模型因为长上下文截断导致输出出错就需要压缩会话历史或者改用摘要。最怕的是把“执行终止”一律当成偶发错误重启了事结果第二天同样的故障再来一遍。我给团队立的规矩是任何Agent执行终止都必须留一份panic report包含输入、步骤trace、错误原文、重试策略。没有这份报告排查效率至少低一半。5. 工具与生态速览技能、画图、搜索与本地工具5.1 Claude Agent Skills 的一线视角Skills 是“说明书示例校验器”Claude Agent Skills是今天另一高热话题。它的核心是把一套可复用的技能打包成目录里面包含说明文档、代码片段、校验要求Agent在需要时动态加载而不是把全部技能都塞进上下文。这和我之前提到的外部记忆思路其实异曲同工都是减少上下文冗余、按需加载。写Skills时的要点是文档要用示例驱动不要只写抽象概念代码要能独立运行且入口和出口足够清晰校验器要能给出明确错误信息。如果你有经常重复的工具调用流程用Skills包一层维护成本会明显降低。比如“检索订单”这个技能你可以把查询语句、字段映射、返回值规范都写进Skills目录Agent每次需要用订单数据时直接加载这个技能包而不是靠系统提示词里那几句模糊描述。我实践后的感受是技能包比纯函数列表好维护得多因为函数列表只能描述“有什么”技能包还能告诉模型“什么时候用、怎么用、出错了怎么处理”。5.2 Hermes Agent 配 Obsidian个人知识库 Agent 的一个可行拼法今天热词里“hermes agent obsidian”连着出现我觉得值得展开说说。把Obsidian当成Agent的长期记忆库本质上是让记忆实体化为Markdown文件。每个文件就是一个知识单元文件名就是Key正文就是Value双链就是记忆之间的索引。Agent处理新信息时先判断是否和已有文件重复再决定是新建笔记还是追加内容。检索时走文件搜索和向量检索的混合方案文件搜索保证精确向量检索保证召回。我搭过一个轻量版一个Python脚本监听Obsidian Vault目录用嵌入模型把每篇笔记切成块写入SQLite向量表Agent对外只暴露一个“搜索笔记”的工具。这个方案的优点是所有记忆都能在Obsidian里直接看到、修改、删除不会像黑盒向量库那样让我心里没底。缺点是文件多了之后双链和标签必须约束好否则检索噪音会很大。如果你本来就是Obsidian重度用户这个拼法可以试试。5.3 Agent 生态里几个有意思的小工具Ransack、画图、LLM Studio今天还有几个有趣的名字。Agent Ransack这名字看起来像文件搜索工具的Agent版本质是把递归搜索、正则匹配封装成技能适合排查日志和定位问题。Agent画图则把绘图SDK封成工具配合LLM规划画布元素和构图。LLM Studio这类本地工具则适合快速对比模型的输出效果。要说价值密度这类小工具其实都不高但它们教会我一件事Agent生态里工具的价值不在于功能多炫而在于能否被模型稳定理解和调用。我也建议想深入Agent的人别只满足于“能跑”试着做一次“工具可观测性改造”给每个工具加上指标上报统计调用次数、失败率、平均耗时。然后你会惊讶地发现某几个工具占了九成调用量而另一些工具几乎没人用。基于这个数据再去优化技能列表比拍脑袋砍工具靠谱得多。今天看下来我的感触是Agent生态已经从“谁的Demo更酷”进入“谁的地基更稳”的阶段。框架、记忆、并发、安全每一样都值得老老实实打磨。最后分享一个我自己的小习惯每个Agent项目第一周就把外部输入隔离和审计日志搭好后面调试和上线会省掉一大半的麻烦。地基打稳Agent才能从玩具变成生产力。