Rivet Agents 完全指南:让每个 AI Agent 成为记忆持久的独立进程
Rivet Agents 完全指南:让每个 AI Agent 成为记忆持久的独立进程
Rivet Agents 是 Rivet 官方开源的 AI Agent 基础设施:它让每个 AI Agent 成为一个记忆持久的独立进程(Rivet Actor),对话在重启、崩溃甚至部署后都不会丢失,而工具则在独立沙箱中安全执行。本文带你完整了解它的架构、快速上手方法,以及多 Agent 应用的设计模式。
解决什么问题:无状态 Agent 的三大痛点
大多数 AI Agent 应用都面临同样的困境:
- 重启即失忆:Agent 的会话只存在于内存里,进程一挂,对话历史全部丢失,用户只能"重新来过"。
- 工具运行不安全:Agent 可以执行 shell 命令、读写文件,如果直接跑在你的服务器上,一个失控的命令就可能拖垮整个后端。
- 成本不可控:为每个用户常驻一个 Agent 进程,内存开销巨大;但用完即弃又丢掉了记忆。
Rivet Agents 的思路非常直接:把 Agent 变成一个"持久进程"——它像 Rivet Actor 一样运行在你的后端中,拥有自己的内存和 SQLite 数据库;空闲时自动睡眠释放内存,下次唤醒只需约 12 毫秒,会话从 SQLite 中恢复;而它执行的工具调用则被隔离到 E2B、Daytona 等沙箱中。
核心架构:一条消息的完整旅程
理解 Rivet Agents,只需要记住三个角色:
| 角色 | 职责 | 运行位置 |
|---|---|---|
| Agent Actor | Agent 主循环:调用模型、管理会话、重试与压缩 | 你的后端(可信区) |
| SQLite | 保存完整会话历史和沙箱 ID | 你的后端(Actor 自带) |
| Sandbox | 执行 Agent 的 read、write、bash 等工具 |
E2B / Daytona 等独立沙箱 |
一个 prompt 到来后,Agent 开始一轮运行:调用模型 → 模型要求执行工具 → 工具调用被发送到沙箱执行 → 结果回传给模型,如此循环直到模型不再调用工具。整个过程中,事件会实时流式推送给所有连接的客户端(比如聊天界面)。
安全模型的关键点:模型 API 密钥永远留在你的后端,绝不进入沙箱。沙箱只能收到"要执行的命令"和"要读写的文件",文件工具也被限制在工作目录内。
快速上手:4 步运行第一个持久 AI Agent
第 1 步:安装依赖
npm add @rivet-dev/pi rivetkit
@rivet-dev/pi 就是 Agent 本体(Pi 编码 Agent 的持久化封装),rivetkit 是 Rivet 的后端框架。
第 2 步:定义 Agent Actor
在你的后端代码中定义一个 Actor,指定模型(如 model: "anthropic/claude-sonnet-4-5")和密钥。完整示例见 examples/docs/pi/server.ts 和 examples/docs/quickstart/server.ts。
第 3 步:挂一个沙箱
# E2B 或 Daytona 二选一
npm add @rivet-dev/sandbox-adapter e2b
不配置沙箱时,Agent 的内置文件/shell 工具会被自动禁用,它就只能使用你传入的自定义工具——这是一种很好的"最小权限"默认行为。适配器实现位于 packages/sandbox-adapter/。
第 4 步:发送提示词
客户端像调用任何 Actor 一样调用 getOrCreate(用 key 区分不同 Agent),然后调用 prompt 发送提示词、getLastAssistantText 读取回复。示例见 examples/docs/quickstart/client.ts。
记忆如何存活:睡眠、崩溃与部署
这是 Rivet Agents 最核心的卖点。Agent 在四种状态间流转:
Idle ──prompt──> Running ──上下文写满──> Compacting
│ │ ▲
│idle │ └────完成/取消────┘
▼
Sleeping ──下一次调用──> Idle(从 SQLite 恢复会话,重连沙箱)
| 发生了什么 | 会话 | 沙箱 |
|---|---|---|
| 睡眠 | 完整保留在 SQLite | 挂起,唤醒后重连 |
| 崩溃 | 崩溃前已写入的消息都在 | 唤醒后重连 |
| 部署新版本 | 完整保留(旧 Actor 有 30 分钟收尾时间) | 重连 |
| 显式销毁 | 删除 | 删除 |
数字很有说服力:一个运行中的 Actor 仅比会话本身多占约 72 KB 内存,睡眠时占用 0,唤醒耗时约 12 ms,同机房内一次工具调用增加约 10 ms。这意味着你可以放心地"给每个用户、每个线程、每个任务各开一个 Agent",而不必担心成本爆炸。详细的状态机说明见 docs/content/docs/architecture.mdx。
多 Agent 设计模式:从"每用户一个"到协作网络
因为每个 Agent 就是一个 Actor,Rivet Agents 提供了一整套现成的设计模式(完整文档:docs/content/docs/design-patterns.mdx):
- 🔑 按 Key 分 Agent:Key 决定哪次对话延续哪段记忆。按用户(个人助理)、按 Slack 线程(每个话题独立)、按任务(修完一个 issue 就
destroy掉)都是常见选择。 - 👥 主 Agent + 子 Agent:主 Agent 把专注任务交给自带独立工具的特工,特工在干净上下文中工作,只把答案带回来。示例见 examples/docs/subagents/。
- 📨 Agent 互发消息:不需要等待结果时,Agent 之间可以像 Actor 一样直接调 Action(例如 coder 调
requestReview()),消息在发送方消失后依然持久。 - ⏰ 定时 Agent:Agent 可以挂上 cron 调度,每天早晨自己醒来干活,干完继续睡。
- 🏢 租户共享凭据:以租户 ID 开头组 Key,同一租户的所有 Agent 共享一套模型登录态,互相隔离。
文档还特别列出两个反模式:全员共用一个 Agent(会互相阻塞、共享会话)和每次请求都换新 Key(记忆清零还留下大量僵尸 Actor)。
人在回路:让 AI Agent 等待人工批准
对 deploy、delete 这类高危操作,Rivet Agents 支持"批准后才能执行"的机制:工具内部检查一个 approval Actor,未批准就结束本轮(Agent 可以直接睡着等批准),前端弹出确认框,用户点批准后再 prompt 唤醒 Agent 重试。由于检查写在工具里,模型无法绕过。实现见 examples/docs/human-in-the-loop/deploy.ts 与 docs/content/docs/human-in-the-loop.mdx。
实时事件流与可观测性
一次运行会持续产生结构化事件:agent_start、turn_start、message_update(流式输出)、tool_execution_start、compaction_start 等。客户端可以中途连上、中途取消,也可以用 steer(text) 在运行中"插话"、followUp(text) 排队追问、abort() 取消运行。完整事件清单见 docs/content/docs/session-lifecycle.mdx。
可观测性方面,每次运行都会生成带 OpenTelemetry GenAI 属性 的 invoke_agent pi span,可直接导出到你现有的可观测平台——且不会记录提示词正文和工具参数。
仓库中还自带一个强大的 Inspector 调试工具,可以实时查看 Agent 会话、事件流、请求日志和快照:
API Key 与凭据管理
Agent 从你的后端调用模型,密钥查找顺序是:
pi()传入的apiKeys选项credentialsActor(让用户用自己的 Claude / ChatGPT 订阅运行 Agent)- Worker 环境变量
无论哪种方式,密钥都不进沙箱。细节见 docs/content/docs/api-keys.mdx。
项目生态与资源导航
这个仓库实际上包含两大块,同一版本线发布:
- Rivet Agents:本文主角,把 Pi 编码 Agent 跑成持久 Rivet Actor,源码在 packages/pi/(运行时入口 packages/pi/src/runtime.ts)。
- Sandbox Agent:在沙箱中运行 Claude Code、Codex、OpenCode 等编码 Agent 并统一通过 HTTP 控制的通用 API,位于 sandbox-agent/。
除此之外,仓库还提供 Gigacode(复用 OpenCode 的 TUI 驱动任意编码 Agent,见 sandbox-agent/gigacode/)、React SDK(docs/content/docs/react-sdk.mdx)以及覆盖 Slack / GitHub / Discord 等场景的 Connector 示例(examples/docs/connectors/)。
常见问题
Rivet Agents 和直接用 LangChain 等框架有什么区别? 核心区别在"持久化":Agent 是一个有状态进程,会话落在 SQLite,睡眠零成本、毫秒级唤醒,而不是每次请求都从数据库重建上下文。
没有沙箱能跑吗? 可以。此时内置的 read/write/bash 等工具自动关闭,Agent 只能使用你在后端定义的自定义工具。
支持哪些模型? 使用 Pi 支持的任意提供商,通过 model: "provider/modelId" 指定,并可配置 scopedModels 允许客户端切换模型。
可以自托管吗? 可以。Rivet 为 Apache 2.0 开源,Worker 可跑在 Kubernetes、Railway、Render、云函数等任意环境。
总结
Rivet Agents 用"每个 Agent 一个持久进程"的简单模型,同时解决了 AI Agent 落地的三大难题:记忆跨重启存活、工具隔离执行、成本随用量伸缩。配合 Key 设计模式、人在回路和 OpenTelemetry 追踪,它几乎是把生产级 Agent 应用需要的积木都备齐了。想动手试试,从 docs/content/docs/quickstart.mdx 的 4 步快速上手开始即可。




