Appearance
Backpressure 与 Gateway Timeout
1. 为什么这组知识要一起学
理解 Agent 服务中的连接生命周期、超时层次、SSE/WebSocket 事件流以及断连后的取消和背压。
这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。
2. Mental Model
HTTP/Streaming 是 Agent 前后端的事件传输边界：先明确单向/双向、连接寿命、断线语义，再选 SSE/WebSocket。
text
Client → HTTP request → Agent Run → event producer → buffer/queue → SSE/WS/streaming response → disconnect/cancel/resume3. 核心机制
Backpressure
慢 consumer 必须限制 event buffer；代理可能有 idle/read timeout 和响应缓冲，需要 heartbeat/flush 或改成异步查询结果。
Proxy / Gateway Timeout
区分 validation、permission、not-found、transient upstream、timeout、semantic failure。Retry 只对明确可恢复错误，并受 deadline/retry budget 约束。
4. 最小实现 / 伪代码
下面代码只表达边界和生命周期，不要求照抄到项目中：
python
async def events(run_id):
async for event in runtime.subscribe(run_id):
yield f"event: {event.type}\ndata: {event.json()}\n\n"真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。
5. 在 Shadow Harness 中怎么落地
API 层只把 Runtime events 映射为 transport events；Run 不应依赖具体 SSE/WebSocket connection 才能存在。
建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。
6. Production Engineering 检查项
- connection/read/run timeout 分层
- disconnect 是否取消 run 要显式
- bounded event buffer
- 代理 idle timeout
- 事件有 id/type/version
7. Failure Modes
7.1 把 streaming 当作降低模型实际计算时间
当出现「把 streaming 当作降低模型实际计算时间」时，从 client→proxy→server→runtime 检查连接/读取/run timeout、事件 buffer 与 disconnect policy。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
7.2 client 断线后后台 task 泄漏
当出现「client 断线后后台 task 泄漏」时，从 client→proxy→server→runtime 检查连接/读取/run timeout、事件 buffer 与 disconnect policy。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
7.3 无 backpressure 导致内存增长
当出现「无 backpressure 导致内存增长」时，从 client→proxy→server→runtime 检查连接/读取/run timeout、事件 buffer 与 disconnect policy。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
7.4 用 WebSocket 解决本可 SSE 的单向问题
当出现「用 WebSocket 解决本可 SSE 的单向问题」时，从 client→proxy→server→runtime 检查连接/读取/run timeout、事件 buffer 与 disconnect policy。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
8. Trade-offs
SSE 简单且适合 server→client；WebSocket 双向能力强但状态/代理复杂；普通 JSON 适合短请求。
设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。
9. Experiment / Evaluation
模拟慢客户端、断线、代理超时和 run resume，验证事件顺序、资源释放与取消策略。
实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。
10. 常见问题
基础：Backpressure 最容易被误解的点是什么？
慢 consumer 必须限制 event buffer；代理可能有 idle/read timeout 和响应缓冲，需要 heartbeat/flush 或改成异步查询结果。
机制：这些能力在一次 Run 的哪个生命周期阶段生效？
沿着 Client → HTTP request → Agent Run → event producer → buffer/queue → SSE/WS/streaming response → disconnect/cancel/resume 找位置，并明确它的输入、输出、持久化事实和失败传播。
工程：如果这一层失败，应该由谁恢复？
先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。
设计：规模扩大 10 倍后，哪个假设最先失效？
优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。
11. Sources
12. 本文结论
掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。