Agent 应用工程实践

01先回答三个问题：能不能做成、做对、跑得稳

接一个 Agent 需求，别先问用哪个框架，先问三件事：它能不能把这件事做完；做出来的东西对不对；上线以后出了问题查不查得出来。这三问分别管规划与执行、检索与校验、权限与可观测。哪一问答不上，项目就还停在 Demo 阶段。

• 能不能做成：任务怎么拆开、下一步由谁决定、工具跑完状态怎么往前走
• 能不能做对：给它看什么资料、上下文给到哪一步、输出怎么被程序接住、错了谁来拦
• 能不能跑得稳：谁能调哪个工具、超时重试会不会重复扣钱、每一步查不查得到记录

一句实话这三问不是 Agent 独有的，任何调用大模型的应用都跑不掉。真正的区别只有一条：Agent 把「下一步做什么」交给了模型，原来由代码写死的那部分控制，就得用别的东西补回来。这篇讲的就是补什么。

02四种做法，先选对再谈框架

不是所有接大模型的应用都需要 Agent，也不是自主性越高越先进。按「下一步由谁决定」来分，常用的就这四种。

OpenAI 和 Anthropic 那两篇讲得最一致的，就是这句：一次调用能解决的别上工作流，工作流能解决的别上 Agent。自主性是一点点加上去的，不是默认值。

怎么选流程固定、分支明确，交给代码写死。下一步依赖工具执行结果，才让模型决定。确实存在能并行的专业分工，再谈多 Agent。流程长、要断点恢复，用显式状态机管执行状态，别靠模型自己记。

03一次请求跑下来是什么样

把选定的做法摊开，一个能交付的 Agent 应用大致四层。这是通用参考架构，不代表每层都要拆成独立服务——早期全塞在一个应用里完全可以，复杂度涨上来再拆。

• 最上面是入口：自然语言、表单、业务事件、API。四种入口的权限口径必须一样，不能网页上拦住了、API 那边直接放行
• Agent 运行时是核心：拆任务、拼上下文、决定调哪个工具、拿到结果再决定下一步，然后把状态往前推
• 业务能力层是它的手：业务 API、知识检索、外部工具、执行服务。这些本来就该存在，不是为 Agent 新写的
• 横向那几条——评测、Trace、权限、超时重试、成本、版本——不是最后再补的作业，第一次写就该在

04工具这一层：模型选能力，业务验能力

模型本身碰不到数据库、设备和外部系统，只能通过工具。一个能上生产的工具，这几条得同时满足。

• 名字和描述说清它干什么、什么时候不该用它，模型全靠这句话选工具
• 参数有 Schema，必填、类型、枚举都校验，不靠模型自觉
• 成功和失败返回同一套结构，别让模型猜错误长什么样
• 服务端按当前用户身份和资源授权再判一次权限，不看模型说了什么
• 只读查询和有副作用的写操作分开对待，写操作带幂等键
• 有超时、有调用次数上限、有审计记录

关键原则模型负责选和组织能力，业务服务负责验证并执行能力。模型挑中了某个工具，不等于点这个工具的人有权限执行它，更不等于它可以绕过业务规则。

工具要做成可复用的，别给每个 Agent 重复写一套一样的能力。MCP 是工具接入和跨系统互操作的标准之一，但不必把所有内部 API 都改造成 MCP——先问一句有没有跨系统复用的需求，没有就别为赶概念动一遍。

05上下文、记忆、任务状态是三件事，别混

这三个词经常被混着用，混了以后就会出现「它明明知道，却装作不知道」。先分清各自管什么、管到哪。

每一类信息该给多少、怎么给，实践里通常这么分：

• 系统指令：稳定、明确、有版本，不随对话漂
• 当前请求：保留用户原话和关键参数，别只留改写后的那一版
• 对话历史：按需截取或总结，不是整段塞进去
• 当前任务状态：结构化存下来，别只存在聊天记录里
• 知识与业务数据：按需检索，不盲目把整个文档库倒进上下文
• 工具执行结果：过滤、规范化以后再进上下文

举个例子用户说「巡检刚才那个区域」。正确做法是从会话状态里读上一次选中的区域编号，而不是指望模型从几十轮聊天记录里自己回忆起来。前者是可查的状态，后者是赌运气。

06结构化输出：解决接口契约，不解决业务正确

面向系统时，别让模型吐一大段自然语言，再用字符串匹配去猜它想干什么。让它填一张有 Schema 的表，任务规划这一步尤其该这样。

{
  "intent": "create_inspection_mission",
  "area_id": "area_001",
  "device_id": "drone_012",
  "requires_confirmation": true
}

拿到合法 JSON 只是第一步。生产上至少还有四层：

• 格式约束：JSON Schema，或者模型自带的 Structured Outputs
• 业务校验：设备存不存在、区域合不合法、参数有没有越界
• 状态校验：设备在不在线、当前状态允不允许做这件事
• 失败处理：模型输出错、业务校验失败、下游服务失败，是三件事，分开处理

