开场先说个我最近遇到的真实场景。上个月帮一个做后台系统的团队做代码评审八个模块里六个是增删改查Controller 里塞着参数校验Service 里做字段搬运Mapper 里写几条几乎一样的 SQLDTO 和 VO 来回转。团队里干了五年的老哥自嘲说这些年写的代码换个表名就能复用。这话听着好笑但笑完得承认一个事实AI Agent 正在吃掉 Java 程序员手里最标准化的那部分工作——CRUD。不是以后可能而是已经在发生需求方开始问这个能不能直接对话完成别给我做页面了。这篇文章想解决的问题很具体当增删改查这类工作被 Agent 承接之后一个写了多年 Java 的人该往哪儿迁移手上的 Spring 那一套东西还有多少能用需要补哪些新能力以及最关键的——怎么把现有的 Service 改造成 Agent 能安全调用的工具而不是推倒重来。内容适合三类人看正在做企业后台开发、感觉自己在重复劳动的 Java 工程师带团队、需要考虑技术栈演进方向的技术负责人以及刚入行、还没被 CRUD 磨平棱角的新人。全文会给出可复现的改造步骤、参数配置、代码骨架和踩坑记录不讲空话。1. 先把话说透Agent 到底吃掉了 CRUD 的哪一块1.1 被吃掉的三层模板代码、胶水逻辑、简单规则我观察下来Agent 蚕食 CRUD 是分三层递进的不是一刀切。第一层是模板代码。Controller 的入参出参包装、DTO 到 Entity 的字段拷贝、分页参数的组装、统一返回体的封装这些东西的规律性极强模型只要看到表结构和几个已有例子就能批量产出一致风格的代码。以前新人上手要照着老代码抄一遍现在这一步基本被跳过了。第二层是胶水逻辑。一个查询订单列表的接口背后往往是三四个服务的拼装查订单主表、查用户信息补昵称、查物流状态补进度、查优惠券补抵扣金额。这类逻辑没有复杂算法难在字段对齐和空值处理而这恰好是大模型比较擅长的部分——它见过太多类似的拼装模式。第三层是简单业务规则。比如金额大于五千要走审批状态为已取消的不能再次提交同一手机号一天最多下三单。这类规则的特点是可枚举、可描述、边界清晰写成自然语言就是现成的规则说明Agent 完全可以在执行前做一轮校验。三层叠起来就是企业开发里工作量占比最大的那块。一个中等规模的后台系统六成以上的接口都属于这个范畴。所以我常说Agent 不是来抢架构设计的饭碗它是来清理地基的。注意这三层被替代的前提是需求描述足够清晰。如果业务方自己都说不清字段从哪来、为空怎么处理那 Agent 也做不了这时候人的价值反而更凸显——把模糊需求翻译成确定性规则。1.2 吃不掉的是什么事务边界、幂等、权限与审计每次有人问我Java 是不是要凉我都会反问你知道一个下单接口为什么不能只写一句 insert 吗事务边界是第一道护城河。跨库写入、跨服务调用、本地消息表、最终一致性补偿这些东西的正确性依赖于对业务语义的深刻理解而不是代码写法。Agent 可以帮你把事务注解写上但它判断不了这个操作到底该不该和那个操作放在同一个事务里那是业务决策。幂等与并发是第二道。用户连点两下提交按钮、消息队列重投、网关超时重试这些场景下代码必须保证执行一次和执行十次结果一样。幂等键怎么设计、唯一索引加在哪张表、乐观锁版本号从哪取这些是经验活。Agent 生成的代码十有八九是裸的 insert跑通了但经不起真实流量。权限与数据隔离是第三道。行级权限、列级脱敏、租户隔离这些规则往往散落在多个地方还带着历史包袱。Agent 不会知道财务角色看不到成本价这种约定俗成的规矩除非你显式告诉它。审计与留痕是第四道。谁在什么时候改了什么字段、改动前后的值是什么这在很多行业是硬性要求。这块反而是 Agent 带来新问题的地方——自然语言驱动的操作留痕比按钮点击更难做你得把用户原话和实际执行的 SQL一起存下来。我的判断是Agent 拿走了写的部分留下了判断的部分。而判断恰恰是值钱的那部分。1.3 一个可量化的判断标准什么样的需求会被替代光凭感觉焦虑没用我给团队用过一个简单的打分表帮大家判断某个需求该不该交给 Agent 承接。四个维度每个 1 到 5 分总分 16 分以上基本可以放心交给 Agent10 分以下老老实实手写。评估维度低分1-2 分表现高分4-5 分表现规则可枚举程度规则散落、有大量例外规则能列成清单例外少数据一致性要求跨服务、需强一致单表操作允许最终一致操作可逆性不可回滚删除类操作可撤销或只是查询调用频率与并发高并发写、秒杀场景低频、内部使用为主举个例子一个根据工单号查询处理进度的需求四个维度全是高分总分接近 20这种需求现在完全可以让 Agent 直接对接工具完成连页面都不用做。反过来批量调整商品价格并同步到多个渠道这个需求一致性要求高、不可逆、还涉及审批分数很低必须人工设计。这个表最大的作用不是分类而是让团队在讨论时有个共同语言。以前争论这个能不能用 AI 做全是主观意见现在对着表打分分歧少了很多。2. 迁移的底层逻辑从写代码的人变成定义边界的人2.1 能力坐标系重构提示词只是表层工具设计才是核心很多 Java 同行一听要转 Agent 方向第一反应是去学提示词写法。我的看法相反提示词是最不值钱的那一层。写得再花哨工具设计得烂Agent 一样跑不出正确结果。为什么因为大模型本质上是个决策器它决定该调哪个工具、传什么参数真正干活的是你写的工具。工具设计得好提示词可以很朴素工具设计得烂提示词写成一本书也救不回来。这跟当年设计 REST 接口是一个道理——接口语义清晰、参数约束明确调用方随便怎么写都不会错接口设计成一坨文档写十万字也天天有人调错。所以迁移的核心动作是把你脑子里的我要写一个 Service 方法换成我要设计一个 Agent 能安全调用的能力单元。这两个视角差别很大。写 Service 方法时你假设调用方是同事他懂业务背景出错了会看日志设计工具时你假设调用方是个聪明但完全不懂你业务的实习生它会把参数填错、会重复调用、会在不该调用的时候调用。我一般用三个问题自检一个工具设计得好不好第一光看工具名和描述能不能判断什么时候该用、什么时候不该用第二参数传错了会不会造成不可挽回的后果第三返回结果会不会撑爆上下文三个问题都能答是这个工具才算合格。2.2 工具设计的三条硬规则幂等、可重试、有界这三条是我踩了不少坑之后总结的几乎每条都对应一次线上事故。幂等。Agent 有个特点它不确定的时候会重试。网络抖动、超时、返回格式不对它都可能再调一次。如果你的工具是创建订单第二次调用就多出一单。解决办法是让 Agent 每次调用带一个幂等键或者在工具内部做先查后写——按业务唯一键查一下存在就返回已有结果不存在才创建。我倾向后者因为不依赖 Agent 的配合更稳。可重试。意思是失败之后重放是安全的。查询类天然可重试写操作要做到可重试就得把检查—执行拆成原子步骤或者在数据库层加唯一约束兜底。最怕的是部分成功——比如扣了库存但没生成订单这种工具一次失败就够喝一壶。所以写操作要么放进一个事务要么设计成状态机推进每一步都可幂等重放。有界。两层含义参数有界、结果有界。参数有界指每个参数都要有明确的范围约束字符串长度上限、数字区间、枚举取值全都写进 Schema 里。结果有界指返回的行数、字段数、字符数都要设上限。我见过一个查询工具返回了八千行数据直接把上下文塞爆后面整个对话全乱套了。// 工具方法的三个约束用注解显式声明方便统一拦截 public interface AgentTool { String name(); // 动词名词如 query_order_detail String description(); // 何时用、何时不用必写 int maxRows() default 20; // 结果行数上限 boolean idempotent() default true; boolean writeOperation() default false; // 写操作需走审批链路 }实操心得把工具方法全部放在一个独立的包下用注解标记启动时扫描注册成工具清单。这样做的最大好处是——你能一眼看到系统对外暴露了哪些能力而不是散落在几十个 Service 里自己都数不清。我第一次做的时候没做隔离结果 Agent 能调到内部的管理接口差点出事。2.3 契约先行把 Service 改造成 Agent 可调用的工具集改造顺序我建议是先只读、后写入先单表、后关联先内部、后对外。这个顺序不是拍脑袋是因为只读工具出错了顶多返回错误数据写工具出错了要修数据。具体怎么改拿一个典型的 Service 方法举例。原来是这样的public PageResultOrderVO pageQuery(OrderQueryDTO dto) { // 十几个可选条件拼装、关联三张表、字段转换 }这个方法对 Agent 不友好参数是个大对象Agent 不知道该填哪些返回是分页结构包含大量它用不上的字段。改造思路是把它拆成几个语义更明确的工具AgentTool(name query_order_by_no, description 按订单号精确查询单个订单的概要信息。仅在用户提供了明确的订单号时使用如果只有手机号或时间范围请改用 search_orders。) public OrderBrief queryByNo(Param(desc 订单号18位数字以SO开头, pattern ^SO\\d{16}$) String orderNo) { // 内部仍调用原有 Service只是做参数收敛和结果裁剪 }注意几个细节工具名用了动词加名词一眼能看懂描述里明确写了什么时候不该用这行字能挡掉大量误调用参数用正则约束Agent 填错格式会被直接拦下返回值是裁剪后的OrderBrief只包含订单号、状态、金额、创建时间四个字段。这套改造做完你会发现原来的 Service 一行没删只是在外面套了一层适配层。这个设计我很坚持——适配层可以随时推倒重来业务逻辑不动。等到哪天 Agent 方案不流行了把适配层删掉系统照样跑。3. 动手把现有 CRUD 服务改造成 Agent 可调工具3.1 改造步骤总览与目录结构整个改造我一般分五步走每步都有明确的产出物避免一上来就写代码写到一半发现方向错了。第一步是盘点。把现有 Service 里所有 public 方法列出来标注读写属性、调用频率、是否有副作用。这一步产出一张表通常会发现实际需要工具化的方法只有三成剩下七成是内部复用或者根本没人调。第二步是收敛。把粒度太粗的方法拆开把粒度太细的方法合并。判断标准是一个工具对应一个明确的用户意图。用户说查一下这个订单到哪了对应一个工具用户说把这批订单都改一下地址对应另一个工具而且这个工具应该带审批。第三步是裁剪。给每个工具定义精简的返回结构字段数量控制在十个以内。这一步最容易被忽略但对效果影响最大。第四步是加护栏。参数校验、权限校验、频率限制、写操作二次确认全在适配层做。第五步是评测。准备一批真实问题跑一遍看准确率。没有评测就直接上线等于闭眼开车。目录结构建议这样组织和业务代码物理隔离src/main/java/ └── agent/ ├── tool/ // 工具定义一个类一个领域 │ ├── OrderTools.java │ └── UserTools.java ├── guard/ // 护栏校验、限流、审批 │ ├── ParamValidator.java │ └── WriteApproval.java ├── view/ // 裁剪后的返回结构 │ └── OrderBrief.java └── eval/ // 评测用例与跑批脚本 └── golden-cases.jsonl物理隔离带来的好处很实际做代码评审时只要看agent这个包就够了不用在几百个 Service 里翻。我见过有团队把工具方法直接写在原 Service 上三个月后没人说得清哪些方法被 Agent 调过。3.2 工具描述与参数 Schema 的写法工具描述是整个方案里最需要打磨的部分没有之一。我改过十几版总结下来有这么几条经验。描述要写三件事这个工具做什么、什么情况下用、什么情况下不要用。第三点最重要也最容易被漏掉。比如查询订单的工具如果只写查询订单Agent 在用户说帮我看看最近买了啥的时候也可能调它但它需要的是订单号调了也白调。加上一句用户未提供订单号时不要调用误调用率能降一大截。参数要给例子。Schema 里除了类型和约束加一个example字段效果比写十行说明还好。{ name: search_orders, description: 按时间范围和状态查询订单列表。用户只说订单号时请改用 query_order_by_no。单次最多返回20条超出请提示用户缩小范围。, parameters: { type: object, properties: { startDate: { type: string, pattern: ^\\d{4}-\\d{2}-\\d{2}$, description: 开始日期格式 yyyy-MM-dd含当天, example: 2024-03-01 }, endDate: { type: string, pattern: ^\\d{4}-\\d{2}-\\d{2}$, description: 结束日期格式 yyyy-MM-dd含当天跨度不得超过90天, example: 2024-03-31 }, status: { type: string, enum: [CREATED, PAID, SHIPPED, DONE, CANCELLED], description: 订单状态不确定时不要传默认查全部 } }, required: [startDate, endDate] } }几个细节值得说。日期跨度限制写在描述里是因为单纯在代码里校验然后报错Agent 拿到错误信息后要再问用户一轮体验很差写进描述里它第一次就会主动收敛范围。枚举值一定要列全别让 Agent 猜。required只放真正必须的字段可选字段越少越好——每多一个可选参数模型填错的概率就涨一点。还有一条不要暴露内部 ID。工具参数里尽量用业务单号、手机号、工单编码这类人看得懂的标识别用自增主键。原因很简单Agent 拿不到主键用户嘴里也不会说主键。我曾经设计过一个需要传tenantId的工具结果 Agent 天天编造租户 ID后来改成从会话上下文里取问题立刻消失。3.3 结果裁剪与上下文预算控制结果裁剪这件事我吃过一次大亏。早期做一个工单查询工具直接把实体类序列化返回一个工单带二十多个字段还有嵌套的流转记录。用户问了一句这个工单现在什么状态Agent 收到的是一大坨 JSON然后它开始把流转记录里的历史状态也念出来回答得又长又乱。后来改成三档返回概要档给列表用只给编号、状态、时间三个字段详情档给单条查询用给到十个字段以内全量档只在用户明确要求导出或看全部字段时给。三档分别对应三个工具描述里写清区别。这个改动之后同样的对话轮次下上下文占用降了差不多六成。裁剪的具体做法我一般用白名单而不是黑名单——明确列出要返回哪些字段而不是排除哪些。黑名单的问题是以后实体类加字段新字段会自动流出去说不定哪个就是敏感信息。白名单加字段要手动改麻烦一点但安全。上下文预算这块给个参考分配按 128K 窗口算用途预算占比说明系统提示与角色设定5%固定不变可缓存工具定义清单10%工具越多占比越高超过 20 个要考虑分组历史对话30%超过阈值做摘要压缩检索到的业务资料20%按相关度截断单次工具返回15%硬上限超了强制分页输出预留20%别把窗口占满留余量这个表不是标准答案但用它做预算意识训练很有用。我带的几个人刚开始都不信工具定义能占 10%一数发现有三十多个工具每个描述写了七八行加起来确实不少。后来砍到十五个核心工具剩下的合并上下文立刻宽松了。3.4 执行链路从意图到落库的完整走法一条完整的执行链路我一般拆成六段每段都有明确的失败处理。第一段是意图识别。判断用户这句话是想查询、想修改还是纯闲聊。这段可以先用规则过滤命中关键词的直接进对应分支剩下的再交给模型。加规则这一步能省不少调用成本。第二段是槽位抽取。把用户话里的关键信息抽成结构化字段比如订单号、时间范围。抽不到的字段标记为缺失不要瞎猜。第三段是工具路由。根据意图和已有槽位选工具。槽位不全的优先选能补齐信息的工具比如用户只说了手机号那就先调按手机号查订单。第四段是参数校验。这一层必须是纯代码不能靠模型。格式不对直接返回结构化错误告诉模型哪个字段错了、应该是什么格式。第五段是执行与兜底。工具执行加超时、加重试、加熔断。失败信息要写得能让模型看懂别直接抛堆栈。第六段是结果回写与留痕。把执行结果、原始用户输入、工具调用参数一起落库。留痕这件事别嫌麻烦出了问题排查全靠它。public AgentResponse handle(String userInput, SessionCtx ctx) { Intent intent intentRouter.route(userInput); // 规则优先模型兜底 Slots slots slotExtractor.extract(userInput, ctx); // 缺失字段留空不猜 ToolSpec tool toolSelector.select(intent, slots); // 选不到就反问用户 if (tool null) return AgentResponse.askForMore(slots.missing()); ValidationResult vr paramValidator.check(tool, slots); // 纯代码校验 if (!vr.ok()) return AgentResponse.retryWithHint(vr.message()); if (tool.writeOperation()) { // 写操作走审批 return approvalService.submitAndWait(tool, slots, ctx); } ToolResult result toolExecutor.runWithGuard(tool, slots); // 超时/重试/熔断 auditLog.record(userInput, tool, slots, result); // 全链路留痕 return AgentResponse.ok(trimmer.trim(result)); }这段代码里我最想强调的是askForMore这个分支。很多人做 Agent 上来就追求全自动结果模型在信息不全的时候硬猜猜错了还得道歉。其实主动反问是更好的体验——您是要查哪一天的订单这一句话比猜错三轮强得多。4. 关键参数与实测让 Agent 跑得稳的几个数字4.1 超时、重试、熔断的具体取值这些参数我没少调下面这组是跑了几个月比较稳的配置可以直接抄。参数建议值理由单次工具执行超时3 秒查询类接口正常在 200ms 内3 秒足够覆盖慢查询工具重试次数2 次再多收益递减还容易放大下游压力重试退避300ms / 900ms指数退避避开瞬时抖动单轮最大工具调用次数6 次超过说明路由有问题强制中断单次返回最大行数20 行再多模型也读不完还会挤占上下文单字段最大字符数500防止超长文本压垮上下文熔断错误率阈值50%30 秒窗口内错误率超这个数直接熔断熔断恢复探测半开5 秒一次避免熔断后一直不恢复关于重试有个细节只重试幂等的工具。写操作类工具默认不重试失败就返回错误让上层决策。我见过有团队给所有工具统一加重试结果一次下单请求生成了三笔订单查了半天才定位到。还有单轮调用次数上限这个值。为什么是 6因为正常业务场景下一轮对话需要的工具调用很少超过 4 次——查询一次、可能补查一次、写入一次、确认一次。超过 6 次基本都是模型在绕圈子比如反复查同一个订单但参数一直不对。这时候中断比让它继续跑更划算。4.2 评测集怎么建才有效没有评测集的 Agent 改造等于没做测试就上线。但评测集不是越多越好关键是覆盖到位。我一般建 30 条左右的黄金用例分四类。正常路径占一半。覆盖最常见的十几种问法每种问法写两三个变体。比如查订单用户可能说帮我看看 SO2024 那个单子也可能说我的订单到哪了还可能直接甩个订单号过来。边界情况占两成。时间跨度超限、参数格式不对、查询结果为空、返回条数超上限。这类用例最容易暴露工具设计的缺陷。多轮对话占两成。第一轮信息不全第二轮补充或者用户中途改主意。专门测状态管理有没有问题。恶意输入占一成。比如用户说把所有订单都删了测的是护栏有没有生效。这类用例不能省我见过 Agent 被一句话骗着调了批量删除接口的情况。评测指标不用太复杂看两个就够任务完成率最终有没有拿到正确结果和无效调用率调用了但结果没用的比例。第一个低了说明工具或描述有问题第二个高了说明路由或上下文有问题。跑评测一定要固化成脚本可重复执行。每改一次工具描述就跑一遍看指标是涨还是跌。我吃过凭感觉改描述的亏改完自我感觉良好实际准确率掉了十个百分点还是跑评测才发现。实测数据分享一个包含 12 个工具、覆盖订单和用户两个领域的改造项目第一版评测完成率是 61%。主要问题集中在三类工具描述里没说清使用场景导致误调用占一半、返回字段太多导致模型抓错重点占三成、参数格式约束缺失占两成。针对这三类改完之后完成率涨到 89%无效调用率从 34% 降到 9%。这个提升幅度在整个过程中很常见关键是要有数据指导改哪儿。5. 常见问题与排查实录5.1 参数幻觉模型编造了不存在的订单号这是最高频的问题没有之一。用户说我那笔订单有点问题模型直接编了个SO2024031500001234传下去工具返回空它接着编一个来回几次用户已经不耐烦了。排查思路分三层。先看描述里有没有明确要求参数必须来自用户输入这句话得显式写进去模型是听话的但你不说它不知道。再看参数格式约束够不够严订单号加正则编造的号码大概率过不了格式校验能被提前拦下。最后看有没有做存在性预检查拿订单号和当前会话用户绑定的订单列表比对一下不匹配的直接返回未找到该订单请确认订单号别往下走。更彻底的做法是改变交互模式当用户没给标识时不要调用需要标识的工具改用列出最近订单让用户选的工具。这个改动看起来绕实际体验好很多因为它把猜换成了选。5.2 写操作爆炸半径怎么把损失控制在最小写操作出问题的后果比查询严重得多所以我把这块单独拎出来说。控制手段有四个建议全上。范围限制。批量写操作的工具参数里必须有明确的批次上限比如单次最多处理 20 条超了要求拆分。这个上限写进描述同时也写进代码校验双保险。先查后写。执行写操作前先调一次查询工具把要改的数据展示给用户确认。您是要把这 3 笔订单的收货地址改成 XX 吗这一步增加的交互成本很小挡住的错误却很大。试运行模式。复杂写操作提供 dry-run 参数只返回将会修改什么不真正落库。用户确认之后再执行一次真实调用。审批链路。高风险操作金额超过阈值、影响客户数量超过阈值走人工审批Agent 只负责发起和跟踪。这条是最稳的兜底。// 写操作的护栏骨架 AgentTool(name update_order_address, description 修改订单收货地址。仅在用户明确提供了订单号和完整新地址时调用单次仅支持一个订单。, writeOperation true) public WriteResult updateAddress(Param(pattern ^SO\\d{16}$) String orderNo, Param(maxLen 200) String newAddress, Param(desc 试运行为 true 时只返回将要修改的内容) boolean dryRun) { OrderBrief before orderService.queryByNo(orderNo); // 先查 if (before null) return WriteResult.notFound(orderNo); // 不存在直接返回 if (before.status() OrderStatus.SHIPPED) { // 状态机校验 return WriteResult.reject(订单已发货无法修改地址); } if (dryRun) return WriteResult.preview(before, newAddress); // 试运行 return WriteResult.ok(orderService.updateAddress(orderNo, newAddress)); }5.3 多轮对话里的状态丢失与错乱第三个高频问题。用户第一轮说帮我查下订单第二轮说改成新地址第三轮说再看看别的。到第三轮的时候模型已经忘了前面说的是哪个订单因为它看到的历史被压缩了或者工具返回的内容把关键信息挤掉了。解决办法是维护一张显式的槽位表不依赖模型自己记。每个会话有一个结构化的槽位对象存着当前讨论的订单号、用户身份、最近一次查询条件。每轮对话开始前把这张表以简洁的形式注入到上下文里格式固定占不了几个 token但效果立竿见影。{ sessionId: s-20240315-001, userId: u-8821, activeOrder: SO2024031500001234, lastIntent: query_order, pendingConfirm: null, turnCount: 3 }这张表还有个别的好处排查问题时一目了然。用户投诉它答非所问你把这表拉出来一看activeOrder是空的那就知道是槽位没填上不是模型的问题。5.4 常见问题速查表把上面这些和另外几个高频问题整理成表出问题的时候直接对号入座。现象优先排查方向常见根因处理办法模型反复调同一个工具参数校验参数格式不合法被拒模型不知道原因错误信息里写清格式要求答非所问、答上一轮的问题槽位管理历史被压缩关键实体丢失维护显式槽位表并注入工具选错工具描述多个工具描述边界模糊描述里补何时不要用返回内容超长结果裁剪直接序列化实体类改白名单返回加行数上限编造数据参数约束缺正则、缺存在性校验加格式约束 预检查调用成本暴涨上下文预算工具定义和历史无节制增长精简工具数历史做摘要响应慢串行调用多个独立查询串行执行无依赖的工具调用并行化最后一条我想多说一句。工具调用的并行化收益很明显一轮里如果有三个互不依赖的查询串行要 900ms并行只要 300ms 出头。但要注意别乱并行——有依赖关系的调用必须串行比如先查用户再查订单并行会导致后一个拿不到前一个的结果。6. 迁移路径一个 Java 程序员的 90 天行动清单6.1 能力盘点哪些能直接复用哪些要从零补先说好消息你这些年积累的东西大半没白学。直接复用的领域建模能力这是最值钱的Agent 时代更值钱因为工具设计本质就是领域建模、SQL 与数据库设计、事务与并发控制、接口设计规范、日志与监控体系。这些是地基换个上层应用照样用。需要强化的把业务能力拆成原子工具的抽象能力、结构化描述写作写工具描述本质上是写文档但不能有歧义、评测思维从跑通就行变成用数据说话、护栏设计把安全边界往前挪。需要新学的上下文预算管理、工具编排与路由、检索增强的基本原理、模型输出的不确定性处理。注意我说的都是原理和工程不是某个具体产品的用法——具体产品三个月换一茬原理能用五年。给个自评表每个维度 1 到 5 分低于 3 分的优先补能力维度权重自评要点领域建模与工具抽象高能否把业务流程拆成独立、可组合的能力单元结构化描述写作高写的工具描述是否无歧义、有无何时不用护栏与安全设计高是否习惯性考虑幂等、限流、审批评测与数据分析中能否设计评测集并用指标驱动迭代上下文与成本控制中是否清楚每一轮对话的 token 花在哪传统后端基本功高事务、并发、索引、缓存别丢6.2 90 天分阶段计划我把这个计划给过几个同事反馈是节奏还算合理不需要脱产每天抽一两个小时就够。第 1-2 周跑通一个只读场景。选一个你自己最熟的查询需求把它改造成一个工具接上一个对话入口能跑通就行。目标不是做好是建立手感——你会很快发现原来模型是这么理解我的描述的这个体感比看十篇文章有用。第 3-4 周工具化改造一个小模块。挑一个包含五到八个接口的模块完整走一遍盘点、收敛、裁剪、加护栏的流程。这一步的重点是把结果裁剪和参数约束做扎实做完之后你会对什么叫有界有具体认知。第 5-6 周建评测集。准备 30 条用例写个跑批脚本把完成率和无效调用率跑出来。这一步是最枯燥的但也是分水岭——做完这一步的人和不做的人后面差距会越拉越大。第 7-8 周接入一个写操作。选风险最低的写场景比如修改备注这种可逆的。把幂等、先查后写、试运行、审批这四道护栏全走一遍。这一步会逼你想清楚错了怎么办。第 9-10 周可观测性补齐。把工具调用日志、耗时、错误率、成本都埋上点做个简单的看板。没有这个后面所有优化都是盲调。第 11-12 周沉淀与分享。把踩过的坑、参数配置、模板代码整理成团队文档做一次内部分享。讲一遍是最好的复习而且能逼自己把模糊的地方想清楚。6.3 该焦虑的和不该焦虑的说了这么多最后聊点实在的。不该焦虑的Java 会不会消失。不会。企业系统的复杂度不会因为多了个 Agent 就降低反而会上升——你要处理的是工具编排、幂等、审计、成本这些全是后端的活。我甚至觉得Agent 落地做得好的团队后端功底都不差因为那些看似AI 问题的故障最后八成定位到数据库索引或者事务边界上。该焦虑的只会照着模板写 CRUD且不愿意把视角从实现抬到设计。这部分工作确实在快速消失而且消失得比想象中快。我见过一个团队去年还需要三个人维护的后台管理模块今年一个人加一套工具就撑住了省下来的两个人转去做数据治理和流程梳理。转得动的留下了转不动的就比较被动。一个反直觉的观察Agent 做得越深入对把话说清楚的能力要求越高。工具描述写得含糊、字段含义定义不清、异常处理约定不明这些问题在人工开发时代会被同事的默契兜住在 Agent 时代会直接变成故障。所以那些平时就喜欢把接口文档写明白、把命名抠清楚的人迁移起来反而最顺。我个人在实际操作中的体会是这件事没有想象中那么需要从头学起。你把一个 Service 方法改造成工具的过程和你当年把一个巨型 Servlet 拆成三层架构的过程本质上是同一件事——都是识别边界、定义契约、划清职责。区别只是这次的调用方从同事写的代码变成了一个聪明但会犯错的模型。想明白这一点手上那些看似过时的经验反而成了最硬的底牌。最后分享一个小技巧成本几乎为零但收益很大给你改造的每个工具都写一句如果我错了最坏会怎样。这句话逼着你把爆炸半径想清楚写不出来就说明这个工具还不该放出去。我给团队定的规矩是这句话写不出来的工具一律不允许接入对话入口。这条规矩挡住的问题比任何技术方案都多。
开场先说个我最近遇到的真实场景。上个月帮一个做后台系统的团队做代码评审八个模块里六个是增删改查Controller 里塞着参数校验Service 里做字段搬运Mapper 里写几条几乎一样的 SQLDTO 和 VO 来回转。团队里干了五年的老哥自嘲说这些年写的代码换个表名就能复用。这话听着好笑但笑完得承认一个事实AI Agent 正在吃掉 Java 程序员手里最标准化的那部分工作——CRUD。不是以后可能而是已经在发生需求方开始问这个能不能直接对话完成别给我做页面了。这篇文章想解决的问题很具体当增删改查这类工作被 Agent 承接之后一个写了多年 Java 的人该往哪儿迁移手上的 Spring 那一套东西还有多少能用需要补哪些新能力以及最关键的——怎么把现有的 Service 改造成 Agent 能安全调用的工具而不是推倒重来。内容适合三类人看正在做企业后台开发、感觉自己在重复劳动的 Java 工程师带团队、需要考虑技术栈演进方向的技术负责人以及刚入行、还没被 CRUD 磨平棱角的新人。全文会给出可复现的改造步骤、参数配置、代码骨架和踩坑记录不讲空话。1. 先把话说透Agent 到底吃掉了 CRUD 的哪一块1.1 被吃掉的三层模板代码、胶水逻辑、简单规则我观察下来Agent 蚕食 CRUD 是分三层递进的不是一刀切。第一层是模板代码。Controller 的入参出参包装、DTO 到 Entity 的字段拷贝、分页参数的组装、统一返回体的封装这些东西的规律性极强模型只要看到表结构和几个已有例子就能批量产出一致风格的代码。以前新人上手要照着老代码抄一遍现在这一步基本被跳过了。第二层是胶水逻辑。一个查询订单列表的接口背后往往是三四个服务的拼装查订单主表、查用户信息补昵称、查物流状态补进度、查优惠券补抵扣金额。这类逻辑没有复杂算法难在字段对齐和空值处理而这恰好是大模型比较擅长的部分——它见过太多类似的拼装模式。第三层是简单业务规则。比如金额大于五千要走审批状态为已取消的不能再次提交同一手机号一天最多下三单。这类规则的特点是可枚举、可描述、边界清晰写成自然语言就是现成的规则说明Agent 完全可以在执行前做一轮校验。三层叠起来就是企业开发里工作量占比最大的那块。一个中等规模的后台系统六成以上的接口都属于这个范畴。所以我常说Agent 不是来抢架构设计的饭碗它是来清理地基的。注意这三层被替代的前提是需求描述足够清晰。如果业务方自己都说不清字段从哪来、为空怎么处理那 Agent 也做不了这时候人的价值反而更凸显——把模糊需求翻译成确定性规则。1.2 吃不掉的是什么事务边界、幂等、权限与审计每次有人问我Java 是不是要凉我都会反问你知道一个下单接口为什么不能只写一句 insert 吗事务边界是第一道护城河。跨库写入、跨服务调用、本地消息表、最终一致性补偿这些东西的正确性依赖于对业务语义的深刻理解而不是代码写法。Agent 可以帮你把事务注解写上但它判断不了这个操作到底该不该和那个操作放在同一个事务里那是业务决策。幂等与并发是第二道。用户连点两下提交按钮、消息队列重投、网关超时重试这些场景下代码必须保证执行一次和执行十次结果一样。幂等键怎么设计、唯一索引加在哪张表、乐观锁版本号从哪取这些是经验活。Agent 生成的代码十有八九是裸的 insert跑通了但经不起真实流量。权限与数据隔离是第三道。行级权限、列级脱敏、租户隔离这些规则往往散落在多个地方还带着历史包袱。Agent 不会知道财务角色看不到成本价这种约定俗成的规矩除非你显式告诉它。审计与留痕是第四道。谁在什么时候改了什么字段、改动前后的值是什么这在很多行业是硬性要求。这块反而是 Agent 带来新问题的地方——自然语言驱动的操作留痕比按钮点击更难做你得把用户原话和实际执行的 SQL一起存下来。我的判断是Agent 拿走了写的部分留下了判断的部分。而判断恰恰是值钱的那部分。1.3 一个可量化的判断标准什么样的需求会被替代光凭感觉焦虑没用我给团队用过一个简单的打分表帮大家判断某个需求该不该交给 Agent 承接。四个维度每个 1 到 5 分总分 16 分以上基本可以放心交给 Agent10 分以下老老实实手写。评估维度低分1-2 分表现高分4-5 分表现规则可枚举程度规则散落、有大量例外规则能列成清单例外少数据一致性要求跨服务、需强一致单表操作允许最终一致操作可逆性不可回滚删除类操作可撤销或只是查询调用频率与并发高并发写、秒杀场景低频、内部使用为主举个例子一个根据工单号查询处理进度的需求四个维度全是高分总分接近 20这种需求现在完全可以让 Agent 直接对接工具完成连页面都不用做。反过来批量调整商品价格并同步到多个渠道这个需求一致性要求高、不可逆、还涉及审批分数很低必须人工设计。这个表最大的作用不是分类而是让团队在讨论时有个共同语言。以前争论这个能不能用 AI 做全是主观意见现在对着表打分分歧少了很多。2. 迁移的底层逻辑从写代码的人变成定义边界的人2.1 能力坐标系重构提示词只是表层工具设计才是核心很多 Java 同行一听要转 Agent 方向第一反应是去学提示词写法。我的看法相反提示词是最不值钱的那一层。写得再花哨工具设计得烂Agent 一样跑不出正确结果。为什么因为大模型本质上是个决策器它决定该调哪个工具、传什么参数真正干活的是你写的工具。工具设计得好提示词可以很朴素工具设计得烂提示词写成一本书也救不回来。这跟当年设计 REST 接口是一个道理——接口语义清晰、参数约束明确调用方随便怎么写都不会错接口设计成一坨文档写十万字也天天有人调错。所以迁移的核心动作是把你脑子里的我要写一个 Service 方法换成我要设计一个 Agent 能安全调用的能力单元。这两个视角差别很大。写 Service 方法时你假设调用方是同事他懂业务背景出错了会看日志设计工具时你假设调用方是个聪明但完全不懂你业务的实习生它会把参数填错、会重复调用、会在不该调用的时候调用。我一般用三个问题自检一个工具设计得好不好第一光看工具名和描述能不能判断什么时候该用、什么时候不该用第二参数传错了会不会造成不可挽回的后果第三返回结果会不会撑爆上下文三个问题都能答是这个工具才算合格。2.2 工具设计的三条硬规则幂等、可重试、有界这三条是我踩了不少坑之后总结的几乎每条都对应一次线上事故。幂等。Agent 有个特点它不确定的时候会重试。网络抖动、超时、返回格式不对它都可能再调一次。如果你的工具是创建订单第二次调用就多出一单。解决办法是让 Agent 每次调用带一个幂等键或者在工具内部做先查后写——按业务唯一键查一下存在就返回已有结果不存在才创建。我倾向后者因为不依赖 Agent 的配合更稳。可重试。意思是失败之后重放是安全的。查询类天然可重试写操作要做到可重试就得把检查—执行拆成原子步骤或者在数据库层加唯一约束兜底。最怕的是部分成功——比如扣了库存但没生成订单这种工具一次失败就够喝一壶。所以写操作要么放进一个事务要么设计成状态机推进每一步都可幂等重放。有界。两层含义参数有界、结果有界。参数有界指每个参数都要有明确的范围约束字符串长度上限、数字区间、枚举取值全都写进 Schema 里。结果有界指返回的行数、字段数、字符数都要设上限。我见过一个查询工具返回了八千行数据直接把上下文塞爆后面整个对话全乱套了。// 工具方法的三个约束用注解显式声明方便统一拦截 public interface AgentTool { String name(); // 动词名词如 query_order_detail String description(); // 何时用、何时不用必写 int maxRows() default 20; // 结果行数上限 boolean idempotent() default true; boolean writeOperation() default false; // 写操作需走审批链路 }实操心得把工具方法全部放在一个独立的包下用注解标记启动时扫描注册成工具清单。这样做的最大好处是——你能一眼看到系统对外暴露了哪些能力而不是散落在几十个 Service 里自己都数不清。我第一次做的时候没做隔离结果 Agent 能调到内部的管理接口差点出事。2.3 契约先行把 Service 改造成 Agent 可调用的工具集改造顺序我建议是先只读、后写入先单表、后关联先内部、后对外。这个顺序不是拍脑袋是因为只读工具出错了顶多返回错误数据写工具出错了要修数据。具体怎么改拿一个典型的 Service 方法举例。原来是这样的public PageResultOrderVO pageQuery(OrderQueryDTO dto) { // 十几个可选条件拼装、关联三张表、字段转换 }这个方法对 Agent 不友好参数是个大对象Agent 不知道该填哪些返回是分页结构包含大量它用不上的字段。改造思路是把它拆成几个语义更明确的工具AgentTool(name query_order_by_no, description 按订单号精确查询单个订单的概要信息。仅在用户提供了明确的订单号时使用如果只有手机号或时间范围请改用 search_orders。) public OrderBrief queryByNo(Param(desc 订单号18位数字以SO开头, pattern ^SO\\d{16}$) String orderNo) { // 内部仍调用原有 Service只是做参数收敛和结果裁剪 }注意几个细节工具名用了动词加名词一眼能看懂描述里明确写了什么时候不该用这行字能挡掉大量误调用参数用正则约束Agent 填错格式会被直接拦下返回值是裁剪后的OrderBrief只包含订单号、状态、金额、创建时间四个字段。这套改造做完你会发现原来的 Service 一行没删只是在外面套了一层适配层。这个设计我很坚持——适配层可以随时推倒重来业务逻辑不动。等到哪天 Agent 方案不流行了把适配层删掉系统照样跑。3. 动手把现有 CRUD 服务改造成 Agent 可调工具3.1 改造步骤总览与目录结构整个改造我一般分五步走每步都有明确的产出物避免一上来就写代码写到一半发现方向错了。第一步是盘点。把现有 Service 里所有 public 方法列出来标注读写属性、调用频率、是否有副作用。这一步产出一张表通常会发现实际需要工具化的方法只有三成剩下七成是内部复用或者根本没人调。第二步是收敛。把粒度太粗的方法拆开把粒度太细的方法合并。判断标准是一个工具对应一个明确的用户意图。用户说查一下这个订单到哪了对应一个工具用户说把这批订单都改一下地址对应另一个工具而且这个工具应该带审批。第三步是裁剪。给每个工具定义精简的返回结构字段数量控制在十个以内。这一步最容易被忽略但对效果影响最大。第四步是加护栏。参数校验、权限校验、频率限制、写操作二次确认全在适配层做。第五步是评测。准备一批真实问题跑一遍看准确率。没有评测就直接上线等于闭眼开车。目录结构建议这样组织和业务代码物理隔离src/main/java/ └── agent/ ├── tool/ // 工具定义一个类一个领域 │ ├── OrderTools.java │ └── UserTools.java ├── guard/ // 护栏校验、限流、审批 │ ├── ParamValidator.java │ └── WriteApproval.java ├── view/ // 裁剪后的返回结构 │ └── OrderBrief.java └── eval/ // 评测用例与跑批脚本 └── golden-cases.jsonl物理隔离带来的好处很实际做代码评审时只要看agent这个包就够了不用在几百个 Service 里翻。我见过有团队把工具方法直接写在原 Service 上三个月后没人说得清哪些方法被 Agent 调过。3.2 工具描述与参数 Schema 的写法工具描述是整个方案里最需要打磨的部分没有之一。我改过十几版总结下来有这么几条经验。描述要写三件事这个工具做什么、什么情况下用、什么情况下不要用。第三点最重要也最容易被漏掉。比如查询订单的工具如果只写查询订单Agent 在用户说帮我看看最近买了啥的时候也可能调它但它需要的是订单号调了也白调。加上一句用户未提供订单号时不要调用误调用率能降一大截。参数要给例子。Schema 里除了类型和约束加一个example字段效果比写十行说明还好。{ name: search_orders, description: 按时间范围和状态查询订单列表。用户只说订单号时请改用 query_order_by_no。单次最多返回20条超出请提示用户缩小范围。, parameters: { type: object, properties: { startDate: { type: string, pattern: ^\\d{4}-\\d{2}-\\d{2}$, description: 开始日期格式 yyyy-MM-dd含当天, example: 2024-03-01 }, endDate: { type: string, pattern: ^\\d{4}-\\d{2}-\\d{2}$, description: 结束日期格式 yyyy-MM-dd含当天跨度不得超过90天, example: 2024-03-31 }, status: { type: string, enum: [CREATED, PAID, SHIPPED, DONE, CANCELLED], description: 订单状态不确定时不要传默认查全部 } }, required: [startDate, endDate] } }几个细节值得说。日期跨度限制写在描述里是因为单纯在代码里校验然后报错Agent 拿到错误信息后要再问用户一轮体验很差写进描述里它第一次就会主动收敛范围。枚举值一定要列全别让 Agent 猜。required只放真正必须的字段可选字段越少越好——每多一个可选参数模型填错的概率就涨一点。还有一条不要暴露内部 ID。工具参数里尽量用业务单号、手机号、工单编码这类人看得懂的标识别用自增主键。原因很简单Agent 拿不到主键用户嘴里也不会说主键。我曾经设计过一个需要传tenantId的工具结果 Agent 天天编造租户 ID后来改成从会话上下文里取问题立刻消失。3.3 结果裁剪与上下文预算控制结果裁剪这件事我吃过一次大亏。早期做一个工单查询工具直接把实体类序列化返回一个工单带二十多个字段还有嵌套的流转记录。用户问了一句这个工单现在什么状态Agent 收到的是一大坨 JSON然后它开始把流转记录里的历史状态也念出来回答得又长又乱。后来改成三档返回概要档给列表用只给编号、状态、时间三个字段详情档给单条查询用给到十个字段以内全量档只在用户明确要求导出或看全部字段时给。三档分别对应三个工具描述里写清区别。这个改动之后同样的对话轮次下上下文占用降了差不多六成。裁剪的具体做法我一般用白名单而不是黑名单——明确列出要返回哪些字段而不是排除哪些。黑名单的问题是以后实体类加字段新字段会自动流出去说不定哪个就是敏感信息。白名单加字段要手动改麻烦一点但安全。上下文预算这块给个参考分配按 128K 窗口算用途预算占比说明系统提示与角色设定5%固定不变可缓存工具定义清单10%工具越多占比越高超过 20 个要考虑分组历史对话30%超过阈值做摘要压缩检索到的业务资料20%按相关度截断单次工具返回15%硬上限超了强制分页输出预留20%别把窗口占满留余量这个表不是标准答案但用它做预算意识训练很有用。我带的几个人刚开始都不信工具定义能占 10%一数发现有三十多个工具每个描述写了七八行加起来确实不少。后来砍到十五个核心工具剩下的合并上下文立刻宽松了。3.4 执行链路从意图到落库的完整走法一条完整的执行链路我一般拆成六段每段都有明确的失败处理。第一段是意图识别。判断用户这句话是想查询、想修改还是纯闲聊。这段可以先用规则过滤命中关键词的直接进对应分支剩下的再交给模型。加规则这一步能省不少调用成本。第二段是槽位抽取。把用户话里的关键信息抽成结构化字段比如订单号、时间范围。抽不到的字段标记为缺失不要瞎猜。第三段是工具路由。根据意图和已有槽位选工具。槽位不全的优先选能补齐信息的工具比如用户只说了手机号那就先调按手机号查订单。第四段是参数校验。这一层必须是纯代码不能靠模型。格式不对直接返回结构化错误告诉模型哪个字段错了、应该是什么格式。第五段是执行与兜底。工具执行加超时、加重试、加熔断。失败信息要写得能让模型看懂别直接抛堆栈。第六段是结果回写与留痕。把执行结果、原始用户输入、工具调用参数一起落库。留痕这件事别嫌麻烦出了问题排查全靠它。public AgentResponse handle(String userInput, SessionCtx ctx) { Intent intent intentRouter.route(userInput); // 规则优先模型兜底 Slots slots slotExtractor.extract(userInput, ctx); // 缺失字段留空不猜 ToolSpec tool toolSelector.select(intent, slots); // 选不到就反问用户 if (tool null) return AgentResponse.askForMore(slots.missing()); ValidationResult vr paramValidator.check(tool, slots); // 纯代码校验 if (!vr.ok()) return AgentResponse.retryWithHint(vr.message()); if (tool.writeOperation()) { // 写操作走审批 return approvalService.submitAndWait(tool, slots, ctx); } ToolResult result toolExecutor.runWithGuard(tool, slots); // 超时/重试/熔断 auditLog.record(userInput, tool, slots, result); // 全链路留痕 return AgentResponse.ok(trimmer.trim(result)); }这段代码里我最想强调的是askForMore这个分支。很多人做 Agent 上来就追求全自动结果模型在信息不全的时候硬猜猜错了还得道歉。其实主动反问是更好的体验——您是要查哪一天的订单这一句话比猜错三轮强得多。4. 关键参数与实测让 Agent 跑得稳的几个数字4.1 超时、重试、熔断的具体取值这些参数我没少调下面这组是跑了几个月比较稳的配置可以直接抄。参数建议值理由单次工具执行超时3 秒查询类接口正常在 200ms 内3 秒足够覆盖慢查询工具重试次数2 次再多收益递减还容易放大下游压力重试退避300ms / 900ms指数退避避开瞬时抖动单轮最大工具调用次数6 次超过说明路由有问题强制中断单次返回最大行数20 行再多模型也读不完还会挤占上下文单字段最大字符数500防止超长文本压垮上下文熔断错误率阈值50%30 秒窗口内错误率超这个数直接熔断熔断恢复探测半开5 秒一次避免熔断后一直不恢复关于重试有个细节只重试幂等的工具。写操作类工具默认不重试失败就返回错误让上层决策。我见过有团队给所有工具统一加重试结果一次下单请求生成了三笔订单查了半天才定位到。还有单轮调用次数上限这个值。为什么是 6因为正常业务场景下一轮对话需要的工具调用很少超过 4 次——查询一次、可能补查一次、写入一次、确认一次。超过 6 次基本都是模型在绕圈子比如反复查同一个订单但参数一直不对。这时候中断比让它继续跑更划算。4.2 评测集怎么建才有效没有评测集的 Agent 改造等于没做测试就上线。但评测集不是越多越好关键是覆盖到位。我一般建 30 条左右的黄金用例分四类。正常路径占一半。覆盖最常见的十几种问法每种问法写两三个变体。比如查订单用户可能说帮我看看 SO2024 那个单子也可能说我的订单到哪了还可能直接甩个订单号过来。边界情况占两成。时间跨度超限、参数格式不对、查询结果为空、返回条数超上限。这类用例最容易暴露工具设计的缺陷。多轮对话占两成。第一轮信息不全第二轮补充或者用户中途改主意。专门测状态管理有没有问题。恶意输入占一成。比如用户说把所有订单都删了测的是护栏有没有生效。这类用例不能省我见过 Agent 被一句话骗着调了批量删除接口的情况。评测指标不用太复杂看两个就够任务完成率最终有没有拿到正确结果和无效调用率调用了但结果没用的比例。第一个低了说明工具或描述有问题第二个高了说明路由或上下文有问题。跑评测一定要固化成脚本可重复执行。每改一次工具描述就跑一遍看指标是涨还是跌。我吃过凭感觉改描述的亏改完自我感觉良好实际准确率掉了十个百分点还是跑评测才发现。实测数据分享一个包含 12 个工具、覆盖订单和用户两个领域的改造项目第一版评测完成率是 61%。主要问题集中在三类工具描述里没说清使用场景导致误调用占一半、返回字段太多导致模型抓错重点占三成、参数格式约束缺失占两成。针对这三类改完之后完成率涨到 89%无效调用率从 34% 降到 9%。这个提升幅度在整个过程中很常见关键是要有数据指导改哪儿。5. 常见问题与排查实录5.1 参数幻觉模型编造了不存在的订单号这是最高频的问题没有之一。用户说我那笔订单有点问题模型直接编了个SO2024031500001234传下去工具返回空它接着编一个来回几次用户已经不耐烦了。排查思路分三层。先看描述里有没有明确要求参数必须来自用户输入这句话得显式写进去模型是听话的但你不说它不知道。再看参数格式约束够不够严订单号加正则编造的号码大概率过不了格式校验能被提前拦下。最后看有没有做存在性预检查拿订单号和当前会话用户绑定的订单列表比对一下不匹配的直接返回未找到该订单请确认订单号别往下走。更彻底的做法是改变交互模式当用户没给标识时不要调用需要标识的工具改用列出最近订单让用户选的工具。这个改动看起来绕实际体验好很多因为它把猜换成了选。5.2 写操作爆炸半径怎么把损失控制在最小写操作出问题的后果比查询严重得多所以我把这块单独拎出来说。控制手段有四个建议全上。范围限制。批量写操作的工具参数里必须有明确的批次上限比如单次最多处理 20 条超了要求拆分。这个上限写进描述同时也写进代码校验双保险。先查后写。执行写操作前先调一次查询工具把要改的数据展示给用户确认。您是要把这 3 笔订单的收货地址改成 XX 吗这一步增加的交互成本很小挡住的错误却很大。试运行模式。复杂写操作提供 dry-run 参数只返回将会修改什么不真正落库。用户确认之后再执行一次真实调用。审批链路。高风险操作金额超过阈值、影响客户数量超过阈值走人工审批Agent 只负责发起和跟踪。这条是最稳的兜底。// 写操作的护栏骨架 AgentTool(name update_order_address, description 修改订单收货地址。仅在用户明确提供了订单号和完整新地址时调用单次仅支持一个订单。, writeOperation true) public WriteResult updateAddress(Param(pattern ^SO\\d{16}$) String orderNo, Param(maxLen 200) String newAddress, Param(desc 试运行为 true 时只返回将要修改的内容) boolean dryRun) { OrderBrief before orderService.queryByNo(orderNo); // 先查 if (before null) return WriteResult.notFound(orderNo); // 不存在直接返回 if (before.status() OrderStatus.SHIPPED) { // 状态机校验 return WriteResult.reject(订单已发货无法修改地址); } if (dryRun) return WriteResult.preview(before, newAddress); // 试运行 return WriteResult.ok(orderService.updateAddress(orderNo, newAddress)); }5.3 多轮对话里的状态丢失与错乱第三个高频问题。用户第一轮说帮我查下订单第二轮说改成新地址第三轮说再看看别的。到第三轮的时候模型已经忘了前面说的是哪个订单因为它看到的历史被压缩了或者工具返回的内容把关键信息挤掉了。解决办法是维护一张显式的槽位表不依赖模型自己记。每个会话有一个结构化的槽位对象存着当前讨论的订单号、用户身份、最近一次查询条件。每轮对话开始前把这张表以简洁的形式注入到上下文里格式固定占不了几个 token但效果立竿见影。{ sessionId: s-20240315-001, userId: u-8821, activeOrder: SO2024031500001234, lastIntent: query_order, pendingConfirm: null, turnCount: 3 }这张表还有个别的好处排查问题时一目了然。用户投诉它答非所问你把这表拉出来一看activeOrder是空的那就知道是槽位没填上不是模型的问题。5.4 常见问题速查表把上面这些和另外几个高频问题整理成表出问题的时候直接对号入座。现象优先排查方向常见根因处理办法模型反复调同一个工具参数校验参数格式不合法被拒模型不知道原因错误信息里写清格式要求答非所问、答上一轮的问题槽位管理历史被压缩关键实体丢失维护显式槽位表并注入工具选错工具描述多个工具描述边界模糊描述里补何时不要用返回内容超长结果裁剪直接序列化实体类改白名单返回加行数上限编造数据参数约束缺正则、缺存在性校验加格式约束 预检查调用成本暴涨上下文预算工具定义和历史无节制增长精简工具数历史做摘要响应慢串行调用多个独立查询串行执行无依赖的工具调用并行化最后一条我想多说一句。工具调用的并行化收益很明显一轮里如果有三个互不依赖的查询串行要 900ms并行只要 300ms 出头。但要注意别乱并行——有依赖关系的调用必须串行比如先查用户再查订单并行会导致后一个拿不到前一个的结果。6. 迁移路径一个 Java 程序员的 90 天行动清单6.1 能力盘点哪些能直接复用哪些要从零补先说好消息你这些年积累的东西大半没白学。直接复用的领域建模能力这是最值钱的Agent 时代更值钱因为工具设计本质就是领域建模、SQL 与数据库设计、事务与并发控制、接口设计规范、日志与监控体系。这些是地基换个上层应用照样用。需要强化的把业务能力拆成原子工具的抽象能力、结构化描述写作写工具描述本质上是写文档但不能有歧义、评测思维从跑通就行变成用数据说话、护栏设计把安全边界往前挪。需要新学的上下文预算管理、工具编排与路由、检索增强的基本原理、模型输出的不确定性处理。注意我说的都是原理和工程不是某个具体产品的用法——具体产品三个月换一茬原理能用五年。给个自评表每个维度 1 到 5 分低于 3 分的优先补能力维度权重自评要点领域建模与工具抽象高能否把业务流程拆成独立、可组合的能力单元结构化描述写作高写的工具描述是否无歧义、有无何时不用护栏与安全设计高是否习惯性考虑幂等、限流、审批评测与数据分析中能否设计评测集并用指标驱动迭代上下文与成本控制中是否清楚每一轮对话的 token 花在哪传统后端基本功高事务、并发、索引、缓存别丢6.2 90 天分阶段计划我把这个计划给过几个同事反馈是节奏还算合理不需要脱产每天抽一两个小时就够。第 1-2 周跑通一个只读场景。选一个你自己最熟的查询需求把它改造成一个工具接上一个对话入口能跑通就行。目标不是做好是建立手感——你会很快发现原来模型是这么理解我的描述的这个体感比看十篇文章有用。第 3-4 周工具化改造一个小模块。挑一个包含五到八个接口的模块完整走一遍盘点、收敛、裁剪、加护栏的流程。这一步的重点是把结果裁剪和参数约束做扎实做完之后你会对什么叫有界有具体认知。第 5-6 周建评测集。准备 30 条用例写个跑批脚本把完成率和无效调用率跑出来。这一步是最枯燥的但也是分水岭——做完这一步的人和不做的人后面差距会越拉越大。第 7-8 周接入一个写操作。选风险最低的写场景比如修改备注这种可逆的。把幂等、先查后写、试运行、审批这四道护栏全走一遍。这一步会逼你想清楚错了怎么办。第 9-10 周可观测性补齐。把工具调用日志、耗时、错误率、成本都埋上点做个简单的看板。没有这个后面所有优化都是盲调。第 11-12 周沉淀与分享。把踩过的坑、参数配置、模板代码整理成团队文档做一次内部分享。讲一遍是最好的复习而且能逼自己把模糊的地方想清楚。6.3 该焦虑的和不该焦虑的说了这么多最后聊点实在的。不该焦虑的Java 会不会消失。不会。企业系统的复杂度不会因为多了个 Agent 就降低反而会上升——你要处理的是工具编排、幂等、审计、成本这些全是后端的活。我甚至觉得Agent 落地做得好的团队后端功底都不差因为那些看似AI 问题的故障最后八成定位到数据库索引或者事务边界上。该焦虑的只会照着模板写 CRUD且不愿意把视角从实现抬到设计。这部分工作确实在快速消失而且消失得比想象中快。我见过一个团队去年还需要三个人维护的后台管理模块今年一个人加一套工具就撑住了省下来的两个人转去做数据治理和流程梳理。转得动的留下了转不动的就比较被动。一个反直觉的观察Agent 做得越深入对把话说清楚的能力要求越高。工具描述写得含糊、字段含义定义不清、异常处理约定不明这些问题在人工开发时代会被同事的默契兜住在 Agent 时代会直接变成故障。所以那些平时就喜欢把接口文档写明白、把命名抠清楚的人迁移起来反而最顺。我个人在实际操作中的体会是这件事没有想象中那么需要从头学起。你把一个 Service 方法改造成工具的过程和你当年把一个巨型 Servlet 拆成三层架构的过程本质上是同一件事——都是识别边界、定义契约、划清职责。区别只是这次的调用方从同事写的代码变成了一个聪明但会犯错的模型。想明白这一点手上那些看似过时的经验反而成了最硬的底牌。最后分享一个小技巧成本几乎为零但收益很大给你改造的每个工具都写一句如果我错了最坏会怎样。这句话逼着你把爆炸半径想清楚写不出来就说明这个工具还不该放出去。我给团队定的规矩是这句话写不出来的工具一律不允许接入对话入口。这条规矩挡住的问题比任何技术方案都多。
