生产级 Agent 架构：从一次运行到持续运营

一个 Notebook 里的 Agent 只需要模型、Prompt 和几个工具。一个生产 Agent 还要面对身份、队列、状态、审批、恢复、评测、告警、发布和成本。

两者的差距，不是再换一个更强模型，而是能否长期运营：失败能被限制，状态能恢复，变更有证据，用户知道系统正在做什么，团队也知道何时必须接管。

这一讲把前面 21 篇的组件收拢成一套生产架构，并给出从试验到上线的渐进路线。

一、生产系统从“用户目标”开始，不从模型 API 开始

架构设计的第一项输入应该是任务契约：

用户要达到什么领域终态；
输入和输出是什么；
允许哪些副作用；
最坏影响范围；
多久必须完成；
何时需要人工；
用什么证据证明成功。

例如“生成退款建议”和“自动执行退款”看似只差一个 Tool Call，风险等级却完全不同。前者可以输出草稿，后者涉及身份、金额政策、批准、幂等和审计。

没有任务契约，系统很容易用模型能力替代产品边界。

二、生产级 Agent 的十层结构

1. Experience Layer

聊天、IDE、业务工作台、API 或后台任务。负责展示进度、工件、审批、错误和恢复入口，不只是显示流式文字。

2. Identity & Tenant Layer

解析用户、组织、租户、角色和委派关系。Agent 不应使用共享超级账号访问所有系统。

3. Orchestration Layer

管理状态机、Manager/Handoff/Parallel、预算、终止和人工节点。简单任务可以是代码 Workflow，长任务需要 Durable Runtime。

4. Context & Memory Layer

选择当前上下文，连接检索和长期 Memory，控制来源、敏感度、版本和过期。它决定模型“此刻知道什么”。

5. Model Gateway

统一模型调用、路由、限流、缓存、降级、版本和成本记录。业务代码不应散落未经治理的模型 Key。

6. Tool & Protocol Layer

Tool Registry、MCP Client/Server、A2A 或业务 API。负责 Schema、能力发现和连接，但业务授权仍在 Policy 与后端。

7. Policy & Approval Layer

校验资源、动作、参数、租户、数据级别和人工批准。策略应可版本化、可测试，并在副作用前执行。

8. Execution & Sandbox Layer

浏览器、代码运行、文件和第三方服务。通过容器、虚拟机、网络策略、短期凭据和资源配额隔离。

9. State & Artifact Layer

保存检查点、业务对象、幂等键、消息、Diff、报告和证据哈希。聊天历史不是唯一状态源。

10. Observability & Evaluation Layer

Trace、Metrics、Logs、Dataset、Eval、红队和发布 Gate。它们横跨所有层，而不是上线后补一个 Dashboard。

Google Cloud 的生产 Agent 指南同样把模型、工具、编排、状态、协议、评测和生产运营视为一套系统问题。[1]

Google Cloud 生产级 Agent 指南

图 1：官方生产指南强调 Agent 生命周期，而非单次 Prompt。来源见文末。

三、Control Plane 与 Data Plane 为什么要分开

Data Plane

处理一次具体运行：构建上下文、调用模型和工具、读取或写入业务数据。

Control Plane

管理模型、Prompt、工具、Policy、Eval Dataset、版本、发布、配额和审计配置。

如果控制配置直接散落在运行代码里，每次调整工具权限都要改应用；如果任何人能在控制台即时改 Prompt 和工具而没有版本与 Gate，线上行为又会失去可追溯性。

正确做法是：Control Plane 产生带版本的配置，Data Plane 在一次 Run 中固定使用，并把版本写入 Trace 和 Checkpoint。

四、同步请求与异步任务怎样分流

用户等得起几秒的查询，可以在同步请求内完成。研究、代码修复、批量处理和等待审批的任务，应进入异步运行系统。

异步任务需要：

稳定 run_id；
队列与并发限制；
持久化状态机；
心跳、超时与取消；
检查点与恢复；
进度事件；
最终工件和通知；
重复投递下的幂等。

