在 Jupyter Notebook 中调用 await team.run(task="写一首诗") 得到一段文字回复，和在生产环境中每秒处理数百个并发请求之间，横跨着一条巨大的鸿沟。这条鸿沟里充斥着：流式响应如何通过 HTTP 暴露？多 Agent 的状态如何持久化？多个 Team 之间如何通信和隔离？当 LLM 调用超时或者 API 密钥过期时，系统如何优雅降级？
AutoGen v0.4+（autogen-agentchat 包）提供了所有必要的构件——ChatAgent 抽象、TaskRunner.run_stream() 流协议、Team.save_state()/load_state() 状态管理接口——但把这些构件组装成一个真正可投入生产的系统，需要深入理解其内部工作原理。本指南将带你走完全程。
我们假设你已经熟悉了 AutoGen 的基本概念（Agent、Team、TerminationCondition），并且有一个在 Jupyter Notebook 中能正常运行的原型。我们将逐步将这个原型改造为一个生产就绪的 API 服务，包括 FastAPI 端点、SSE 流式传输、Redis 状态持久化、Docker 容器化部署和 LangFuse 可观测性。
| 层级 | 技术 | 职责 |
|---|---|---|
| API 网关 | FastAPI + SSE | HTTP 端点、认证、限流 |
| 状态管理 | AgentRuntime + AgentState | 跨进程状态持久化 |
| 数据存储 | Redis + Postgres | 状态存储 + 对话历史 |
| 容器编排 | Docker Compose | 环境隔离 + 扩缩容 |
| 可观测性 | LangFuse | 追踪 + Token 监控 |
开发阶段的 AutoGen 应用通常只有一条执行路径：RoundRobinGroupChat → team.run() → TaskResult.messages。这是一个纯粹的单进程、内存态模型。生产系统需要在同一个架构上叠加 API 网关、流式传输、持久化和可观测性。关键的架构洞察：AutoGen 的 Team 本身是一个有状态的异步生成器——每次调用 run() 或 run_stream() 都会从当前状态继续执行。这意味着：会话持久化（通过 save_state() 跨进程恢复）、流式能力（run_stream() 天然适合 SSE 包装）、Team 嵌套（形成 Team-of-Teams 分层架构）。
理解这个架构的关键在于认识到：AutoGen 的生产部署本质上是一个"序列化与反序列化"的问题。你需要在每次请求结束时将 Team 的状态序列化到外部存储，在下次请求开始时反序列化恢复。Team 的 save_state() 返回 TeamState Pydantic 模型，天然支持 JSON 序列化，可以直接存入 Redis 或 Postgres。
生产环境中，用户不会直接调用 Python API——他们通过 HTTP 端点触发 Agent 执行。AutoGen 的 TaskRunner.run_stream() 返回一个异步生成器，天然适合通过 Server-Sent Events (SSE) 协议逐条推送消息给 HTTP 客户端。SSE vs WebSocket 设计决策：AI Agent 推理流场景推荐 SSE（纯单向输出、内置自动重连、标准 HTTP LB），WebSocket 适合需要双向通信的场景（如 Agent 需要用户输入）。
定义 Agent 和 Team：使用 AssistantAgent 和 RoundRobinGroupChat，设置 MaxMessageTermination 和 TextMentionTermination 组合终止条件。SSE 包装器实现：将 run_stream() 的 BaseChatMessage 和 BaseAgentEvent 事件映射为 SSE event: message 和 event: agent_event 格式。REST 端点：GET /api/agents/sessions/{id} 查询会话，DELETE /api/agents/sessions/{id} 清理 Team 实例。
SSE 流的关键实现细节：使用 StreamingResponse 包装异步生成器，设置 media_type="text/event-stream" 和 Cache-Control: no-cache 头。每个事件遵循 SSE 格式：event: {type}\ndata: {json}\n\n。客户端使用浏览器原生的 EventSource API 或 fetch 读取流。生产环境建议在 SSE 流上叠加心跳事件（每 15 秒发送 : keepalive 注释）防止代理超时断开连接。
AutoGen 的 Agent 是有状态的——BaseChatAgent 明确指出："An agent is considered stateful and maintains its state between calls to the on_messages or on_messages_stream methods." 生产环境中，Agent 状态需要跨进程持久化。AutoGen 的状态系统基于 Pydantic 模型，定义在 state/_states.py：BaseState（基类）→ AssistantAgentState（LLM 上下文）→ TeamState（聚合所有 Agent 状态）→ BaseGroupChatManagerState（消息线程 + 当前轮次）。
save_state() 的工作原理：遍历每个参与者，调用 runtime.agent_save_state()，也保存 Manager 的状态。自 v0.4.9 起，状态使用 Agent 名称作为键，使得状态可以在不同的 Team 实例和 AgentRuntime 之间移植。数据库持久化方案：使用 Redis 存储 Team 状态（TeamRegistry 模式），Postgres 存储对话历史用于审计和分析。
Redis 作为状态存储有一个关键优势：自动 TTL 过期。你可以为每个 Team 实例设置 TTL（如 30 分钟），避免状态泄漏导致的内存泄漏。Postgres 存储的对话历史则可以永久保留，便于后续的审计、分析和模型微调数据采集。建议在 save_state() 之后异步将对话历史写入 Postgres，避免阻塞主流程。
真实场景中，单个 Team 通常不足以覆盖复杂的业务需求。AutoGen 支持 Team 嵌套——BaseGroupChat 的 participants 参数可以同时接受 ChatAgent 和 Team 实例。Team-of-Teams 架构示例：一个协调 Team 管理两个子 Team（一个负责研究，一个负责写作）。子 Team 之间通过 HandoffMessage 实现跨 Team 通信和任务委派。资源隔离策略：每个 Team 独有的 SingleThreadedAgentRuntime（天然隔离）、共享或独立模型客户端、按 session_id 分片状态存储。
扩缩容考虑：垂直扩展（传入自定义 AgentRuntime 共享运行时）、水平扩展（通过 save/load_state 在多进程间迁移 Team）、会话亲和性（有状态模式需确保同一 session_id 路由到同一进程）。推荐模式：无状态 + Redis 状态存储——每次请求根据 session_id 从 Redis 恢复 Team 状态，执行完毕后立即保存。
水平扩展的最佳实践是使用"无状态 Worker"模式。每个 Worker 进程不持有任何本地状态，收到请求后从 Redis 加载 Team 状态、执行、保存、返回结果。这样任意 Worker 可以处理任意请求，无需会话亲和性。当需要扩容时，只需增加 Worker 实例数量，前置负载均衡器自动分发请求。
Docker 部署：多阶段构建（Python 3.12-slim），docker-compose.prod.yml 包含 FastAPI 应用 + Redis（状态持久化）+ Postgres（对话历史）+ LangFuse（可观测性）。LangFuse 集成：通过 LangFuseTracker 类追踪 Agent 执行轨迹，记录每个 Agent 调用的输入、输出、模型和 token 用量。错误处理：使用 retry_on_llm_error 装饰器，对 429/500/502/503 进行指数退避重试。速率限制：每用户每分钟 10 次（slowpi 库），API Key 认证（FastAPI Security）。成本追踪：通过 models_usage 字段计算每轮对话的 token 成本和总费用。
LangFuse 的追踪数据特别有价值：你可以看到每个 Agent 调用了多少次 LLM、每次调用的延迟、使用了哪些工具、工具执行结果如何。这些数据不仅用于调试——它们还可以帮助你优化系统设计。例如，如果你发现 Researcher Agent 的 Tool Call 失败率高于 30%，可能需要改进工具的实现或降低 Agent 对工具的期望精度。
将 AutoGen Agent 投入生产前，请逐项检查：安全清单——API Key 认证、速率限制（5-20 req/min）、LLM API Key 环境变量注入、Pydantic 输入验证、max_turns（建议 20）、CORS、HTTPS、审计日志。性能优化——模型客户端复用（共享连接池）、只在必要时调用 save_state()、优先使用 run_stream()、Redis/Postgres 连接池。监控设置——请求延迟 p95（>30s 告警）、Token 消耗/小时（超预算 120% 告警）、Agent 轮次数（单次 >15 轮告警）、错误率（>5% 告警）。
常见部署陷阱：有状态 Team 的并发问题（每个请求独立 Team 实例）、状态序列化的循环引用（model_client 不可序列化，需重新提供）、无限循环与 Token 耗尽（同时设置 max_turns 硬限制和 TerminationCondition 软限制）、Team 嵌套的 ID 冲突。
生产环境的一条黄金法则：永远不要在生产中复用开发环境中的模型客户端。每次请求应该创建新的模型客户端实例，或者从连接池中获取。多线程共享同一个模型客户端可能导致 API 调用冲突、速率限制计数不准和 Token 计费混淆。