这两年大家开口闭口都是 AI Agent但真正把系统做成“Agent 用起来很顺手”的团队其实没几个。我最早看到 agent-native 这个词时以为它又是包装出来的新概念直到自己把一个传统订单系统改造成智能体可调用的服务形态才意识到它说的根本不是“在 App 里加一个机器人对话框”而是软件本身的架构前提变了。所谓 agent-native简单讲就是把 AI 智能体作为系统的一等公民来设计。传统软件的服务对象是人人看页面、点按钮、填表单agent-native 应用的服务对象是智能体智能体用自然语言理解目标、自己规划动作、通过工具调用把事办完。判定一个系统是不是 agent-native不看你接没接大模型而看你有没有把“让 agent 高效且安全地使用你的系统”当作核心设计目标。这篇文章不聊概念包装直接讲我在实际改造中的设计思路、落地步骤和踩过的坑。1. 先搞懂 agent-native它不是“接入大模型”而是重构软件形态1.1 从 app-native 到 agent-native交互主体变了一个系统从设计之初就是给人用的比如打车软件乘客自己输入目的地、自己比对车型、自己点确认下单这是 app-native。换成 agent-native 之后用户只需要告诉智能体“明早七点从望京去首都机场选经济舱、别走高速”剩下的行程规划、比价、下单、确认信息全部由智能体替用户完成。关键变化在于“使用者”从人变成了模型。人眼里的好设计是按钮大、路径短、文案清楚模型眼里的好设计是工具描述准确、参数结构清晰、返回结果稳定。以前我们做产品要研究用户行为现在做 agent-native 系统要研究的是“模型行为”——它面对你的接口时会不会选错工具、会不会编造参数、会不会在一条错误路径上反复重试。这一点想通之后很多设计决策会完全不同。比如 API 的错误返回以前给前端用返回一段 HTML 错误页或者一个含糊的 500 就够了前端弹个 toast 就完事。但给 agent 用错误返回必须结构化、可解释、带下一步建议否则模型根本不知道发生了什么只能瞎猜然后重试最后变成死循环。还有一点容易被忽略agent-native 不代表抛弃所有 UI。用户在关键节点仍然需要可视化确认尤其是花钱、删数据这类不可逆操作。只不过 UI 从“完成所有操作的主要入口”退化成“审批和展示结果的辅助层”。这个定位变化很重要决定了你前端团队的工作重心到底放在哪。1.2 agent-native 给技术架构带来的三个转移第一个转移是交互层。传统应用的交互靠 GUI 事件驱动agent-native 的交互靠对话意图驱动。系统入口从“一堆页面”收敛成“一个对话入口加一组工具”用户不再需要理解你的菜单结构你也不再依赖页面层级引导用户而是靠智能体理解意图、编排动作。第二个转移是业务能力层。以前业务逻辑分散在各个页面控制器和前端调用的 API 里agent-native 要求你把业务能力原子化成一个个“工具”查订单是一个工具、改地址是一个工具、取消订单是一个工具。工具就是 agent 的四肢你的系统能干什么、边界在哪全部通过工具列表暴露给模型。第三个转移是决策层。传统系统每一次业务动作都由用户手动触发agent-native 把“决定下一步做什么”交给了模型。这不是简单的交互方式变化而是引入了新的不确定性模型可能选错工具、可能把参数填歪、可能在两个工具之间来回横跳。系统设计上必须增加对应的可控制层比如最大步数限制、重复调用检测、高风险操作二次确认。这三个转移叠加下来你会发现自己做的已经不是“加个 AI 功能”而是把原来的单体应用重新拆成“模型可理解的工具集 状态管理 安全护栏”。听起来工程量大但绝对值因为同一个工具集以后既可以被对话助手用也可以被自动化流程用等于一次改造多处受益。2. agent-native 的核心设计工具、状态、安全、记忆2.1 工具层为 agent 写 API而不是为人写 API工具层是 agent-native 的重中之重。我见过太多团队栽在这里把公司现有 API 直接塞给模型当工具实际效果非常差。原因很简单现有 API 是给人调的路径短、参数隐晦、返回字段嵌套深模型根本看不懂。给 agent 用的工具描述要像给一个刚入职的实习生写操作手册。工具名称要动词开头、语义明确query_order_detail比orderQuery好一百倍。description 里要写清楚“什么时候该用它、什么时候不要用”而不是简单一句“查询订单”。比如name: query_order_detail description: 根据订单号查询订单详情适合用户询问订单状态、物流、金额时使用。 如果用户没有提供订单号先调用 list_orders 获取订单列表不要自己编造订单号。参数部分尽量用约束明确的类型能用 enum 就用 enum能加 description 就加 description。比如订单状态给模型一堆可选字符串“pending/paid/shipped/completed/cancelled”它才知道每个词是什么意思。返回结构更要统一我建议所有工具固定返回两层结构{ success: true, data: { ... } }失败时返回{ success: false, error: { code: ORDER_NOT_FOUND, message: 订单不存在请检查订单号后重试 } }这套结构表面上多包了一层实际对模型极其友好。它不用在一大坨返回体里找自己关心的字段一眼就能判断调用成没成功、失败原因是什么。更重要的是错误码可以写进系统提示词里告诉模型“遇到 ORDER_NOT_FOUND 就告知用户查不到不要重试”死循环概率直接下降一大截。工具数量也要克制。我实测下来一个智能体场景控制在 10 到 20 个高质量工具最舒服。少于 5 个发挥不出 agent 的价值超过 30 个模型选错工具的概率明显上升。如果业务很复杂优先做工具分层让一个“路由工具”根据关键词分发到二级工具而不是把所有工具平铺给模型。2.2 状态层让 agent“看见”而不是“记住”很多初做 agent 的人容易犯一个错恨不得把系统里所有状态都塞进提示词里让模型“记住”。几轮对话之后上下文又长又乱模型反而把关键信息丢了。agent-native 的原则是动态状态不要塞上下文要让模型通过工具实时查询。举个例子。用户问“我刚买的那双鞋发货了吗”正确做法是系统先查当前用户是谁然后给模型一个query_recent_order(user_id, product_keyword鞋)工具模型调用后拿到实时结果再回答。而不是在每轮对话里都带上“用户张三订单包含一双鞋”这种旧数据。你今天带了明天他换了双袜子你的旧状态就是误导。会话状态还是要管的但管的是对话消息本身。我一般给对话消息设定 token 预算超出后做两件事一是裁剪最老的轮次二是把前几轮内容让模型压缩成摘要存起来。系统提示词、工具返回、用户最新消息永远保留历史对话按需压缩。业务状态如果是跨步骤的比如“取消订单前先确认了原因”我建议显式维护一个state_store把“当前在取消订单流程、订单号、确认状态”存进去下一次工具调用前再把相关的 state 作为上下文注入。不要把一切都押在模型的记忆上模型不可控你的核心业务状态必须可控。2.3 安全层权限收敛、人工审批、全量审计agent-native 的安全设计核心原则只有一条agent 的权限不能超过背后用户的权限而且关键写操作必须有人确认。我按操作危险程度把工具分成三档级别动作类型示例执行策略L1只读查询查订单、查库存、查物流agent 直接执行走审计L2低风险写保存备注、修改草稿、添加标签agent 直接执行走审计L3高风险写取消订单、退款、发送消息、删除数据必须用户二次确认L3 的确认机制在 agent 场景里要设计得顺畅一点。我用的方案是工具执行时返回{status: PENDING_APPROVAL, approval_id: ...}agent 看到这个结果后主动询问用户“取消该订单需要确认回复确认即可执行”用户确认后 agent 再调用一个专用的confirm_action(approval_id)工具完成操作。这样既保留了 agent 主导流程的体验又把最终决定权留在人手里。审计日志也必须全量记录尤其是工具级日志。我每条工具调用都会记下时间、用户 ID、会话 ID、工具名称、输入参数、返回结果、耗时。这不仅是合规要求更是排查线上问题的唯一途径。模型是概率性的它干了什么奇葩操作你根本猜不到没有日志你只能干瞪眼。另外敏感操作的频率限制也要做比如单日最多取消几单、单次退款上限多少这些护栏在 agent 场景下比人操作场景更必要因为模型可能在一次任务里连续触发多个写操作。2.4 记忆层长期记忆与上下文的取舍agent-native 的“记忆”要区分两种情况短期上下文和长期用户偏好。短期上下文就是当前会话的 messages管理方法前面说了。长期记忆比如用户常用的收货地址、偏好快递公司、对某个商品类别的历史偏好建议存到向量库或者结构化存储里在需要时检索注入。我踩过的坑是“把向量库检索出来的东西全塞进 prompt”。一次检索出来二三十条记忆模型反而被无关信息干扰。后来改成只注入跟当前用户和当前意图强相关的记忆最多 3 到 5 条。比如用户一旦提到退货就检索他近期退货相关的记录用户提到发票才检索发票抬头信息。记忆注入也是对话上下文的一部分不是越多越好。长期记忆的删除权一定要交给用户。用户说“忘掉我的偏好”你的系统要真的清掉那些存储而不是模型口头答应。这一点既关乎合规也关乎用户信任agent 越智能越要给人“关掉记忆”的安全感。3. 从零落地一个 agent-native 服务一个订单助手的完整实现3.1 最小闭环模型 工具 循环先别急着上什么编排框架。我推荐自己先写一个最小的 agent 循环几百行代码跑通之后再考虑要不要引入框架。最小闭环只需要三样东西一个支持工具调用的大模型接口、一组工具定义、一个 while 循环。下面是我实际用过的极简版本Python 加 openai SDKimport json from openai import OpenAI client OpenAI() TOOLS [ { type: function, function: { name: query_order_detail, description: 根据订单号查询订单详情。用户询问订单状态、物流、金额时使用。用户未提供订单号时先调用 list_orders。, parameters: { type: object, properties: { order_id: {type: string, description: 订单号} }, required: [order_id], }, }, }, { type: function, function: { name: list_orders, description: 查询当前用户最近的订单列表。当用户说我的订单最近买了什么等表述时使用。, parameters: { type: object, properties: { limit: {type: integer, description: 返回条数默认5} }, }, }, }, ] SYSTEM_PROMPT 你是订单助手的智能体。可以调用工具来查询和操作订单。 规则 1. 用户没有提供订单号时先调用 list_orders 获取订单列表不要编造订单号。 2. 回答简洁给出结论和必要字段即可。 3. 工具返回错误时如实告知用户原因不要反复重试同一个参数。 MAX_STEPS 6 def dispatch_tool(name: str, arguments: str): args json.loads(arguments) if name query_order_detail: return query_order_detail(args[order_id]) if name list_orders: return list_orders(args.get(limit, 5)) return {success: False, error: {code: UNKNOWN_TOOL}} def run_agent(user_input: str): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(MAX_STEPS): resp client.chat.completions.create( modelgpt-4o, messagesmessages, toolsTOOLS, tool_choiceauto, temperature0.2, ) msg resp.choices[0].message messages.append(msg) # 包含 tool_calls 的 assistant 消息必须加入历史 if not msg.tool_calls: return msg.content for tool_call in msg.tool_calls: result dispatch_tool(tool_call.function.name, tool_call.function.arguments) messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse), }) return 操作步骤较多我没能在限制步数内完成。请缩小范围或稍后重试。这段代码里最容易被忽略的是messages.append(msg)。assistant 消息里带着tool_calls必须原样放回历史模型才知道自己刚才调了哪些工具下一轮才能继续。少这一步API 直接报错。另外temperature在 agent 场景一定要调低0.2 左右合适否则模型输出随机性太强同样的输入两次结果差别很大线上没法排查。3.2 写工具函数时的三个关键规范第一返回结构必须统一。前面说的success/data/error结构不只是格式好看更给模型提供了稳定的“信号”。我见过团队某个工具返回数组、另一个返回对象、还有的失败时返回空字符串模型真的会被逼疯。统一结构后系统提示词里可以明确写“判断 success 字段false 则向用户解释 error.message”。第二工具描述要写“调用边界”。什么叫边界比如查询订单的工具描述里写“仅返回近 90 天订单超过请告知用户”取消订单的工具描述里写“必须先调用 query_order_detail 确认订单可取消且必须获得用户明确同意”。模型对描述中的“必须”“禁止”非常敏感这些词越明确行为越可控。第三工具要设计成幂等的尽量幂等。尤其写操作agent 场景下模型因为网络超时重试一次、用户多问一次“成功了吗”agent 又补调一次都是常见情况。如果后端幂等做得好重复调用不会产生副作用做不好用户就可能被重复扣款或重复取消订单。这一点后面单独展开但写工具函数时就要把它刻在脑子里。给一个工具函数的标准写法参考def query_order_detail(order_id: str) - dict: try: order order_service.get(order_id) if not order: return {success: False, error: {code: ORDER_NOT_FOUND, message: 订单不存在请核对订单号}} return { success: True, data: { order_id: order.id, status: order.status, amount: order.amount, product_name: order.product_name, shipping: order.shipping_info, }, } except Exception as e: return {success: False, error: {code: INTERNAL_ERROR, message: 查询服务暂时不可用请稍后重试}}注意返回给模型的字段必须精简。订单底层可能有一百个字段但你只需要把模型回答用户需要的那几个字段返回。字段越多模型越容易抓错重点token 也烧得越快。3.3 MCP 标准化让工具可以被动态发现如果工具数量多、涉及跨团队共享2024 年下半年开始 MCPModel Context Protocol逐渐成了事实标准。MCP 的核心价值是“一次接入处处可用”你的服务暴露成一个 MCP server客户端通过统一的协议自动发现工具不用每个接入方都手动维护一份工具 schema。下面这个例子是用一个常见的 Python MCP SDK 把订单查询工具暴露成 MCP server 的写法from mcp.server.fastmcp import FastMCP mcp FastMCP(order-assistant) mcp.tool() def query_order_detail(order_id: str) - dict: 根据订单号查询订单详情。用户询问订单状态、物流、金额时使用。用户未提供订单号时先调用 list_orders。 return query_order_detail_impl(order_id) mcp.tool() def list_orders(limit: int 5) - dict: 查询当前用户最近的订单列表。 return list_orders_impl(limit) if __name__ __main__: mcp.run()用了 MCP 之后agent 客户端只需要读取 server 提供的工具描述自动转为自己的 tools schema不需要你在每个调用方都硬编码一份 TOOLS 列表。这是真正的“agent-native”基础设施思路让工具是活的、可发现的而不是写死的一份 JSON。我个人的建议是团队刚开始做第一个 agent 功能时不需要 MCP手写工具列表就够当工具超过 10 个或者要开放给其他团队/其他 agent 用时再迁移到 MCP。工具协议本身不会让你的 agent 更好它简化的是工具分发的工程量。3.4 真实场景记录一次带审批的取消订单我拿一次实际的“取消订单”流程来演示整个 agent-native 交互是怎么走的。用户说“帮我把最新一单取消掉我不想要了。”第一步agent 看到“最新一单”但它没有订单号所以调用list_orders拿到最近订单列表找到第一单得到订单号20240601A003。第二步agent 调用query_order_detail(20240601A003)确认这单状态是paid可以取消同时告诉用户这单是什么商品、什么金额等待用户确认意愿而不是直接取消。这里必须靠工具结果确认状态不能靠模型“猜”。第三步用户说“确认取消”。agent 调用cancel_order(20240601A003, reason用户不想要)。这个工具属于 L3 高风险后端并不立即执行而是返回{ success: true, status: PENDING_APPROVAL, approval_id: APP-20240601-8f3a }第四步agent 告诉用户“取消申请已提交需要你最终确认回复确认后立即取消”。用户回复“确认”agent 调用confirm_action(APP-20240601-8f3a)后端才真正执行取消并向用户返回最终结果。这套流程里agent 全程主导节奏但写操作卡点永远在人手里。如果把“确认”环节放在前端独立弹窗里也可以逻辑不变。做成对话内确认用户体验更顺也能让 agent 保持在“从理解到执行”的完整主线上。4. 上线之后最容易踩的五个坑与排查思路4.1 Agent 陷入反复调用工具的死循环症状很典型日志里 model 一直在调用同一个工具参数一模一样返回结果要么是错误要么是同一个值agent 像复读机一样反复调用直到撞上最大步数才退出来。我排查下来最常见的原因是错误返回没有给模型“止损信号”。比如查订单返回{error: not found}模型并不清楚这个错误是永久性的还是临时的就会重试。解决办法有两个一是错误信息里直接写清楚比如message: 订单不存在请勿重试建议用户核对订单号二是在系统提示词里加一条规则“遇到 ORDER_NOT_FOUND、ORDER_CANNOT_CANCEL 等错误码时向用户解释原因不要重复调用同一工具。”双管齐下之后死循环问题基本绝迹。另外一定要保留最大步数限制就算模型抽风也最多跑 6 到 8 步就兜底返回。兜底文案我都是写“操作步骤较多我没能完成”然后引导用户换一种说法重试。4.2 上下文越滚越长、响应越来越慢Agent 每调一个工具返回内容都会留存在 messages 里。业务复杂时五六轮过后上下文里堆了几百行 JSON模型处理速度肉眼可见变慢token 费用也在涨。我常用三板斧第一工具返回减字段前面说过返回给模型的数据必须是经过裁剪的视图第二列表类数据截断默认只返回前 5 条多的给总数和分页参数模型需要更多时会用分页参数再查第三历史对话超过一定轮次就做摘要把旧轮次压缩成一段话比如“用户询问了 3 号订单的物流随后确认了取消操作”只保留关键事实。还有个大坑千万别把日志、调试信息、数据库原始行返回给模型。有一次我的工具异常时把堆栈信息返回了模型一本正经地把堆栈报错当结果念给用户听场面非常尴尬。给模型的永远是“面向用户问题的答案”不是“面向程序的调试信息”。4.3 模型幻觉出本来不存在的参数用户说“帮我查一下单号 123”的时候模型有可能在参数里填一个123456789出来因为它在训练数据里见过类似数字下意识补全了。这是 function calling 场景下最恶心的幻觉之一。解法分三层。第一层工具描述里明确写“只能使用用户明确提供的订单号用户没有提供时必须先调用 list_orders 获取禁止猜测或编造订单号”。第二层代码层校验对枚举值和白名单字段做硬校验不合法直接返回 ORDER_NOT_FOUND。第三层把参数 schema 里不确定的字段设为 optional并明确写上“如不确定可不填不要臆造”让模型有“不填”的合法出口。多数模型在有明确出口时比被逼着填一个值时表现好得多。从设计上更推荐把任务拆开先让模型调用“列表查询”拿到真实存在的 ID再基于真实 ID 做后续操作。这条链路把幻觉空间压到最小因为真实 ID 是工具返回的不是模型生成的。4.4 并发场景下的重复执行与竞态Agent 场景天然有重复触发风险。用户连续点了两次提交、上一轮请求超时用户又发了一次、agent 自己因为超时重试这些都会导致同一个写操作被执行多次。人操作时双击也常常被前端防抖拦掉agent 时代这个防抖要移到后端。标准做法是给写操作加幂等键。每个 agent 会话生成一个全局唯一的request_id所有写工具都要求带这个参数。后端点单表加一个request_id唯一索引重复请求直接返回第一次的执行结果。我实际还遇到过并发取消失败后状态机卡死的案例两个取消请求并发到达一个成功一个失败订单状态变成了“已取消”和“取消失败”两个结果。压测之后发现是状态流转没加乐观锁后来所有状态更新都带上“当前状态”作为条件update ... where status :old_status解决了竞态。这个坑不发生在模型身上但 agent-native 放大了它的发生概率因为模型的调用节奏比人的点击快得多一次任务内连续多个写操作是常态。4.5 线上评估无从下手很多团队的 agent 功能上线后只有“看起来能用”的感受没有量化的效果指标。传统接口测试用例对 agent 不适用因为模型输出是概率性的同一个问题两次回答过程可能完全不同。我实践的评估方案分三块。离线评估集我准备了三类数据用户真实录制的 query、标注好的期望结果、需要规避的边界场景比如涉及隐私、拒绝执行的。评估指标很简单指标含义目标参考任务完成率最终结果满足用户请求的比例85%工具调用准确率选对工具并参数全部正确的比例90%无效调用率调了不该调的工具或明显参数错误5%平均步数完成任务平均调用工具次数5线上监控重点看兜底文案触发率、用户明确表达不满的比例、L3 操作审批拒绝率。兜底文案触发率突然升高大概率是新需求没覆盖工具集审批拒绝率升高则说明 agent 把不该做的操作也推进到了确认环节需要加强工具描述里的边界说明。每周从线上日志抽 20 到 30 条真实 query 回流到离线评估集让评估集跟着业务变化走。模型隔几个月更新一次也要全量回归一遍评估集防止“新模型更聪明了但行为变了”导致的意外下滑。做 agent-native 快两年我最大的体会是别急着追新框架。先把工具层打好一个模型加一个循环加一组精心设计的工具能解决绝大多数业务问题。框架解决的是复杂状态流你的业务还没复杂到那个份上就别给自己加戏。始终记住agent 一定会出错一定会用错工具、编错参数、走错路径。你的系统设计要让它“错了还能优雅回退”而不是一出错就让用户承担后果。另外所有你以为模型能“记住”的东西最终都别指望它状态存到你自己的系统里比什么都靠谱。