“HTTP 连接一直开着”等待几十分钟，不等于 Durable Execution。连接断开后，任务仍应有明确状态和恢复入口。

五、模型路由不能只按单次价格

模型选择应结合：

任务复杂度和风险；
结构化输出与工具能力；
上下文长度；
延迟、地域和数据政策；
实际 Eval 结果；
每个成功任务总成本。

可以让便宜模型处理分类和简单提取，让通过业务 Eval 的模型处理规划，高风险终态由确定性验证器和人工控制。

降级也不能只把大模型换成小模型。如果小模型在关键工具路由上未通过 Gate，合理降级可能是只读、生成草稿或转人工。

六、Tool Registry 应保存哪些治理信息

生产 Tool 不只是名称和 Schema。注册信息至少包括：

owner                维护团队
version              契约版本
risk_class           read / write / irreversible
required_capability  所需权限
data_classification  输入输出敏感级别
idempotency          是否支持及键规则
timeout/retry        超时与可重试错误
approval_policy      何时人工批准
audit_fields         必须记录的字段
deprecation          下线日期与替代项

工具变更要跑契约测试和 Agent 回归，不能只保证 HTTP 还返回 200。

MCP 可以改善发现和连接，但 Registry 仍需记录组织级 Owner、风险和允许范围。

七、执行环境按风险分级

Level 0：无副作用

仅生成文本或结构化建议，不访问私有系统。

Level 1：受控读取

读取特定知识库、订单或仓库，按租户过滤，禁止外传。

Level 2：可逆写入

创建草稿、分支或待审批记录，能够清楚撤销。

Level 3：不可逆或外部影响

付款、发布、删除、发送、生产变更。需要强身份、预览、批准、幂等、验证和审计。

同一个 Agent 可以在不同步骤进入不同等级，但权限应随步骤临时授予，完成后收回。

OpenHands 的架构把产品界面、Agent 与 Runtime 分开，体现了 Coding Agent 需要独立执行环境这一工程事实。[2]

OpenHands 架构页面

图 2：Coding Agent 的能力来自模型与 Runtime、工具、状态共同组合。来源见文末。

八、数据和 Memory 的生产责任

上下文可能包含用户输入、检索文档、工具结果、Memory 和其他 Agent 工件。每一类都需要：

来源与用途；
租户和访问控制；
敏感级别；
保留与删除；
新鲜度与版本；
是否允许进入模型；
是否允许外发。

长期 Memory 尤其不能成为“不知道放哪就都存起来”的数据库。写入要有 Schema、作用域、过期和用户删除入口；检索要遵守当前身份与目的。

九、发布流水线怎样设计

Agent 变更包括模型、Prompt、工具、Harness、Policy、Memory 策略和检索索引。任何一项变化都可能让旧评测失效。

一条实用流水线：

静态检查与 Tool Contract Test；
单元测试状态迁移、策略和幂等；
固定 Dataset 离线 Eval；
高风险切片与安全红队；
影子流量或历史 Trace Replay；
小比例 Canary；
实时监控业务终态、人工接管和成本；
自动或人工回滚；
新故障沉淀为回归 Case。

每份 Evidence 要绑定当前代码、模型、配置和数据版本。任何关键组件变化，旧“测试通过”都可能失效。

十、Feature Flag 与 Kill Switch

生产 Agent 应能快速：

关闭某个高风险 Tool；
把写操作降级为草稿；
停止某个模型或 Server；
限制特定租户；
暂停新任务但允许安全收尾；
撤销临时凭据；
把任务转人工。

Kill Switch 需要真实演练。如果开关只改 UI，后台队列和长任务仍继续执行，就不是完整停止机制。

十一、运营面板看什么

不要用“模型请求数”代表业务价值。至少建立四组视图。

Outcome

已验证任务成功、部分完成、失败、人工接管及用户纠正。

Reliability

状态停留、重试、未知副作用、恢复、重复动作和下游可用性。

Risk

