Agent开发 12|系统设计:怎样评审 Agent 的上线准备?
《Agent开发》系列 · 第 12 篇
订单助手已经能调用工具、查询知识、等待审批,并在重启后继续处理。演示时,订单 1001 的 500 金币也只补发了一次。
现在产品负责人问:“下周能不能开放给真实用户?”
这时不能只回答“功能都做完了”。我们需要说明开放哪些能力、由哪些组件负责、发生故障怎样处理,以及现有证据能支持什么结论。
本篇将前面的知识放回一套参考架构,沿着真实请求的处理路径分析取舍,再建立一份可用于上线评审的证据清单。这是一份设计推演,不是宣称前面的教学脚本已经组成可部署的生产系统。
一、系统设计先从范围开始,不从框架名称开始
1.1 我们准备开放什么能力?
假设目标产品是企业订单助手,第一阶段业务范围如下:
- 用户查询自己有权访问的订单,获得状态解释和相关制度依据。
- 对金币未到账问题,系统查询支付与最终发放结果,必要时创建补发申请。
- 有权限的人员批准具体申请,后端重新校验后执行。
- 执行过程支持追踪、等待、恢复与人工接管。
不把自动退款、任意 SQL、任意网页访问和自主修改业务规则纳入这个范围。每增加一种工具,就需要重新检查数据权限、副作用和恢复路径。
这里的“第一阶段”是产品开放范围,不是延长本系列的学习时间安排。
1.2 怎样判断一项任务完成?
先将不同结果分清:
| 任务 | 合理终态 | 不能冒充成功的情况 |
|---|---|---|
| 查询订单 | 返回可信状态或说明无法访问 | 模型猜测订单状态 |
| 信息缺失 | 请求必要澄清 | 编造订单号继续查询 |
| 申请补发 | 创建可追踪的待审批申请 | 把“已提交申请”说成“已到账” |
| 执行补发 | 核对可信账务结果 | 仅有批准、模型请求或接口超时 |
产品界面、API 状态、评测与监控要使用一致的含义。否则后端的 WAITING_APPROVAL 可能在前端变成“处理成功”,给用户造成错误预期。
1.3 非功能要求也需要具体化
要询问预期流量、数据范围、允许等待多久、哪些错误不能接受、成本预算以及谁负责处理异常。
例如,“查询要快”可以进一步定义为某类查询在指定负载与统计窗口下的完成延迟目标;“可靠”需要包括任务丢失、重复入账与结果不确定的处置规则。衡量服务表现的指标称为 SLI(Service Level Indicator),期望达到的目标称为 SLO(Service Level Objective),二者应围绕用户真正关心的行为定义。Google SRE 服务目标说明
本篇没有进行真实负载测试,因此不提供已经达到的吞吐量、P95 延迟或可用性承诺。
二、一张参考架构图:先看请求怎样走
用户 / 客服界面 审批人员界面
│ │
▼ ▼
API 与身份入口 审批服务
认证、租户与资源权限 审批人权限、范围、有效期
│ │
▼ │ 审批事件
任务服务 ───► 任务状态与 Checkpoint 存储 ◄─────┘
创建任务、查询进度 ▲
│ │ 保存 / 恢复
▼ │
调度与后台 Worker ───────► Runtime
任务领取、重试与恢复 │
├─ Context Builder
│ ├─ State / Memory(按权限读取)
│ └─ RAG 检索服务
│ └─ 文档、词项 / 向量索引、版本与 ACL
│
├─ Model Gateway ──► 允许使用的模型服务
│ 路由、能力检查、时限、用量与预算
│
└─ Tool Executor
工具允许列表、参数、权限与业务校验
│
▼
订单 / 账务 / 工单系统
实时事实、幂等写入、最终结果
贯穿各层:Trace / Metrics / 结构化日志
关键业务:审批、操作与审计记录
持续改进:离线评测 → 发布检查 → 灰度观察 → 故障样本回归
图中的 Worker 指后台领取并执行任务的程序,Tool Executor 指负责校验和调度业务工具的执行模块。图中的框表示职责,不要求每个框独立部署。早期可以使用一个模块化后端和少量存储,把接口与边界划清;当独立扩缩容、团队分工或隔离要求出现时,再拆分服务。
State 是后端维护的当前任务数据;Checkpoint 是在执行边界保存的状态与恢复进度。Runtime 是组织模型、工具和任务步骤的执行程序,Context Builder 为它准备每轮模型输入,Model Gateway 管理模型调用。先把这些职责分清,再看它们怎样协作。
ACL 是访问控制列表,用来表达谁能读取某份资料。本图把它放在知识索引旁,是为了强调检索同样需要权限,不是只有订单接口需要认证。
三、沿着订单 1001,检查完整执行路径
3.1 接收请求:先确定身份,再创建任务
入口验证用户身份,得到可信租户与用户标识。模型参数里的 tenant 或“我是管理员”的自然语言描述不能覆盖这些信息。
创建任务时,关联会话、请求标识、用户和目标资源。用户重复点击或客户端重试,应该按明确的请求幂等规则返回已有任务,或创建有意的新任务,而不是无条件重复发起业务流程。
请求幂等与业务幂等不同:前者避免重复受理,后者保证即使有多个任务指向同一笔发放,也不会重复入账。
3.2 调度任务:数据库成功,通知失败怎么办?
异步系统可能先写任务数据库,再发送队列消息。如果任务保存成功后进程崩溃,消息没发出去,就会留下无人处理的任务。
一种设计是 Transactional Outbox(事务发件箱):把任务变更与待发送事件写入同一个数据库事务,再由后台发布器读取事件并发送。发布器仍可能重复发送,因此消费者需要去重或幂等处理。AWS Transactional Outbox 说明
这个模式解决的是本地状态与待发送事件的一致性,不等于数据库、队列和远程业务系统自动组成一个大事务。
对较小系统,也可以直接从数据库领取待处理任务,但必须明确领取、并发、超时与重试规则。不能仅用一个内存队列就宣称任务重启后不会丢失。
3.3 Runtime 运行:确定性规则包住动态判断
常规路径可以用 Workflow(预先定义步骤与条件分支的工作流)固定:查询身份授权范围内的订单、核对最终发放、创建申请、等待审批、执行前复核。
需要深入未知日志线索时,再在限定区域使用 ReAct,让模型根据新观察选择下一步行动;任务确实需要多阶段调查时,再考虑 Planner-Executor,将制定计划与执行步骤分开。Multi-Agent 让多个承担决策任务的 Agent 分工,适用于清晰的专业边界,不是系统规模稍大就必须引入。
无论模型怎样选择下一步,Runtime 都检查工具、资源与预算。工具结果进入下一轮 Context 前,还要确认属于当前请求,避免把另一张订单的数据回填给模型。
3.4 准备 Context 与 RAG:事实、知识和状态分开
Context 是模型这一轮能使用的输入信息。Context Builder 从授权数据源取得当前目标、事实、进度与约束,选择必要历史和文档片段,并检查长度。RAG 则通过检索外部知识,为生成回答补充依据,是这里的信息来源之一。
实时账务结果回答“订单目前怎样”,知识文档解释“业务规则是什么”,State 记录“任务处理到了哪里”。三者可以一起进入模型输入,但不能互相代替。
知识更新时应关联文档版本、切块版本和索引版本;权限撤销时也要考虑索引与缓存的更新延迟。读取和输出都应执行适当的权限检查,不能因为旧索引中仍然命中某个片段,就默认它仍可访问。
3.5 等待审批:释放执行资源,保留恢复依据
保存申请标识、任务状态与必要进度,再结束当前处理。审批事件到来后验证来源、审批人、申请版本与批准范围,按状态规则恢复。
重复事件、晚到事件和已撤销申请应有明确处理。只有一个 approved 布尔值,通常不足以描述审批生命周期。
3.6 业务写入:用真实结果完成任务
后台执行前重新读取批准范围和当前业务条件,调用有幂等与结果查询能力的账务服务。
调用超时后,任务进入“结果待核对”,不能直接说失败,也不能重新创建无关操作标识补发。核对成功后保存任务完成,并向用户反馈已确认的结果。
如果程序在业务成功后、保存任务完成前崩溃,恢复路径仍要核对原操作,而不是把旧 Checkpoint 当成“没有执行”的证明。
四、技术选型:每个选择都应解释代价
4.1 自己写循环,还是使用工作流框架?
| 选择 | 适合什么情况 | 代价与边界 |
|---|---|---|
| 简单自研 Runtime | 流程少,想明确控制各步骤,团队能维护状态规则 | 要自己实现恢复、事件、并发与观测,不能停留在 while 循环 |
| 工作流或 Agent 框架 | 分支、暂停恢复、图结构与工具编排需求较多 | 需要理解持久化、中断与重放语义,并验证外部副作用 |
| 专用确定性流程 | 业务规则明确、路径可预先定义 | 灵活探索有限,但容易检查和测试 |
框架提供机制,不自动理解你的账务规则。选择前应拿“写入后崩溃、重复审批、版本升级”这些场景做验证,而不是只比较 API 写法。
4.2 存储怎样分工?
任务、审批和关键操作记录通常需要可查询、可并发控制和适当的事务能力。知识原文件需要来源与版本管理,检索索引可以从这些原始资料重建。
可以先按数据性质划分职责,再选择具体产品:
| 数据 | 主要需求 | 不应混淆的边界 |
|---|---|---|
| 任务与审批 | 状态推进、范围核验、持久化 | 聊天摘要不能替代审批 |
| 业务账务 | 原子写入、唯一操作、对账 | Trace 不能替代账本 |
| 文档与索引 | 版本、权限、重建与检索 | 相似度不能证明权威性 |
| Memory | 相关性、过期、删除、访问控制 | 用户偏好不能覆盖业务事实 |
| Trace 与指标 | 排障、聚合、采样和保留 | 采样日志不能承载全部必需审计 |
SQLite 很适合本系列的单机教学。要不要转向其他数据库、独立搜索引擎或向量服务,需要根据并发、部署与运维条件验证,不能仅凭“生产级”三个字堆组件。
4.3 Gateway 是公共能力,但不应成为所有逻辑的中心
网关统一模型协议与调用策略,Runtime 仍管理任务与工具,业务服务仍拥有数据与写入规则。
如果把订单权限、RAG 语料规则和审批全部塞进网关,模型接入层会与具体业务耦合。反过来,每个业务模块各自重试和计算费用,也会失去统一控制。
可以用接口明确职责:Runtime 提供能力要求、允许范围与任务预算,Gateway 返回实际模型、结果、停止原因和用量状态。
4.4 先模块化,再按需要拆服务
拆成多个服务可以独立扩容与隔离故障,但也引入网络错误、版本兼容、分布式追踪与数据一致性问题。
初期可以在同一后端中清晰划分任务、上下文、检索、网关与工具模块。审批与资产业务则根据既有系统边界接入。只有出现明确的负载、权限或团队需求,再决定拆分。
五、故障设计:每个失败都要有下一步
| 故障 | 当前系统应做什么 | 谁提供恢复依据 |
|---|---|---|
| 模型暂时不可用 | 有限重试或切换允许路径,耗尽后停止或排队 | Gateway 的尝试与预算记录 |
| 检索不到足够证据 | 澄清、补查或转人工,不生成确定结论 | 检索与引用记录 |
| 业务写入超时 | 保留结果未知,核对原操作 | 业务服务与账务结果 |
| Worker 崩溃 | 重新领取任务,核对已发生操作 | State、Checkpoint 与业务记录 |
| 审批过期或范围变化 | 阻止新写入,进入重新确认流程 | 可信审批服务 |
| 数据库存储不可用 | 无法可靠保存关键状态时,不启动不可追踪的资产操作 | 存储恢复与运维流程 |
| 观测平台不可用 | 按设计缓冲、降级并报告丢失;关键审计遵守独立策略 | 本地或可靠审计记录 |
还要明确谁来处理自动恢复不了的任务。转人工不是一个字符串终态,而需要有人能看到任务、理解证据、采取操作并留下记录。
对取消请求也应区分“停止后续模型调用”和“撤销已发出的业务操作”。远程请求可能已经成功,取消本地等待不能证明远端没有执行。
六、容量、成本与服务目标怎样评审?
6.1 先定义负载模型
询问峰值同时任务数、每任务模型轮数、平均上下文长度、检索规模、写操作占比和审批等待比例。单次模型调用很快,不代表多轮 Agent 任务也很快。
用一组明确的假设做压力测试,并记录测试环境、配置、数据规模与结果。正常负载之外,还要测试模型限流、工具变慢、队列积压及重复事件。
6.2 把等待拆开观察
用户等待可能来自排队、模型生成、检索、工具、重试退避和人工审批。只有区分这些部分,优化才有方向。
查询任务可以定义端到端完成延迟;审批任务则更适合分别定义受理响应、自动处理时间和人工等待时间。不能把数小时审批等待混进模型 P95 延迟,然后得出模型太慢的结论。
6.3 单任务成本比单次 Token 价格更有意义
成本要包括多轮调用、重试、检索与重排、评测和观测等实际开销。模型费用未知的调用应单列,不能因为账单还没返回就记为零。
在评审中,列出预计成本与实测成本的区别,给预算耗尽后的行为一个明确答案:停止、降级、等待还是人工处理。不要让系统在用户看不到的后台无限尝试。
七、发布与回退:代码回退不会撤销业务写入
发布单元不只是模型版本,还可能包括 Prompt、工具 Schema、状态结构、知识索引、权限配置和评测规则。
上线前需要检查旧任务能否在新版本恢复。状态字段变了、工具参数改了,仍在等待审批的任务可能不兼容。可以通过迁移、版本固定或兼容处理解决,但需要在演练中验证。
灰度观察应对照固定指标与关键失败案例。发现模型质量退步,可以回退后续调用配置;已经发生的补发或退款需要独立业务核对,不能指望部署回滚自动恢复资产。
回退还可能涉及知识索引版本与缓存失效。记录任务实际使用的配置,才能知道某个结果来自哪一套系统。
八、上线评审需要哪些证据?
8.1 把“做了功能”改成“在什么范围验证了什么”
| 评审问题 | 需要的证据 | 不能替代它的东西 |
|---|---|---|
| 能否完成目标任务 | 代表性真实模型评测、逐案失败分析 | 一次成功聊天 |
| 是否隔离用户与租户 | 认证与授权集成测试、检索和缓存隔离验证 | Prompt 写了不许越权 |
| 审批是否有效 | 身份、范围、期限、撤销和重复事件测试 | 一个 approved 字段 |
| 恢复是否正确 | 崩溃、并发、未知业务结果和对账演练 | 单次读取 Checkpoint |
| 成本是否可控 | 实测用量、未知用量处理与并发预算测试 | 只看公开单价 |
| 故障能否追查 | Trace、业务审计、版本与复现路径 | 只有最终错误文本 |
| 谁负责持续运行 | 告警、处置步骤、值守与回退演练 | 有一个监控页面 |
评审不是要求所有风险消失,而是让开放范围、已验证能力和未解决问题相匹配。遇到关键缺口,应缩小产品开放能力或补齐证据,不能用免责声明代替执行控制。
8.2 教学项目当前能提供什么证据?
| 篇目 | 本地已经实现的验证方向 | 仍需真实环境验证 |
|---|---|---|
| 06 状态与恢复 | SQLite 持久化、进程退出恢复、重复与并发写入保护 | 远程账务结果不确定、多机存储与灾备 |
| 07 RAG | BM25、RRF、引用回溯、指标与范围过滤 | 学习型 Embedding、重排和模型回答质量 |
| 08 LLM Eval | 逐案判分、修复与回归、CI 退出码 | 真实样本覆盖、模型波动与 Judge 校准 |
| 09 Model Gateway | 脚本重试、Fallback、虚拟时限和预算预留 | 真实 HTTP、供应商用量、并发配额 |
| 10 可观测性 | 单进程 Span、错误定位与受控字段 | 分布式传播、平台接入、采样与保留 |
| 11 安全与可靠性 | 模拟身份下的隔离、审批范围、有效期与事务恢复 | 真实认证、完整审批生命周期和外部系统集成 |
这些脚本验证了重要机制,但它们不是一个已经部署的统一服务。本文架构图中的 API、队列、真实认证、远程模型与业务服务集成,仍属于参考设计范围。
因此,当前结论应该是:适合教学、架构讨论和受控本地演示;尚不足以证明可以直接承接真实用户的资产操作。
8.3 怎样逐步开放能力?
可以先在测试数据与内部环境验证,再开放有权限的只读查询;有充分证据后允许创建申请;最后才考虑接入真实审批与业务写入。
每一步都要列出验收条件与回退方式。只读不等于没有风险,仍可能泄露数据或给出错误建议;写入则进一步要求更严格的授权、幂等和核对机制。
这里描述的是能力开放顺序,不是承诺某个固定时间表。实际节奏由验证结果决定。
九、一次架构评审可以怎样讨论?
9.1 先让团队走完一条正常路径
以订单 1001 为例,从用户登录、查询订单、检索规则、创建申请、批准到实际入账,逐步说明每次读取和写入由谁完成,使用什么身份与标识。
如果某一步只能回答“Agent 会处理”,就继续追问:具体由哪个后端模块调用哪个接口,保存什么状态,失败后由谁重试。
9.2 再在关键位置插入故障
分别假设模型没有返回、文档已经过期、工具返回另一张订单、审批被撤销、账务成功后 Worker 崩溃。
要求设计给出可执行的后续路径。不是每种情况都要自动完成,但不能丢失任务、误报成功或重复产生资产效果。
9.3 最后核对证据与风险负责人
对照评测、测试、压力测试和演练报告,确认结论对应当前代码、模型和数据版本。列出未验证项与负责补齐的人,避免“已讨论”被误记成“已实现”。
参考评审记录可以写成:
拟开放范围:内部只读订单查询,禁止资产写入。
已验证证据:认证资源权限测试、固定版本模型评测、查询超时演练。
待补证据:高峰负载、知识更新延迟、观测数据访问权限。
异常处理:查询失败明确返回未完成,保留任务标识供人工排查。
放量条件:待补项通过既定门槛,关键失败案例无未处置回归。
这是填写方式示例,不是对本教学项目已经完成这些真实环境验证的声明。
十、面试视角:怎样讲清一套 Agent 系统?
可以围绕一条完整请求组织回答:
我会先定义系统允许处理的任务与业务边界。入口验证用户和租户,任务服务保存可恢复状态。Runtime 根据当前阶段构建上下文,调用模型网关取得建议,再通过受控工具执行器访问业务系统。知识问答由检索提供证据,实时订单事实来自业务接口。涉及资产写入时,绑定具体范围的人工审批和业务幂等是必要约束。故障后依据检查点与实际业务结果恢复,不能只看模型说了什么。上线前用代表性评测、权限与恢复测试、性能成本数据和运行处置流程评审开放范围。
接着准备接受追问:为什么选择单 Agent,哪些步骤固定,如何处理远程写入超时,怎样发现模型升级的回归,数据与任务在哪一层隔离。
如果自己的实践仅限于本系列,可以如实说“我做过这些教学验证和架构推演”。不要把本地 Mock 描述为线上项目,也不要编造真实生产流量或事故经验。
十一、最后检查自己的理解
试着不看前文,回答下面三个问题:
- 模型、Runtime、Gateway、Tool Executor 和业务系统各自决定什么?哪一层有权改变余额?
- 任务状态显示未完成,但远程业务已经成功,系统怎样避免重做?
- 你手里的测试报告能支持哪种开放范围,哪些结论还缺乏证据?
能回答术语定义只是开始。更重要的是能够指出每个设计决定的依据与局限,面对新故障时仍然能推导出合理处理方式。
如果回答第二题时只说“保存 Checkpoint”,需要回到状态恢复;如果第一题把模型输出当成授权,需要复习工具与审批;如果第三题只看总通过率,需要复习 Eval 与上线评审。
十二、系列收束:把知识变成可检查的设计
从 Function Calling 到系统评审,我们一直在拆解同一个问题:用户表达一个目标之后,系统怎样在信息不完整、模型可能出错、外部服务可能失败的情况下,继续完成允许的工作。
工具调用连接模型与程序,Agent Loop 组织反馈,架构模式安排决策,Context 与 RAG 提供依据,State 和 Checkpoint 保存进度,Gateway 管理模型调用,Eval 与可观测性提供质量证据,权限、审批和幂等保护业务结果。
这些能力只有放回同一条请求路径中,才能看出彼此怎样配合。设计的好坏不取决于图里有多少组件,而取决于是否讲清楚职责、约束、失败路径和验证依据。
参考资料
实践:用现有项目做一次评审
本篇不新增一个只有外壳的“完整系统”。可以使用系列配套验证命令检查现有示例,再根据上面的能力矩阵写出自己的上线评审结论。
在本项目的 demo 目录运行:
python3 verify_series.py
它运行 06—11 的配套测试,并检查这些文章的附录与脚本是否一致;报告写入 verification-report.json。这是本地教学验证入口,不会连接真实模型或发布服务,也不代表生产验收。
然后选择一个尚未验证的真实能力,例如模型参数生成、远程账务幂等或知识更新后的检索效果,写清楚要收集什么证据、怎样判断通过。把“不知道是否可靠”变成一个可以执行的验证问题,就是这一阶段最有价值的收获。
到这里,《Agent开发》00—12 的主题已经串成一条完整学习路线。后续无论使用什么框架,都可以先回到这些问题:模型看到了什么,程序允许它做什么,实际发生了什么,失败后怎样继续,以及我们凭什么相信它正确。