跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 11

11-01|Production Architecture:真实 Agent 系统如何运行

把 V1.0 RC 放进真实请求链,明确 Frontend、API、Agent Service、数据与外部系统的生产责任。

Production Architecture · Deployment · Reliability

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

图 1|Frontend 接受交互,API 建立可信边界,Agent Service 编排,业务系统保存事实。

Frontend 不保存服务端 Secret,也不决定权限。API 层处理身份、限流、请求大小和基础校验。Agent Service 运行 Loop、组装 Context、调用 RAG 与 Tool。Database 保存 Workflow State、审批、幂等键和运行记录;订单、物流与退款事实仍由各自业务系统负责。

什么需要持久化

Stateless compute

请求解析、模型调用、Tool 编排;实例可被替换

Business state

refund status、approval、idempotency;事务化保存

Conversation context

受控短期材料;按任务恢复和裁剪

Knowledge index

版本化文档与 metadata;可重建、可追溯

Evidence

Trace、Audit、Eval Result、部署版本

Secrets / Config

运行时注入;按环境分离并可轮换

图 2|进程可以消失;业务 State、授权证据和幂等记录不能跟着消失。

Agent 请求可能持续数秒,也可能在 Human Approval 暂停数小时。系统应把可恢复状态写入数据库,使用稳定 runId / workflowId 重新加载,而不是依赖某台机器内存。重试只能发生在已定义的安全边界内;具有副作用的 Tool 需要幂等键和结果记录。

失败如何被隔离

Model timeout
停止当前调用,可控重试或安全降级
Order API unavailable
不猜订单状态;返回可重试错误或转人工
Database unavailable
禁止推进有副作用 Workflow
Trace exporter failure
业务路径按策略运行,同时告警并缓冲有限证据
One bad deployment
Health Check 失败,不接流量并触发回滚
图 3|每种依赖失败都要有边界、用户结果、告警和恢复动作。

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。

主动回忆

  1. Agent Service 可以保持无状态到什么程度?
  2. 哪些数据必须在进程之外持久化?
  3. 为什么 Human Approval 需要可恢复 Workflow?
  4. Tool timeout 后系统为什么不能让模型猜结果?

下一课把这张架构图变成可重复构建的容器、环境配置和部署流水线。

延伸阅读 / Sources

核查日期:2026-10-18。

长期有效的原理: 运行计算可以替换,业务状态、授权与证据必须持久且可恢复。当前实现方式: 部署平台可以变化,服务责任、数据所有权和失败契约应保持清晰。