权限拒绝、批准、数据流、越权尝试、安全 Case 和事件。

Economics

每个成功任务模型费、工具费、基础设施费和人工时间，按任务与租户切片。

这些指标要能下钻到 Trace、Artifact 和具体版本，而不是孤立的漂亮曲线。

十二、团队与 Owner 怎样划分

生产 Agent 往往跨越产品、模型、平台、安全和领域团队。建议明确：

产品 Owner：定义用户目标和可接受失败；
领域 Owner：维护业务政策与终态；
Agent/Harness Owner：编排、上下文和验证；
Tool Owner：契约、权限、幂等和可用性；
平台 Owner：运行时、队列、状态和遥测；
安全/隐私 Owner：威胁模型、数据政策和事件响应；
Eval Owner：Dataset、Judge 与发布 Gate。

同一个人可以承担多个角色，但责任不能消失。尤其要明确谁有权批准高风险变更，谁在事故时停止系统。

十三、从原型到生产的四个阶段

阶段 A：只读助手

固定小任务，工具只读；建立 20：50 个业务 Eval 和基础 Trace。

阶段 B：受控草稿

允许生成 Draft、Diff 或建议，由人提交；增加沙箱、版本和成本指标。

阶段 C：低风险自动化

对可逆动作自动执行；加入持久状态、幂等、回滚、Canary 和 SLO。

阶段 D：高风险有条件自治

只有经过强 Eval、最小权限、绑定批准、实时监控和事件响应，才逐项开放。不是把 Level 3 总开关一次性打开。

每个阶段都由真实证据晋级，不由“模型看起来更强”晋级。

十四、20：40 分钟实践：做一次生产就绪评审

选一个已有 Agent 原型，创建下面的表，不改代码也可以完成第一轮：

用户终态：
最大副作用：
运行 Owner：
状态存储：
幂等/恢复：
最小权限：
人工节点：
Eval Case 数与关键切片：
Trace 与版本：
SLO：
Kill Switch：
事件响应：

给每项标记 ready / limited / missing，并要求 missing 项提供具体 Owner 和日期。

然后做一个演练：运行到外部写操作后断开网络，再重启进程。系统能否知道真实状态、避免重复，并让用户看到准确进度？如果不能，先不要扩大自动权限。

十五、常见的“伪生产化”

有向量数据库，却没有数据删除与作用域；
有多 Agent，却没有状态 Owner；
有 Trace，却没记录模型、工具和 Policy 版本；
有审批，却不展示具体参数；
有重试，却没有幂等；
有 Benchmark 分数，却没有业务终态；
有沙箱，却仍挂载宿主 Secret；
有 Dashboard，却没有告警和响应人；
有 Kill Switch，却从未演练。

生产化不是组件名齐全，而是每个风险都有可运行控制和可验证证据。

十六、这一讲的结论

生产级 Agent 是模型、Harness、工具、状态、身份、执行环境、政策、Eval 和运营共同构成的系统。

架构的核心不是追求最大自治，而是按任务风险逐级开放 Capability，并让每次变更、运行和失败都能被版本化、观察、验证和接管。

第五单元到这里结束。下一讲开始读源码：面对 OpenAI Agents SDK、LangGraph、PydanticAI、ADK、Microsoft Agent Framework 等项目，怎样避开 README 热闹，从五个入口读懂真正设计。

参考资料

[1] Google Cloud, A developer’s guide to production-ready AI agents. https://cloud.google.com/blog/products/ai-machine-learning/a-devs-guide-to-production-ready-ai-agents/

[2] OpenHands, Architecture. https://docs.openhands.dev/modules/usage/architecture

[3] OpenAI, A practical guide to building agents. https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/

[4] Anthropic, Building Effective AI Agents. https://resources.anthropic.com/building-effective-ai-agents

[5] OpenTelemetry, Generative AI Semantic Conventions. https://opentelemetry.io/docs/specs/semconv/gen-ai/

[6] NIST, AI Risk Management Framework. https://www.nist.gov/itl/ai-risk-management-framework