智能体后端的真实形状从提交到流式交付的八层参考架构

同步请求-响应是写Web服务时最自然的本能，对智能体应用却错在六个方向上，每一个都会在不同日子变成事故。它会把连接挂开两分钟、标签页一关就丢任务、网络抖动就重试一次0.2美元的操作、只给用户一个转圈而不给任何信息、无法取消、第97秒失败时前96秒的工作全部消失。

Part 1讲:AI Agents系统设计:把前沿模型扔进糟糕设计的智能体系统你只会得到更会说话的失败的是Harness本身：工具、提示、记忆、编排和评估。这一部分是真正跑起来的后端——一个可以直接拿来改的参考模板。例子用FastAPI，因为最常见，但原理不依赖任何框架。一切都从工作负载的四个属性推出来：耗时长、I/O密集、结果非确定、按单位计费。

我起初也按Web服务的习惯去写，后来在真实系统里一次次看到账单和用户投诉，才意识到必须先把这套本能杀掉。

先把项目分层摆清楚再写任何逻辑

路由里不含逻辑，只做验证、调服务、返回。整个代码库只有一个文件会import提供商SDK。如果openai出现在三个地方，你就没有接缝，后面想加限流、缓存、熔断都会变成灾难。

Layer 1：身份与隔离
每层都靠它做key。请求必须携带已验证的主体，“按租户”在没有验证主体之前毫无意义。三个现在便宜、以后昂贵的规则：永远按认证主体做范围，而不是客户端传的ID；任务ID用不可猜测的UUID4；租户要贯穿队列消息、worker上下文、缓存key、日志、追踪和预算。没有租户的缓存最终会把A客户的答案返回给B客户，测试里看不见，公网上不可挽回。

Layer 2：API表面
只要三个动词：提交、查询状态、取消。提交在工作开始前就返回，换来超时独立、标签页关闭后任务仍在、独立扩展、清晰的重试边界。Pydantic是第一道防线，extra="forbid"能抓住拼错的字段，边界检查能拦住100KB文档这种合法HTTP体却会毁掉提示的东西。提交做五件事，没有一件是智能体本身：校验、幂等检查、持久化、入队、返回句柄。幂等不是可选项，重复提交直接烧钱。先持久化再入队，顺序反过来会出现worker已经在跑、GET却404的情况。把状态机写下来，中间状态就是整个UX。awaiting_input是一等状态，给人机回路留位置，并设过期。取消需要真正的机制，而不是一个死URL；长步骤要把取消token传进模型层，好在生成中途就中止。

Layer 3：队列
它是承重墙：超时独立、独立扩展、背压降级而不是失败、明确的重试边界。至少三条队列：默认、优先（交互或付费层）、死信（人工检查，永不自动排空）。有两个客户就立刻加按租户公平。worker设置里，墙钟限制是唯一真实的后盾——框架递归限制只数轮次，不数秒。重试只针对传输（429、断连、503），永远不要重试推理本身。一个跑了十五分钟却什么都没产出的任务不是暂时故障。

Layer 4：Worker与并发
智能体worker有70%到95%的时间堵在网络套接字上，几乎不吃CPU。默认用进程×异步：每核一个进程做隔离，进程内高并发。陷阱是异步路径里冒出一个同步调用，整个事件循环就被卡住。用算术定规模，而不是感觉。到达率0.5/s、时长90s、每任务8次模型调用、提供商600 RPM，系统级并发上限大约112，稳态在飞45个。先抬高单worker并发（免费），再加worker。内存才是真正的单worker上限。SIGTERM会在每次部署、缩容、Spot回收时中途到来，把平台优雅终止时间设到p99任务时长以上，SIGTERM立刻让就绪探针失败，存活探针继续撑到排空完成。

Layer 5：模型调用层
几乎所有成本和可靠性都在这里。永远不要在智能体代码里直接调SDK，前面加一道接缝，让它干六件事：三级缓存（提示缓存杠杆最大，静态永远在动态前面，缓存key跟着提示版本走）、按任务路由（五步流水线通常只有一步需要前沿模型，其余下沉到小模型，成本可砍到原来的30%）、带抖动的重试并分类故障、熔断（开路时停止从队列取活，而不是快速失败）、跨提供商回退、连接池预热流式批处理。每任务设置花费上限，步骤之间检查。结构化输出先校验再修复一次，无界修复循环就是无界账单。

Layer 6：工具执行
工具是安全边界。模型生成的代码不能和凭证同进程执行。出口锁到白名单，屏蔽元数据端点和私有网段，每个工具加超时和输出上限。返回的一切都当不可信数据，不可逆动作必须过人审。副作用用(job_id, step, args)做幂等，密钥在工具边界注入，模型输出渲染前先消毒。

Layer 7：状态与会话
两个存储回答两个问题：热存储服务状态，持久存储服务历史，轮询路径永远不碰数据库。会话必须活过中断——刷新、换设备、worker挂掉。只活在进程内存的dict在第二个worker出现后立刻只剩一半可用。持久化三样东西、三种节奏：会话元数据、工作记忆摘要、完整历史。用会话做key，而不是连接。检查点保护应用失败，持久执行（Temporal一类）才能让工作流在另一台机器上续跑。现在就决定数据生命周期：按租户保留、调用提供商前脱敏、覆盖两个存储加追踪缓存的删除路径、追加式审计日志。

Layer 8：交付与流式
进度粗糙时用轮询，2秒一次对热存储，整任务生命周期大约50次便宜读取，任何网络事件都免费存活。token就是产品时才流式，SSE优于WebSocket。错误是直接从智能体进程流出去——这会重新把连接寿命和任务寿命绑在一起。中间缓冲：worker不管有没有人听都往流里写，API按需挂接。TTFT和tokens/sec才是真正的流式指标，总时长是错的。

控制平面贯穿所有层：限流按身份而不是IP、按token而不是请求数；API按请求率扩、worker按队列深度扩（永远不要按CPU）；可观测性要有关联ID、统一事件词汇、逐步追踪（token、延迟、成本、缓存状态）。

几乎没有一条是关于智能体本身的。换模型、换框架、换任务，这套后端形状不变，因为它直接来自工作负载的四个属性。这些属性不会消失。

按这个顺序建，而不是按感觉。离架模型网关能快速买到Layer 5，托管智能体平台能买到2-4、7和部分8，但调试时你依然要理解每一层。

你准备从身份隔离还是模型调用接缝开始，给自己的智能体后端补上第一道真正能挡住账单的骨架？

我是紫微AI，在做一个「人格操作系统（ZPF）」。后面会持续分享AI Agent和系统实验。感兴趣可以关注，我们下期见。