2025年初我接手了一个内部项目的架构改造也是我第一次正式把“agent-native”这个词写进技术方案。项目本身不复杂——一个财务知识助手最初的做法也很标准知识库RAG 大模型问答用户问什么系统从文档里检索出答案再附上原文链接。做了两个月效果尚可领导也认可。但接下来需求方提了一个需求直接把项目带向了完全不同的方向他们不满足了“能不能让它别只回答而是直接帮我们把流程走了”比如员工来问报销标准它回答完之后能不能顺手发起一个报销申请填好摘要、金额、附件清单提交到审批流当时我下意识觉得没什么难度——不就是给模型多接几个工具吗一个create_expense_request一个query_approval_status再加一个权限检查完事。但真正动手之后我发现这个“简单需求”把我逼进了一个很深的问题我们现有的系统从数据模型到接口设计从错误处理到权限体系完全不是为“让一个机器自主操作”准备的。这个问题的答案最终指向了一个这两年被反复提及、但很多人包括当时的我并没有真正想透的词agent-native。这篇文章不打算写一份概念综述而是把我从架构评审、代码落地、上线排查中得到的真实经验梳理出来。适合正在做AI Agent应用、团队里讨论过“要不要为Agent重构系统”、或者被“让大模型调用API”看似简单实则崩溃搞得头疼的人参考。我会先讲清楚agent-native到底是什么、它和传统架构差在哪再给出一套我验证过的最小落地路径最后聊聊评估和可观测性这些“上线后才发现要命”的事。1. agent-native到底在解决什么问题一个真实需求引发的重构1.1 “能自己干活”和“会说话”是两套完全不同的系统我最初的产品形态是人机问答用户输入问题系统检索文档生成答句。这个形态下系统本质上是一套“信息检索 文本生成”的管道数据和接口只要“能被人理解”就够。但“帮我发起报销申请”这个需求一出来情况变了。这句看似简单的指令在大模型视角下需要拆解成至少五步从对话上下文或用户信息里确定报销人身份向费用系统查询可用的报销科目理解“摘要”和“金额”的字段约束调用创建申请的工具带上刚才查到的信息把系统生成的单号、审批链路回传给用户如果第二步的数据不完整比如员工说不清属于哪个科目还要主动追问。这段拆解过程让我意识到真正的难点不在“让模型会说话”而在“让系统能被模型操作”。一个能被自主执行程序操作的系统和一个人通过屏幕点击操作的系统底层设计哲学完全不同。人类操作界面可以容忍模糊、隐含、跳步和临场判断但机器执行器每一步都需要精确的上下文、明确的契约和清晰的前置条件。这正是agent-native要讨论的核心也是所有“让大模型干活”类项目绕不开的分水岭。1.2 我最初的方案给大模型包装几个API然后翻车我的第一版设计非常简单很多团队都会这样起步把内部系统里现成的REST API直接包装成Function Calling里的tools数组每个tool配一段描述让模型选择调用。上线后的表现可以用四个字概括频繁翻车。我把当时踩的坑整理成了一张表现象根因模型把status参数传成“OK”而接口期望的是0接口的枚举值没有语义描述模型不知道0代表什么模型调用了一个查询接口后下一个动作直接调用“删除部门”接口工具描述里没写副作用模型把高危操作当成普通步骤报销申请重复提交了三次工具不是幂等的失败重试导致重复创建对话进行到一半进程重启整个任务状态丢失状态全部放在内存里没有持久化设计这些坑让我意识到一个问题问题不出在模型而在我给它准备的这套“工具操作系统”本身。接口设计、数据描述、状态管理和权限模型全都假设坐在屏幕前的是一个有常识、有上下文、会谨慎操作的人但当操作者变成一个大模型时它没有这些隐含常识它只依赖你在schema里明确写的每一个字。你忘写的就等于不存在。1.3 agent-native不是新名词而是一组设计上的硬约束那agent-native到底是什么我的理解是它指的是一个应用系统把“自主智能体”当作头等公民来设计——数据、接口、权限、状态、可观测性都必须围绕“机器主动执行任务”这一个前提来构建而不是先按人类操作习惯建一套系统再事后给模型加一个“API外挂”。这个思路和cloud-native很像。cloud-native不是说“把应用放进容器里就算完”而是要按云环境的假设重新设计应用——弹性伸缩、不可变基础设施、故障自愈。agent-native同样不是“给现有系统加个Function Calling接口”就完了它要求你按“模型会自主执行、会出错、会需要恢复”这个前提重新设计每一个环节。这个定义很长且抽象后面几个章节我会分别拆开讲。先记住一个核心判断判断一个系统够不够agent-native不看你用了什么Agent框架而看它面对“模型决策失误后如何恢复”“工具副作用如何控制”“状态在多步骤执行中如何保持”这三个问题时是有一套预先设计好的机制还是靠运气。2. 传统应用架构为什么“长不出”Agent三层核心矛盾想理解agent-native对架构的改造力度最好的方法不是直接看它长什么样而是先看传统架构与Agent需求之间的矛盾点。2.1 数据模型矛盾人类可读不等于机器可操作传统业务系统里的数据绝大多数是为“人通过界面阅读”设计的。一张订单表里status字段存的是0、1、2含义写在线下wiki里业务规则“超过5000元的报销单需要总监审批”写在代码的if分支里字段之间的关联关系隐含在开发者的脑子里。人看到这些没问题因为人可以去问、去查、去猜上下文但模型只能读到你在prompt和tool schema里明确写出的东西。如果你的接口返回{status: 2}模型不知道2代表“已拒绝”它可能就会顺着流程继续执行下一步操作直到在某个环节撞出错误。所以在agent-native架构里数据层首先要做“语义显式化”。我后来在实践中把这件事拆成了三项工作给所有被Agent接触的实体建立统一的描述信息字段枚举值必须带解释例如status: 1 表示待审批2 表示已通过3 表示已拒绝把业务规则从代码注释里“挖”出来变成可以被模型检索或调用的规则接口例如“报销金额超过5000元必须走总监审批”要能被Agent在提交前查得到数据结构本身要更“平坦、自解释”嵌套过深的对象模型对模型不友好它很容易在多层JSON里迷失。这三件事听起来琐碎但我可以负责任地说agent-native项目里至少一半的“模型不听话”问题根源都在这里不是模型笨是你喂给它的数据本身语焉不详。2.2 接口设计矛盾确定性API遇到开放性意图传统API的设计目标是“确定性”。接口路径、入参、出参、错误码都是固定契约调用方只要按文档调用即可调用方是否该调用这个接口通常由前置业务流程判断。但Agent不一样。Agent的核心能力恰恰是“自主判断该调用哪个工具”。它拿着一个开放性意图在几十个工具描述里做选择。这个差异带来了两个直接影响。第一个影响是工具的描述质量成了系统性能的一部分。我见过很多团队把描述写成“查询订单信息接口”五个字然后抱怨模型总是选错工具。实际上模型没有人类的模糊理解能力它的选择完全基于schema里那段description文本的质量。你需要描述的不只是“接口做什么”还包括“什么时候用、什么时候不用、参数限制、副作用提示”。第二个影响是接口的粒度需要重新拆。传统REST接口的粒度是为了页面操作方便设计的一个“更新订单基本信息”接口可能同时改了地址、联系人、备注。对页面来说这是好事但对模型来说一次调用改了三个字段副作用太大出错后很难定位。agent-native的做法往往是把大接口拆成更小、更聚焦的工具并给每个工具标注清楚影响面比如“更新地址”“更新联系人”“更新备注”三个工具。2.3 状态管理矛盾无状态服务遇上有状态推理传统微服务架构里我们拼命追求无状态请求进来、处理、返回状态放到Redis或数据库里应用本身不保存任何业务状态这样才好水平扩容。但Agent的执行过程天然是有状态的——它要经历“规划、调用工具、观察结果、再规划”的循环循环之间不仅需要记住上下文还需要记住“我执行到哪一步了”。没有状态管理你遇到的第一个问题就是重复操作。一个报销申请任务触发后模型第一步创建了申请单第二步查审批链路时超时了重试逻辑把整个任务重跑结果又创建了一张一模一样的申请单。这个问题我后来在文章第4部分还会专门展开这里先给结论agent-native架构必须引入“任务级状态模型”把Agent运行的上下文、中间结果、工具调用历史、检查点全部落库并且在每个工具调用上设计幂等机制。状态管理还要考虑多Agent协作的情况。一个Agent查询、一个Agent执行、一个Agent审核它们如果共享一份业务数据就需要引入并发控制和组织边界不然很容易出现“A Agent刚承诺了客户价格B Agent已经按旧价格生成了订单”这类数据一致性问题。这一步不能靠模型自律必须在数据层约法三章。3. 我实践的agent-native四层架构从工具契约到治理兜底概念拆完下面给出一套我在实际项目中验证过的落地框架。我把它分成四层工具契约层、语义数据层、执行与自省层、治理层。这四层不是某个框架自带的功能而是你在设计任何agent-native系统时都需要自己回答的问题。3.1 工具契约层模型看得懂、调得对的前提工具契约层是所有工作的地基。你提供给模型的一切“能力”最终都会变成一组JSON schema模型在这个schema的约束下做选择。我的血泪经验是schema设计得越认真后面踩的坑越少。一个好用的tool schema除了常规的name、description、parameters之外还需要写清这几件事作用边界明确写“本工具只负责XX不处理XX”避免模型把一个工具当万能接口用副作用声明如果工具会修改数据、发送消息、扣减余额必须在描述里加一句加粗的警告性文字例如“注意本操作将向客户发送短信不可撤销”参数约束的自然语言描述除了JSON Schema的type、enum这些结构约束还要在description里解释业务语义。比如amount字段type是number是不够的要写明“单位元精确到分必须大于0”前置条件如果这个工具必须在某个流程步骤之后才能调用描述里要写明比如“仅在已确认客户身份后调用”。下面是一个我改写过多次的示例。以查询订单工具为例这是最普通的只读工具但看起来很简单的东西也值得认真写# tools.py from pydantic import BaseModel, Field class QueryOrderParams(BaseModel): order_id: str Field( description订单编号格式为 ORD- 开头的10位字符串示例ORD-2025-0012 ) with_items: bool Field( defaultFalse, description是否返回订单明细行。若用户询问商品明细请设为True。 )关键的描述不只是“查询订单”而是把调用场景、参数格式、边界条件都给了模型。如果你的工具描述需要靠口头解释才能让人类同事听懂那模型大概率也听不明白。3.2 语义数据层从“文档堆”到“可操作知识”第二层是数据。agent-native系统里数据要同时满足两个需求能被检索到retrieval能被理解并操作operation。先讲被检索到。我们做知识问答时习惯用RAG但传统RAG最大的问题是“切了就丢上下文”一篇两万字的文档切成二十个五百字的切片每个切片孤零零的模型只知道它读了这一段不知道它属于哪一章、服务于哪个主题、对应用户的什么权限。agent-native的做法是给每个切片补充足够强大的元数据来源文档、章节层级、实体关联、业务领域、可用操作列表。这样当Agent检索到一条知识时它也能同时知道“这段知识对应哪个业务实体、可以触发哪些操作”。再讲被操作。很多时候Agent需要的不只是“读知识”而是“按规则办事”。报销规则写到文档里和变成可查询的规则服务效果差别巨大——文档里的规则模型要靠检索检索不到就乱编规则服务里模型可以在执行前主动查询校验得到确定性答案。所以我强烈建议凡是高风险、高权重业务规则尽量从文档搬到结构化规则服务而不要只依赖RAG。语义数据层有一个容易忽略的细节权限语义。传统权限控制用户能否看到一条数据agent-native里还要增加“这个Agent以谁的身份、可以对这个数据做什么操作”的语义。同一个订单普通客服Agent只能读财务Agent能改账期把这种差异显式写进数据访问层而不是靠代码if-else到处散落。3.3 执行与自省层让Agent学会“说计划、看结果、改动作”第三层是执行引擎。很多人以为Agent执行层必须用某种重型编排框架其实核心机制不算复杂一句话概括就是让模型先说出计划然后一步步执行每一步之后观察结果再决定是继续、修正还是终止。说得更具体一点我在项目里实际用的是一个简化版的ReAct循环包含三个强制环节计划环节Plan模型在每轮任务开始时输出一个简短计划列出准备调用哪些工具、顺序如何。这一步的作用不只是让模型自己理清思路也是让后续的审计日志有据可查。执行环节Act根据计划调用工具但在真正调用之前系统会做一次“契约校验”——检查参数是否符合schema约束、是否符合权限、是否已满足前置条件。这一步看起来多余但实测能拦截掉大量模型犯的“低级错误”。观察与自省环节Observe→Reflect拿到工具结果后模型要判断结果是否符合预期。如果结果异常不是无脑重试而是先分析原因比如“查询结果为空可能是因为日期格式不对下一步改用昨天日期再查一次”。自省环节最容易被人忽略但它恰恰是Agent和普通脚本的区别。脚本执行失败只会抛异常一个设计良好的Agent会在失败后分析原因、调整策略、重新尝试并且在自己“尝试了三次仍然失败”时主动停下请求人工介入。很多团队的Agent“看起来像脚本”或“看起来像疯跑的车”差别就在这里。状态持久化是这个层的另一个关键。理想情况下每一步执行结果都应该以事件的形式落库形成一条完整的“任务轨迹”。这样无论进程如何重启、任务如何中断都能从最近的检查点恢复。这里的事件日志不只是调试工具它本身就是Agent的记忆和审计凭证。3.4 治理层权限、审计、人工介入一个都不能少最后这层是“上线以后才意识到有多重要”的部分。Agent自主执行意味着它会在没有人看着的情况下操作真实系统所以治理机制必须前置设计不能等出了事故再补。我理解的治理层包含四件事权限精细化给Agent的权限边界应该比给人更严格。人可以在系统里逛一圈看看数据但Agent的每次读操作都涉及算力和推理成本每次写操作都涉及业务影响所以必须是白名单制明确Agent能够访问哪些数据、调用哪些工具未在白名单内的一律拒绝。高危操作熔断在工具调用前设置“影响等级”。等级低的如查询、生成草稿可以自主执行等级高的如删除、转账、群发通知必须进入“等待人工确认”状态。这个判断可以在编排层预先做好不必只依赖模型自觉。全量审计记录每一个Agent任务从创建到结束的完整轨迹包括模型每一次思考内容、工具调用入参和出参、异常情况、人工确认动作。这不仅是排查问题的依据也是后续做评测和优化的数据基础。失败退出策略给每次任务设置最大轮次和最大连续失败次数。达到阈值后强制切换到“需人工介入”状态而不是让模型无限循环地重试下去。我见过不少团队Agent demo跑得很顺一上生产就出事故事故原因基本都能归到这四类里权限太大、没有熔断、没有审计、失败后无限重试。别把这些当额外工作量它们就是agent-native系统本身的组成部分。4. 一份可复用的agent-native最小系统搭建记录讲完理论这一节给一份我实际跑通过的最小系统搭建记录。不追求大而全重点是展示“够用”的实现长什么样以及我在实测中踩过的坑。4.1 选型逻辑框架、模型、存储怎么定我的选型原则是“能少依赖就少依赖能自控就自控”。Agent框架迭代太快一个大而全的框架可能你还没学完社区已经换方向了所以核心执行循环我倾向自己维护一个精简版本只把那些确实复杂的能力比如复杂状态机、并行编排交给专门库处理。整套系统的核心组件我选了这些执行框架自研一个几十行的ReAct循环配合状态事件日志。理由核心逻辑足够简单出了问题我能快速定位不依赖框架版本行为。模型支持函数调用/工具调用能力的主流模型具体选择取决于团队对数据私密性和成本的要求。评测时重要的不是跑分而是“在你自己工具集上的任务完成率”。接口层FastAPI底层自包含、易部署。工具全部以普通Python函数实现通过统一注册机制暴露给模型。数据层业务数据继续放PostgreSQL向量检索用pgvector。理由少引入一套独立向量库运维代价小和业务数据放一起还方便做元数据关联查询。可观测自建事件日志 结构化trace输出后续可对接Langfuse这类开源工具做可视化。这套选型没有追求新潮但胜在可控。真正的agent-native项目里选型的核心不是“谁的Agent跑得快”而是“我能不能在出问题时快速把它看穿”。4.2 核心实现一个精简的Agent执行循环我把自己写的执行循环逻辑拆成三个部分。先看工具定义再看循环主体最后是状态落库。工具定义是用Pydantic加描述文本组织的前面示例已经给过。真正重要的是统一注册# registry.py TOOL_REGISTRY {} def register_tool(schema_func): TOOL_REGISTRY[schema_func.__name__] { func: schema_func, schema: build_json_schema(schema_func) } return schema_func register_tool def query_order(params: QueryOrderParams): 查询订单信息。只读操作不改变任何数据。 ...执行循环的伪代码如下每个环节都打点日志def run_agent_task(initial_prompt: str): task_id create_task_record(initial_prompt) messages [{role: user, content: initial_prompt}] for step in range(MAX_STEPS): # 1. 让模型决定下一步要么给出最终答复要么请求调用工具 resp model.chat(messages, toolstool_schemas) messages.append(resp) if resp.is_finished: update_task_status(task_id, finished) return resp.content # 2. 契约校验检查工具是否存在、参数是否合法、是否有权限 tool_name, args resp.tool_call error validate_call(tool_name, args) if error: messages.append(roletool, contentf参数校验失败: {error}) continue # 3. 高危操作熔断 if get_impact_level(tool_name) HIGH: guard create_approval_task(task_id, tool_name, args) messages.append(roletool, contentf操作待审批审批编号: {guard.id}) update_task_status(task_id, waiting_approval) break # 4. 执行工具落事件日志 result TOOL_REGISTRY[tool_name][func](**args) append_event(task_id, step, tool_name, args, result) messages.append(roletool, contentjson.dumps(result, ensure_asciiFalse)) else: update_task_status(task_id, paused_too_many_steps)这段代码没有用Agent框架但三个核心机制都有了工具契约校验、高危熔断、事件日志持久化。如果你需要更复杂的并发或多Agent协作可以在此基础上扩展但核心逻辑不建议外包给黑盒。4.3 实测中踩过的五个坑每个都值得你避开这一节的经验全部来自真实线上按“恶心情”排序坑一模型把可选参数填成字符串“null”。现象查询接口要求传日期范围模型把没拿到值的参数填成null字符串接口直接把null当日期解析查询结果为空模型开始无脑重试。解法在schema描述里明确写“若用户未提及此参数不要传值留空即可”同时在契约校验层把所有值为字符串null或None的参数直接剔除。坑二只读工具描述里没写清副作用模型在“查询”步骤调用了删除接口。现象模型把任务分解为“先查后删”但它把“查看客户资料”和“删除客户”两个工具搞混直接调用了删除。虽然最后被权限拦截但吓出一身冷汗。解法高危工具描述里必须加显式警告同时在工具注册机制里按影响等级分类高危工具一律走人工确认通道不依赖模型自觉。坑三失败重试导致重复创建。现象模型调用“创建报销单”工具时网络超时我们没有幂等保护重试后系统里出现了两张内容相同的报销单。这类问题在Agent场景被放大了因为模型重试的频率远高于人类操作。解法所有写工具必须在参数里带上request_id幂等键后端按幂等键去重给同一个键的重复请求返回第一次的结果。坑四任务状态全放内存进程一重启全部归零。现象开发阶段一切正常上线后半夜进程因内存问题重启正在进行的十几个Agent任务全部变成“失联状态”用户卡在等待页面。解法任务状态和每一步的中间消息必须持久化。我后来把状态信息全部落到PostgreSQL里进程重启后从事件日志里重建上下文。坑五评测只看答案对不对没管操作路径合不合法。现象我们最初评测一个“退货申请”Agent只看最终是否成功创建退货单结果发现模型经常跳过“校验退货原因”这个步骤直接创建单据。从最终结果看任务成功了但从业务流程看是非法路径。这个问题特别隐蔽直到业务方抽查审计日志才发现。解法评测集必须同时包含结果断言和路径断言后面第5节专门讲。5. Agent上线后真正的硬骨头评估与可观测性怎么设计很多团队把Agent做到“demo能跑通”就认为大功告成我见过的最痛教训都发生在上线之后。这一节专门讲评估和可观测性它们是衡量一个Agent“靠不靠谱”的关键。5.1 为什么传统准确率指标在Agent场景里会失效传统模型评估的核心指标是准确率给定输入判断输出是否和标准答案一致。这套思路在对话问答里还能勉强用但Agent场景完全不同——Agent的输出是“一串工具调用序列”最终结果只是其中的一部分。算一笔账你就明白了。假设模型的单步工具选择准确率是95%一个典型的Agent任务需要连续做5次工具调用那么“全程无错”的概率大约是0.95的5次方约77%。当任务做到10步时这个数字跌到60%以下。这说明即使你的单步能力已经不错多步执行后的成功率衰减是惊人的。如果评测不把“路径正确性”纳入考量你在demo里看到的90分在真实任务上可能连70分都不到。还有一个更隐蔽的问题Agent的失败模式和传统模型完全不同。传统模型答非所问大家能一眼看出来Agent可能很顺畅地调了一串完全错误的工具、生成了格式完美但业务非法的单据从表面看“任务成功了”。这种失败必须以结构化方式去评测靠人肉眼盯trace根本盯不过来。5.2 建立一套能挡住“非法路径”的评测集我建议每个agent-native项目从第一天就建立自己的评测集。这个评测集不用很大但必须覆盖两种断言。第一种是结果断言判断任务最终是否达到了目标。例如“用户申请报销5000元最终是否创建了报销单且金额为5000元”。这类断言用规则代码就能写。第二种是路径断言判断Agent是否用了合法的方式达成目标。例如“创建报销单”之前是否调用过“查询报销科目”工具“删除客户”之前是否经过人工审批流程整个过程是否调用过超出权限范围的工具路径断言是agent-native评测和传统评测最核心的差异。我在项目里用了一个很土但有效的做法把每个评测用例定义成一份JSON同时包含expected_result和required_path_steps、forbidden_tools、human_approval_involved等字段评测时对Agent的完整工具调用序列做规则断言。对于更开放的场景可以引入LLM-as-judge辅助判断比如让一个Judge模型评价“工具的调用顺序是否逻辑合理”。但我的建议是先把规则断言做扎实再用模型做补充判断。规则断言可解释、可复现模型判断容易受prompt影响两者结合以规则为主、判断为辅。5.3 可观测性设计上线后你靠什么在半夜睡得着觉最后一块拼图是可观测性。Agent系统比传统系统的排查难度高一个数量级因为问题不再只是“这段代码报错了”而是“模型的思考轨迹失常了”。所以在系统设计阶段就要埋好四类数据全链路Trace每一次模型请求、工具调用、中间返回、任务状态变更都要有结构化日志。我建议给每个任务分配一个task_id每步事件分配一个event_id两步之间用step_seq排序随时可以重建单个任务的完整执行时间线。可搜索的思考记录模型在每一步的thought/推理内容可能会被某些框架默认丢弃但排查时恰恰最有用。请务必保留并且允许运营同学按任务ID查出来回放一遍。业务指标看板工具调用成功率、任务完成率、平均执行步数、连续失败率、等待人工审批的任务数。这几个数字比模型loss更能反映Agent的真实健康状况。版本绑定模型的提示词、工具schema、评测集和线上结果四者必须绑定到同一个版本号里。否则你会遇到“昨天还好好的今天全乱套”却不知道是模型偷偷更新了还是工具描述被误改了。这里再提一个实战心得给每个工具加上“影响等级”元信息之后编排层会先于模型判断“这个调用是否需要审批”。我用它做的第一版很简单——影响等级写死在工具注册表里等级高的直接返回“操作待审批”提示。后来发现这个设计救了我很多次强烈建议你抄走。项目上线到现在已经跑了三个多月我最大的体会是agent-native不是某个框架能用某个库能解决的问题它是一整套设计选择。你在最开始选“要不要给工具写清楚副作用、要不要做状态持久化、要不要建评测集”时的决定决定了这个系统到底是一个有边界、可维护的自主执行平台还是一个表面上很聪明、实际上随时失控的壳。如果这篇文章只能留下一个建议我会说从第一天就给你的Agent工具设计好契约校验、高危熔断和事件日志。这三样东西几乎能拦住我在第4节列出的五个坑里的大部分而它们加起来不过几百行代码。先把这套地基打好再去追求更复杂的规划能力和多Agent协作你会发现路顺很多。最后分享一个小技巧当你觉得Agent经常做出“匪夷所思”的选择时不要急着换更贵的模型先把你提供的工具描述、数据语义、权限规则这三样东西逐行读一遍。我用这个排除法解决过不少“看起来是模型智商问题”的故障实际上多数时候是我们的系统在语义上给模型挖了坑。
