AI Agent Engineering · Week 11
11-01|Production Architecture:真实 Agent 系统如何运行
把 V1.0 RC 放进真实请求链,明确 Frontend、API、Agent Service、数据与外部系统的生产责任。
localhost 隐藏了哪些问题
本地演示中,一个进程可以同时保存聊天、调用模型、读取 Mock 订单并输出结果。真实运行会遇到多用户并发、进程重启、网络超时、凭据隔离、版本切换和跨服务追踪。生产架构的目标,是让每项责任拥有明确边界、持久状态和失败处理。
生产请求链
Customer Frontend
↓ HTTPS
API / Identity / Rate Limit
↓ trusted subject
Agent Service
├─ Model Provider
├─ RAG / Knowledge Index
├─ Workflow + Approval
└─ Tool Runtime → Order / Logistics / Refund APIs
↓
Database + Trace + Audit + Metrics
Frontend 不保存服务端 Secret,也不决定权限。API 层处理身份、限流、请求大小和基础校验。Agent Service 运行 Loop、组装 Context、调用 RAG 与 Tool。Database 保存 Workflow State、审批、幂等键和运行记录;订单、物流与退款事实仍由各自业务系统负责。
什么需要持久化
请求解析、模型调用、Tool 编排;实例可被替换
refund status、approval、idempotency;事务化保存
受控短期材料;按任务恢复和裁剪
版本化文档与 metadata;可重建、可追溯
Trace、Audit、Eval Result、部署版本
运行时注入;按环境分离并可轮换
Agent 请求可能持续数秒,也可能在 Human Approval 暂停数小时。系统应把可恢复状态写入数据库,使用稳定 runId / workflowId 重新加载,而不是依赖某台机器内存。重试只能发生在已定义的安全边界内;具有副作用的 Tool 需要幂等键和结果记录。
失败如何被隔离
停止当前调用,可控重试或安全降级
不猜订单状态;返回可重试错误或转人工
禁止推进有副作用 Workflow
业务路径按策略运行,同时告警并缓冲有限证据
Health Check 失败,不接流量并触发回滚
Failure Lab
把所有组件放进一个进程
为什么诱人: 部署简单,Demo 中调试方便。
为什么失败: 任一依赖卡住都会拖垮全部请求,重启还会丢失审批和 Workflow State。
更合理设计: 先分离责任和持久状态;是否拆成多个服务由规模、团队和故障需求决定。
把聊天历史当生产数据库
为什么诱人: 对话里似乎已经有订单、审批和退款信息。
为什么失败: 历史会被裁剪、总结或污染,无法提供事务、归属和审计保证。
更合理设计: 聊天是 Context 来源之一,业务事实与 Workflow State 保存在权威存储。
所有失败都自动重试
为什么诱人: 短暂网络错误经常会自行恢复。
为什么失败: 重复退款、请求风暴和成本放大可能随重试发生。
更合理设计: 按错误类型、幂等性、最大次数和退避策略决定重试;不可恢复错误立即停止。
实践:画出 V1.0 Production Boundary
为 Frontend、API、Agent Service、Database、RAG、Tool Runtime、业务 API 和 Observability 标出责任、数据、Secret、扩缩容、超时、重试、持久化和失败结果。
Acceptance Criteria
- ☐ Frontend、API、Agent Service、Database 与业务系统责任清楚。
- ☐ 身份与授权在进入 Tool Runtime 前建立可信链。
- ☐ Workflow、Approval、幂等和 Audit 可跨进程重启恢复。
- ☐ 订单与物流事实继续来自业务系统,不从聊天历史推断。
- ☐ 每个外部依赖都有 Timeout、Error Contract 和安全降级。
- ☐ 重试明确区分只读与有副作用操作。
- ☐ 部署版本可关联到 Trace、Eval 和 Security Report。
主动回忆
- Agent Service 可以保持无状态到什么程度?
- 哪些数据必须在进程之外持久化?
- 为什么 Human Approval 需要可恢复 Workflow?
- Tool timeout 后系统为什么不能让模型猜结果?
下一课把这张架构图变成可重复构建的容器、环境配置和部署流水线。
延伸阅读 / Sources
核查日期:2026-10-18。
- The Twelve-Factor App:Processes。用于核对无状态进程与持久数据边界。
- The Twelve-Factor App:Config。用于核对环境配置与代码分离原则。
- OpenTelemetry:Traces。用于核对跨服务 Trace 与 Span 的通用关系。
长期有效的原理: 运行计算可以替换,业务状态、授权与证据必须持久且可恢复。当前实现方式: 部署平台可以变化,服务责任、数据所有权和失败契约应保持清晰。