Agent 如何上线？从 API、状态外置到灰度回滚
内容摘要：把 Agent 从脚本变成可运维的生产服务，需要：清晰的 API、无状态化 + 外置状态、容器化、伸缩、配置/密钥管理、灰度与回滚。本章给出工程要点与生产检查清单。 难度：高级 |前置知识：09 状态、15 可靠性、17 可观测性
常见误区
把本地 Agent 脚本包进容器、暴露一个同步 HTTP 接口，就完成了生产部署。
先给结论
生产 Agent 应把计算实例做成可替换的无状态执行器，将任务状态、Checkpoint、队列和审计外置；同时具备鉴权、限流、异步任务、灰度、版本绑定、回滚与资源隔离。
带着这三个问题阅读：
- 短请求与长任务的 API、超时和状态查询应如何设计？
- 模型、Prompt、工具与 Schema 版本怎样共同参与灰度？
- 扩缩容和故障恢复时如何避免丢任务或重复副作用？
一、部署架构总览
核心原则：Agent 服务进程无状态，所有状态外置到 DB/队列，这样才能水平伸缩、随时重启、故障恢复。
二、API 设计
python
# 伪代码：异步任务接口骨架
# POST /agent/tasks {goal} -> {task_id, status: "accepted"}
# GET /agent/tasks/{task_id} -> {status, result?, trace_id}
# POST /agent/tasks/{task_id}/approve {decision} -> 人工审批回调（带外确认，13）三、配置与密钥管理
- 密钥只从环境变量/密钥管理服务注入，绝不入代码/镜像/日志（14、17）。
- Prompt、模型名、预算、白名单等外部化为配置，支持不改代码热调整（与"Prompt/配置外部化"一致）。
- 固定依赖版本（模型/框架/SDK/MCP 协议版本），避免"隐式升级"引入行为漂移。
四、容器化与伸缩
- 容器固定运行环境与依赖版本；镜像不含密钥。
- 按 CPU/队列长度伸缩；模型调用是 IO 密集，注意并发与下游限流的匹配（15）。
- 优雅停机：收到停止信号后停止取新任务，等在途任务 checkpoint 后退出。
五、灰度发布与回滚
模型/Prompt/框架的变更都可能改变行为（非确定性），必须可灰度、可回滚：
- 把"模型版本 + Prompt 版本 + 框架版本"作为一个可回滚单元。
- 回滚阈值提前定义（成功率下跌、成本突增、注入拦截异常）。
六、失败路径
- 有状态进程 → 无法伸缩、重启丢任务。
- 密钥进镜像/日志 → 泄露。
- 无灰度直接全量 → 模型/Prompt 变更引发大面积回归。
- 依赖版本浮动 → 某天行为突然变化难以定位。
七、测试与验证
八、安全与权限
- 网关鉴权限流、最小权限、密钥隔离与轮换、审计日志（14）。
九、性能与成本
- 伸缩策略与预算护栏联动，避免高峰烧钱（18）。
十、生产检查清单
- [ ] 最小权限：读写分离、每工具最小作用域
- [ ] 人工审批：高危操作 propose/execute（13）
- [ ] 幂等控制：写操作幂等键（15）
- [ ] 超时与重试：有上限、只重试可恢复错误
- [ ] 状态持久化：外置 DB，可恢复（09）
- [ ] 故障恢复：崩溃续跑、优雅停机
- [ ] 审计日志：谁在何时做了什么（脱敏）
- [ ] 成本预算：单任务硬上限（18）
- [ ] 模型降级：主备切换（18）
- [ ] 灰度与回滚：可灰度、阈值回滚
十一、框架差异
- LangGraph Platform、各云的 Agent 托管、自建 FastAPI + 队列都可行。无论哪种，本章的"无状态 + 外置状态 + 灰度回滚"原则通用。
十二、关联章节
面试复述
Agent 上线不只是容器化。需要异步任务协议、外置状态与队列、版本化配置、密钥管理、可观测性、灰度回滚，以及与幂等和审批一致的恢复策略。
复述时先给结论，再补机制、适用边界和一个可验证指标；不要只罗列框架名称或产品功能。
迁移练习
为一个预计运行 5 分钟的 Agent 设计提交、查询、取消和审批 API，并说明实例重启、版本回滚与重复回调时的处理方式。
检索关键词
Agent 生产部署 无状态 外置状态 容器化 伸缩 灰度发布 回滚 密钥管理 生产检查清单
官方来源
- 各框架部署文档、云厂商 Agent 托管文档、十二要素应用（Twelve-Factor App）作为工程对照（
verified_at: 2026-09-07）。