Agent-Native：为AI代理重构软件的设计与实践

我一直觉得软件行业有个很有意思的规律每一次交互主体的变化都会把一批旧系统变成“遗产”。最早是人对着命令行打字后来人对着图形界面点鼠标再后来程序通过API调用程序。而2024年下半年开始一个新的交互主体正在批量入场它既不读界面也不严格按照你文档里的字段约束来调用API它就是AI代理。这个阶段冒出来的关键词就是我最近一直在琢磨的“agent-native”。所谓agent-native直白讲就是“原生为智能代理设计”的软件形态。过去我们做产品默认使用者是坐在屏幕前的人所以要设计按钮、菜单、提示文案后来有了开放平台默认使用者是开发者所以要有文档、SDK和鉴权而agent-native要求更进一步——把AI代理当作和人类用户同等重要的一等使用者来设计。这篇文章不打算绕概念我想结合自己参与过的几次系统改造和从零搭建的经验把三件事聊透agent-native到底解决了什么问题、一个agent-native系统内部应该长什么样、以及真正把它落到业务里时那些没人提醒你的坑。1. agent-native要解决的是“软件不再默认用户是人”1.1 传统软件默认的“用户模型”正在失效传统软件从设计之初就默认使用者是一个坐在屏幕前的人。人有什么特点人会看版面布局会注意到红色警告会在弹窗里犹豫要不要点确定。人操作软件是串行的一个动作完成看清楚结果再做下一个动作。人还会主动纠正自己点错了就撤销理解错了就换个入口重来。AI代理完全没有这些习惯。代理的工作方式是理解目标→拆解成步骤→按接口文档组装请求→读取返回结果→根据结果更新计划→继续下一步。它不“看”屏幕只“读”结构化数据它不会从菜单浏览中找到“这里还有一个入口”只能从你给它的工具清单里选它也不会因为“感觉不太对”就停下来除非你的数据结构里明确告诉它“这个操作有风险”。我在一次老系统改造中特别清楚地感受到这一点。我们有一套内部CRM接口文档写得很规范但全局梳理后发现至少二十多个接口都和“创建订单”相关分别处理普通销售、内部调拨、赠品核销等场景。人用图形界面时菜单路径已经帮你把场景约定了进哪个页面就代表走哪个流程。但代理面对二十多个长得类似的接口时只能靠接口描述里的几个字去猜。我当时花了大量时间教代理“什么场景该选哪个接口”后来想明白这不是代理笨而是这套系统原本就不是为代理设计的。被传统API束缚的agent本质上是在把“程序接口”当成“人机界面”来硬用。1.2 代理眼中的应用和人类眼中的应用完全是两个东西如果做过大模型函数调用你会很直观地理解代理的视角。模型看到的每个能力就是一个函数结构函数名、描述、参数结构、返回类型。它看不到“这个页面上有个提示框写了退货需要扣除手续费”它只能看到你给的函数描述里有没有写这句话。agent-native的第一性原理就是把“人在界面上能感知到的决策上下文”全部显式地、结构化地移交给代理。人看到“商品下架”按钮旁边有一行灰色小字“该操作将关闭所有渠道在售状态且不可逆”人会自然地谨慎。代理不会“自然”谨慎它只会根据描述判断该不该用。如果你在API描述里只写了“下架商品”那代理就真的只知道它能下架商品。所以agent-native不是简单多开放几个API的问题也不是在文档里多写两句话的问题而是要把动作的前置条件、副作用、失败后果、替代方案都变成机器可读的元数据。可以粗暴理解成把“用户手册”改写成“代理决策手册”。传统系统的隐含前提agent-native系统的显式要求用户会阅读界面提示代理需要结构化风险等级与副作用说明用户靠记忆和经验选入口代理需要意图到工具的明确映射用户能忍受模糊反馈代理需要机器可解析的明确返回结构用户会在操作前自我确认代理需要权限规则和审批节点来约束用户可人工回滚代理需要幂等键和逆向操作能力这也是为什么很多团队尝试“把一个AI代理接进旧系统”会失败。他们以为代理的问题是“模型不够聪明”实际问题是软件根本没给代理留下“聪明发挥”的空间。2. 一个agent-native系统至少要有的五块拼图在我经手的项目里真正称得上agent-native的系统很少是一两个接口的改进而是围绕“代理作为用户”这个前提构建了完整的五个模块。缺了任何一块后面都会以各种姿势出问题。2.1 工具描述层让代理不靠猜工具描述是代理的“说明书”它直接决定了代理什么时候会调用这个工具、调用完怎么理解结果。很多接口失败根源在描述不充分。我举一个特别常见的例子邮件发送接口。如果描述只写“发送邮件”代理会把它用在各种场合包括一些不该用的地方。但如果描述写成“发送邮件此操作会向外部真实地址发送不可撤回的邮件仅当用户明确要求联系对方时使用”代理的调用准确率会明显提升因为模型在规划时会把这个“风险提示”纳入决策权重。参数枚举也要写全。某个状态字段如果只有“草稿”和“已提交”两种合法值就一定要在工具定义里枚举出来并且说明两种状态的差别。代理不是不认真它是真的会去猜“已提交”和“已发布”是不是一回事。一个动作一个工具这个原则也很重要不要为了减少工具数量而把多个动作揉进一个接口参数一旦互相依赖代理的规划成功率会立刻下降。2.2 状态管理层让代理不再对着窗口挠头代理经常被人吐槽“没记性”这不算冤枉。因为模型本身是无状态的每次调用都是独立计算所谓的“记忆”全靠外部系统把历史拼进上下文。agent-native系统应该主动承担一部分状态管理责任。我的习惯是把状态拆成三层会话上下文记录本次交互的目标和最近几轮动作任务上下文记录当前任务已经执行到哪一步、中途产出了什么中间数据持久业务身份记录用户或组织的偏好、权限边界和历史模式。系统侧要提供显式的状态存取接口比如get_task_state和save_task_state让代理在步骤之间保存和恢复进度而不是把所有历史一股脑塞进提示词。这个设计能节省大量token更重要的是能降低模型迷失在长上下文里的概率。代理只需关心当前增量不需要每次从头回忆。2.3 权限与审批让代理拥有“恰到好处”的权力权力过大的代理是事故源权力过小的代理是废柴。我在项目里比较推荐的做法是参考OAuth的scope思路但把粒度再往下钻一层设计成“动作资源条件”三级结构。举一个真实例子。一个客服场景的代理权限策略可以写成这样动作资源范围条件是否需要审批读取订单全部订单无否修改订单备注全部订单无否修改订单金额订单金额小于10000元仅限未发货订单否修改订单金额订单金额大于等于10000元无是需客户主管审批发起退款全部订单仅限已支付且未发货是需财务审批这种策略下代理拥有比人更细分的操作空间。它不需要每次操作都问人高风险动作又被制度性拦截住了。权限系统还要注意“可解释性”每次授权记录都要能回答三个问题谁批的、基于什么条件批的、当时代理声称的意图是什么。2.4 可观测与反馈层每一笔行动都有回溯能力代理的操作路径是多步决策一旦出错复盘难度远高于传统程序。因为错误往往不是一个接口调用失败而是好几步组合起来产生了意外结果。所以agent-native系统从第一天就要定义标准事件结构。我习惯把事件字段定义为actor、action、resource、intent、result、cost、latency、external_outcome。actor是哪个代理或哪个用户intent是代理自己记录的本意result是操作结果external_outcome是操作对外部系统产生的实际影响。每个事件都带唯一的trace_id串联起整个决策链这样才能在出问题时回放“代理到底怎么想到这一步的”。反馈层是闭环的另一半。代理执行完动作后系统要把结果信号返回给它比如“工单已关闭客户满意度4星”“订单已发货但物流号异常”。这些信号会成为下一次决策的输入让代理自动调整行为策略。没有反馈层的agent系统就像没有仪表盘的司机开得越快越危险。2.5 意图路由层从“一个代理包打天下”到“多代理协作”很多团队一上来就想做一个“全能代理”让它处理所有业务。结果往往是上下文塞爆、工具数量失控、指令互相干扰。agent-native的一个常见进阶形态是意图路由入口网关先对用户的请求做意图分类再分发给对应领域的专业代理跨领域任务再交给编排器串成工作流。这个路由层需要定义清晰的意图模型至少要包含意图名称、置信度、可选代理列表、风险等级。我在项目中还会加一个“回退规则”当意图识别置信度低于阈值时宁可交给人工处理也不要让代理硬做。一开始听起来像少了智能化实际落地时你会发现这是系统不出大事故的关键兜底。3. 把存量系统往agent-native改造我按这个顺序落地老系统改造成agent-native最忌讳上来就推倒重来。我自己验证过一条比较稳妥的路径按顺序做投入产出比会高很多。3.1 第一步圈出代理真正会触碰的动作而不是全部功能没有哪个系统需要一次性把所有接口改造完。我建议先做一次盘点按三个优先级筛选高频查询类操作排第一因为查询量最大、风险最低适合练手高频小写操作排第二比如更新状态、添加备注高风险写操作排第三比如退款、删除、批量改价这类操作先不做完全自动化只做“可读化”和“审批化”。你这个系统里可能有三四十个接口但代理日常用得最多的可能只有六七个。把这六七个接口做到代理友好比把三十个接口全部加一层包装要有效得多。3.2 第二步给关键接口补一份“决策上下文”有个成本很低的技巧不用急着设计一堆agent-native接口。先把现有接口的返回结构里加一个optional_context字段把人在界面上才看得到的约束条件结构化吐给代理。举个例子。某个“查询客户列表”接口原来只返回客户数据和订单数量。改造后额外返回当前用户的可见数据范围、可执行的操作列表、每个操作是否需要审批。代理拿到这些信息就不用靠猜去决定下一步是“直接改客户等级”还是“先提交审批申请”了。这个字段可以理解为“当前状态下下一步可选动作”概念参考了HATEOAS但比那套理论更实际不要求接口把所有操作都嵌到返回里只要求把“与当前状态相关的动作和条件”说清楚。3.3 第三步先跑影子模式再考虑开放写权限影子模式意思是把真实的请求流量复制一份给代理处理但代理执行的结果不真正落库只和人工操作做对比。这相当于给代理一个“模拟考场”用真实数据考验它的计划能力又不承担真实风险。我习惯在影子模式阶段盯三个指标意图理解准确率指代理是否听懂了用户到底要什么计划路径准确率指代理选的动作序列是否合理缺上下文追问次数指代理因信息不足反复询问的频次。这三个指标稳定不下来不要开放写权限。就算开放了也要上一批护栏幂等键防重复提交、频率限制防代理风暴、危险操作强制二次确认。3.4 第四步建立动作后的反馈闭环这是最容易被人跳过的一步。不少团队把接口开放给AI就宣布“改造完成”结果代理一直在重复同样的错误因为没有任何机制告诉它“你做错了”。我建议在改造的第二周就给人侧加几个反馈入口采纳、撤销、修正。人可以对代理的每个动作进行标注标注结果全部回流到策略服务形成“代理行动→结果评估→策略调整”的小闭环。不用搞复杂的强化学习就是从上下文层面让代理在下一轮决策时知道“这类操作上次被用户撤销了要换一种方式”。没有这个闭环agent-native永远只是单向的“自动执行”而不是“自适应执行”。4. 落地时最容易被忽视的边界权限、记忆与状态漂移前几节讲的都是从零搭建设计而这一节我想专门聊边界问题。因为我在多个项目里踩过同样的坑基本都是这三个方向。4.1 权限不是越大越好也不是越小越安全权限给得太粗代理一晚上能产生大量异常单据权限给得太细代理连正常的活都干不了最终被人嫌麻烦绕过系统手写脚本。理想状态是“可解释策略”前面表格里的“动作资源条件”就是这一思路的落地。还有一个绕不开的问题责任归属。代理捅了篓子谁负责我的经验是落到“最后一个人工审批人”和“系统所有者”身上。每一类高风险动作都对应一个明确的人代理只是建议者、执行者和记录者决策责任永远有人承担。这不是为了甩锅而是为了出问题时能快速定位决策链也让审批人不会因为“代理做的而我只是点了同意”就掉以轻心。4.2 记忆要分层设计不能一股脑喂给大模型有些系统把用户过去一年的所有行为都塞进上下文美其名曰“让代理更懂用户”结果token费用爆炸模型还被海量无关信息干扰。agent-native的记忆应该由平台统一管理而不是由提示词拼装。分层设计是这样的短期记忆只保留当前会话的目标和最近几步动作工作记忆保存当前任务中的数据上下文长期记忆保存用户偏好、组织规则、历史偏好总结。我在代码里会给每个会话配一个MemoryService代理显式调用读取和保存方法而不是把记忆揉进每一轮对话。长期记忆尤其要注意遗忘权用户要求删除时就必须真的清掉不要在向量库里留镜像备份。这个既是对用户隐私的尊重也是系统上线前必须过的合规关。4.3 状态漂移是代理故障的主要来源之一代理决定“接下来调用A接口”的时候是根据它手里当时拿到的状态。但从做出决定到真正执行中间可能隔了几秒钟甚至几分钟业务状态早被别人改了。这就是状态漂移。传统程序是单线程资产状态不会凭空变化但代理面对的是多并发、多系统联动的环境。解决办法是给关键业务实体加版本号。代理在每一步执行前先校验版本号发现不一致就重新拉取最新状态并在原计划基础上更新。我管这个叫“执行前状态核对”也是在多次事故后才养成的习惯。代理计划得再漂亮状态过期了行动就是空中楼阁。5. 几个典型场景里的agent-native价值到底落在哪里5.1 客服工单从“写回复”变成“真正解决问题”传统客服系统的核心是工单流转人看工单、查业务数据、写回复、点流转。agent-native改造后的客服系统会把客户意图推断、可选处理动作、知识库引用这些本来靠人脑做的事变成结构化元数据输出给代理。代理生成的不再是回复草稿而是包含操作链接、状态流转建议、所需审批动作的完整处理方案。这类项目最明显的收益不是时间减少多少而是客服上手成本被压得很低。新人不需要背几十个业务规则代理会在每一步把“为何这么做、下一步该问什么”摆出来等于把一个老师傅的经验固化成系统能力。5.2 数据分析从“写SQL取数”变成“回答问题”数据分析代理最大的障碍不是生成SQL的能力而是数据口径混乱。同一个“复购率”业务部门说一套财务部门说一套代理根本不知道听谁的。agent-native化的BI系统会在每个数据集之上加一层语义层把指标的公式定义、统计口径、允许下钻的维度、关联数据源等全部标注清楚。代理基于这层语义层工作生成查询时不再靠猜“这个指标要不要排除赠品订单”因为语义层已经告诉它了。这个方向我尤其看好因为语法错误只是一时的痛语义误解才是分析结果长期被质疑的根因。5.3 后台运营从“流程自动化”变成“异常监管”早些年大家用RPA做后台自动化规则写死流程一变就要重录一遍。agent-native的实践是每个操作变成可组合的代理技能比如“创建供应商档案”“发起付款申请”“获取审批链”。代理根据实际任务动态编排这些技能而不是执行一条写死的流程。这类场景里人从执行者变成监管者只需要处理代理标记出来的异常队列。我在项目里看到的真实变化是基层运营的注意力从“怎么把事情做完”转移到“怎么把规则定对”这在我看来是更大的生产力解放。6. 把agent-native当成产品理念而不是技术口号最后说几句实在的。我见过不少技术团队把agent-native理解成“给接口写几段中文描述”或者“接一个开源智能体框架”这是两码事。真正的agent-native改造是在改变软件和用户之间的权力关系过去是人适应软件软件给出路径人跟着走现在是软件适应代理把判断所需的信息全部交给代理让它自己找路径。这个改变会传导到岗位分工。产品经理要开始定义“代理可见的行为边界”把权限和意图写成产品需求测试工程师要从功能测试扩展到代理交互测试甚至模拟极端意图看系统会不会防御架构师则要把接口描述、权限表达式、事件Schema这些“软资产”当成一等交付物来看待它们的质量直接决定整个系统的智能化上限。如果你刚开始接触agent-native我的建议是别试图一步到位造一个全知全能的超级代理。先从最常用的那个内部系统开始挑一个高频接口在返回里补一段可选动作和限制说明让代理在影子模式下跑一周看看问询次数和报错率会不会显著下降。我实践下来的结果往往比想象中明显因为代理真正缺的从来不是聪明而是可理解的环境。