Agent 上线模板包

这个 pack 包含什么

这是一个真正的工程师在 agent 上线前那一周会装的套件 — 不是上线后第一个 OOM 把服务打挂时通宵抢救的那种。每个都是字面意义上的「部署模板」：clone 一个 repo、配几个 env、你就拿到一个能并发处理请求、能持久化状态、能沙箱执行不可信代码、进程挂了能恢复的 agent。开源优先、便宜，每层都能跟下一层串起来。

推荐安装顺序（骨架 → 状态 → 沙箱 → 队列 → 部署目标）

顺序是有讲究的。别一上来选部署目标 — 你会被平台特性逼着重写 agent。先在本地把骨架、状态、沙箱跑通，部署目标是最后一个决定。

1. 选一个 agent 骨架。想要 FastAPI 起服务 + sessions + tracing 都现成的「全套」runtime → Agno。想要更小、类型优先、Pydantic model 当 I/O 契约、HTTP 那层自己来 → PydanticAI。选一个，目标是拿到一个收请求返类型化响应的 /run 端点。先本地跑通。
2. 加工具之前先加状态存储。agent 一有 session，你就得找地方装 — 选 Upstash Redis（serverless、按请求付费、空闲不收钱）装 session/cache，Upstash Kafka（或任意托管队列）做工作队列（如果单轮可能超 30 秒）。别把 state 写到本地磁盘，下次 pod 重启全没了。
3. 不可信工具调用包到沙箱里。agent 一旦执行生成的代码、跑 shell、爬网页，就必须隔离。E2B 最低门槛 — from e2b import Sandbox; sbx.run_code(...) 一行就完事。Daytona SDK 是另一种：要长生命周期、可快照的开发工作区时（比如做长任务的 coding agent）用它。Modal Sandboxes 是同一种原语但跟 Modal 计算在一起 — 如果你也在 Modal 上部署，用它链路最短。
4. 请求是脉冲流量选 Serverless 模板。Modal（加 modal-examples 当参考 repo）给你一个 Python 装饰器变成 HTTP 端点，带 GPU、缩到零、按秒计费 — 适合请求集中爆发的 agent。Replicate Cog 把模型 + handler 打成一个容器，靠 cog.yaml 描述；如果你也要同时 serve 一个模型并想合并成一个部署 artifact，用它。
5. 多步或有状态的流程上 LangGraph。当 agent 是个多步图（规划 → 搜索 → 反思 → 回答）有分支、有人工介入时，LangGraph 给你显式状态 + checkpoint — 单轮崩了能恢复而不是从头来。把它的 checkpointer 绑到第 2 步里的 Redis。
6. 最后选部署目标。三条现实路径：(a) Serverless — 把 FastAPI app 包进 Modal @asgi_app、或 Replicate 的 cog predict，作为容器发布。(b) PaaS — 用 Dockerfile 推到 Fly/Render/Railway，稳定流量场景最便宜。(c) Kubernetes — 需要多租户、gVisor 级隔离，或者已经超出 PaaS 能力时，用 Agent Sandbox 当 k8s 跑 agent 的参考模式（每 session 一 pod、每工具调用一沙箱、网络策略默认拒绝）。

各部分怎么拼起来

[客户端]
   │  HTTP /run
   ▼
[FastAPI agent 骨架]   ← Agno 或 PydanticAI
   │
   ├─ session/cache  ──▶  Upstash Redis
   │
   ├─ 后台任务       ──▶  Upstash Kafka  ──▶  worker（同镜像）
   │
   ├─ 工具: run_code ──▶  E2B / Daytona / Modal Sandbox
   │
   ├─ 图状态         ──▶  LangGraph checkpointer (Redis)
   │
   ▼
[部署目标]  ── Modal @asgi_app  /  Replicate Cog  /  k8s (Agent Sandbox)

四件套组合 骨架 + 状态存储 + 沙箱 + 部署目标 是「最小可行生产 agent」。少哪一个都顶不过一周：没状态 → 用户骂失忆；没沙箱 → 幻觉调出的 rm -rf 干掉你的服务；没骨架 → 你又写了一遍 FastAPI 中间件还写得不如别人；没部署目标 → 你根本接不到流量。

你会遇到的取舍

• Agno vs PydanticAI — Agno 是更大的框架，sessions / FastAPI app / 集成 / tracing 现成；代价是你得忍受它的主张。PydanticAI 更小更类型优先，HTTP 那层你自己拼。两周要上线的团队 → Agno。已经有 FastAPI 约定的团队 → PydanticAI。
• E2B vs Daytona vs Modal Sandbox — E2B 是最低门槛的临时代码执行沙箱（Python SDK，默认安全）。Daytona 长项是需要持久化、可快照的工作区（长生命周期的 coding agent）。Modal Sandbox 是「你已经在 Modal」的最优解 — 同 auth、同账单、跟模型调用同机房延迟最低。
• Modal vs Replicate Cog vs k8s — Modal 缩到零、按秒计费、Python 即部署单元；脉冲流量最划算。Replicate Cog 是一个容器 + cog.yaml；同时 serve 模型 + agent 时合并部署最简单。Kubernetes（走 Agent Sandbox 模式）适合真需要多租户、gVisor 隔离、或者已经超出托管平台能力。
• LangGraph vs 手写状态机 — 单轮 agent（一次 LLM 调 + 工具）别拉 LangGraph 进来，纯负担。多轮图 + 分支 + 重试 + 人工介入，LangGraph 的 checkpointer 让崩溃可恢复，值这个体积。
• Upstash Redis vs 自托管 Redis — Upstash 是 serverless、按请求计费；超过 ~1000 万 commands/月 之后 $20 的 Redis VM 反而更便宜。迁移就是改个 URL。别提前优化。

常见踩坑

• session state 写本地磁盘或进程内存。下次 pod 重启全没了，用户骂你失忆。第一天就把 state 写进 Redis（或你的 DB），不是出事之后再改。
• 工具调用没沙箱。agent 第一次幻觉出 subprocess.run(['rm', '-rf', '/']) 而你的服务真跑了，生产集群就完了。只要工具包含 shell 或代码执行，E2B/Daytona/Modal Sandbox 不是可选项。
• Serverless 跑长 agent 轮次。大多数 serverless 有最大执行时间（Lambda 15min、Vercel 5min、Modal 最长 24h）。如果单轮可能 30+ 分钟，要么选 Modal（长超时），要么把活推进队列让 HTTP 请求立刻返个 job ID。
• FastAPI 骨架里没设请求级超时。没超时一次卡死的 LLM 调用就能把 worker 池耗干。HTTP 边界、LLM 客户端、工具调用三层都要显式设超时。
• 把完整 prompt + response 全打日志。开发期感觉很爽，生产环境 PII 漏进不合规的日志聚合器。截断、脱敏、采样后再打，完整 trace 留给 LLM observability（Langfuse、Phoenix）走访问控制。