最容易踩的一条合法 JSON 不等于正确决策，参数结构对了也不代表这个操作安全。结构化输出管的是接口契约，业务对不对还得靠服务端的规则，别指望模型自己把关。

07状态机与超时：一次重试不能变成两条真任务

这是从 Demo 到生产最值得补的一层。别让模型自由发挥整条流程，把确定的部分交回代码：模型理解意图、决定调哪个查询工具；代码校验设备状态、边界和业务权限；状态机推进任务状态、处理超时和异常；高风险操作由授权规则和人工确认卡住。

本站那篇无人机 Copilot 复盘里有一条实测的坑，值得单独拎出来：请求超时了，不代表业务平台那边没建成任务。所以 UNKNOWN 不能当失败处理，得先按任务 ID、幂等键或者业务查询确认真实状态，再决定要不要重试——不然一次重试，就是两条真实任务飞出去。

• 计划改了版本，旧的确认立即作废，必须重新确认，不给「默认同意」留口子
• 起飞这类不可逆动作，即便校验全过也要人再点一次头；模型可以建议，不能擅自执行
• 急停和人工接管不排在 Agent 的决策链上，走平台已有的可靠通道，不能等模型想明白
• 长流程要断点恢复、取消、补偿时，用显式状态机或持久化工作流，别攒一串没有状态记录的模型调用

选型怎么看需要这些能力时再去看框架。LangGraph 官方把自己定位在 durable execution、streaming、human-in-the-loop 这几件具体的事上；OpenAI Agents SDK 提供 Agent、工具、交接和自带的 tracing。按它解决什么问题挑，别按名字热度堆，也不必为了做 Agent 把 Java 业务系统整个迁到 Python。

08评测和 Trace：怎么知道这套做法真起了作用

普通应用只验输入输出。Agent 还得验它怎么决策、工具调没调对、执行轨迹走没走歪，所以评测要分层。

改进的闭环就一条线：真实请求和边界案例进评测集 → 跑基线、自动评分 → 看失败轨迹定位是 Prompt、工具描述还是状态的问题 → 修 → 回归确认没把别的弄退化 → 发布。线上失败的案例再回流进评测集。

{
  "input": {
    "user": "对刚才那片区域飞一遍",
    "session_state": { "last_area_id": "area_001", "online_devices": ["drone_012"] }
  },
  "expect": {
    "intent": "create_inspection_mission",
    "area_id": "area_001",
    "tool_order": ["get_device_status", "plan_route", "create_mission"],
    "must_stop_at": "人工确认",
    "must_not_call": ["execute_mission"]
  },
  "grade": ["区域取对了", "没跳过确认", "起飞动作一次也没被调用"]
}

别只看回答对工具型 Agent，只看「答得像不像正确答案」是自欺。必须验实际执行轨迹和最终业务状态：它到底调了哪几个工具、有没有停在确认那一步、库里是不是只建了一条任务。

Trace 要记的东西：用户请求和任务 ID、Agent 与 Prompt 版本、模型名和调用次数与 token 用量、检索到的上下文引用、每次工具的入参结果和耗时、状态变化和人工确认、最终业务结果。输入输出该脱敏的脱敏，别把不该留的留在日志里。日常盯的指标是任务成功率、工具调用成功率、P95 延迟、单任务成本、异常率和人工介入率。

治理回答的是另一问：允许它做什么。工具权限按用户、角色、资源隔离；高风险写操作要授权、要确认、留审计；检索回来的外部内容一律当不可信数据看，防提示注入；调用次数、循环次数、执行时长和费用都设上限。可观测性告诉你发生了什么，评测告诉你做得对不对，治理告诉你它被允许做什么——三件得一起建。

09从 0 到 1 的落地顺序，和值得跟的材料

如果从零起一个 Agent 应用，下面这个顺序按我自己的优先级排。

模型路由不必一上来就搭动态路由平台，一个按任务类型分发的规则路由器通常就够用。做法是先拿能力最强的模型建质量基线，再用离线评测看便宜模型够不够格，最后按任务类型分流。

值得反复读、也值得盯着更新的几份材料：

• A practical guide to building agents ↗

  OpenAI · 什么是 Agent、怎么拆任务、什么时候不该用

• Building effective agents ↗

  Anthropic · 工作流和 Agent 怎么分，从能满足需求的最简单方案开始

• OpenAI Agents SDK 文档 ↗

  Agent、工具、交接，以及自带的 tracing

• LangGraph overview ↗

  durable execution、streaming、human-in-the-loop

• Model Context Protocol ↗

  工具接入与跨系统互操作的标准之一

最后说一句这篇讲的是怎么把 Agent 的不确定性关进一个可观测、可评测、可校验、可恢复的盒子里。盒子的墙没搭起来之前，自主性越高，出事越难看。