ai-agent-workspace

AI Agent 工作区

重要：开始任何操作前，你必须先阅读此技能目录中的 BASE_SKILL.md。其中包含有关调试、错误处理、状态管理、部署和项目设置的重要指导。所有 RivetKit 工作都适用这些规则和模式。以下内容均假设你已阅读并理解这些内容。

可运行示例

如需参考实现，请阅读以下模板中的原始可运行示例代码：

• agent-os

为每个 AI Agent 提供独立计算机的模式，详见 agentOS：每个 Agent 对应一个 Rivet Actor，负责运行一个基于 Wasm 和 V8 的便携、轻量级进程内 OS。可用于在多次运行间保留状态的代码解释器、通过可共享预览 URL 发布产物的 Agent、按用户划分的开发环境，以及定时维护 Agent。agentOS 目前处于预览阶段，API 可能会发生变化。

本文介绍如何为 Agent 提供工作区。有关对话记忆、消息队列和流式聊天模式，请参阅 AI Agent。

入门代码

agent-os 集合是参考代码，每项功能各有一个子示例；请将其视为可复制到项目中的模式，而不是开箱即用的应用。agent-os-e2e 示例则是完整的端到端演练。

示例	入门代码	适用场景
Hello World	GitHub	你需要最精简的循环：首次执行操作时惰性启动 VM、写入文件，再读回文件。
文件系统	GitHub	Agent 需要完整的文件操作能力：递归列出、查看 stat、移动、删除和自定义挂载。
Git	GitHub	Agent 在工作区内操作实际的 git 仓库：通过 exec 执行 init、commit、branch 和 clone。
进程	GitHub	Agent 需要运行带管道的 shell 命令和长时间运行的子进程。
网络	GitHub	Agent 在 VM 内提供 HTTP 服务，且你需要使用 vmFetch 或签名预览 URL。
Cron	GitHub	工作区需要运行定时命令或周期性 Agent 任务。
工具	GitHub	你希望将后端函数作为 CLI 命令暴露在工作区中。
Agent 会话	GitHub	你在工作区内驱动 Pi 编码 Agent 会话。需要 ANTHROPIC_API_KEY。
沙箱挂载	GitHub	Agent 需要原生二进制文件或真实 OS，并从 Docker 支持的沙箱挂载到 VM 中。需要 Docker。
端到端演练	GitHub	你需要一个可运行脚本，涵盖文件、进程、预览 URL 和流式 Pi Agent 会话。

设置

整个后端由一个注册表和一个 agentOs() Actor 组成：

import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";

const vm = agentOs({
  options: { software: [common, pi] },
});

export const registry = setup({ use: { vm } });
registry.start();

客户端侧和项目布局请参阅快速入门。

工作区模型

• 每个工作区对应一个 actor，以键作为身份标识。 client.vm.getOrCreate(["my-agent"]) 会为每个 Agent 创建独立的工作区；按用户 ID 作为键，可创建每位用户专属的开发环境。每个工作区都有自己的文件系统、进程和网络，彼此之间不共享状态，也不会相互干扰（参见概览）。
• 由软件包决定安装哪些内容。 agentOS 初始不安装任何命令。software 选项会安装软件包，例如 @rivet-dev/agent-os-common（包含 coreutils、sed、grep、gawk、findutils、diffutils、tar 和 gzip 等 Wasm 命令行工具的元软件包）、@rivet-dev/agent-os-git（git）和 @rivet-dev/agent-os-pi（Pi 编码 Agent）。参见软件。
• 虚拟机按需启动，空闲时休眠。 第一次执行操作时会启动虚拟机（客户端会收到 vmBooted 事件）；没有活动任务时，actor 会进入休眠并广播 vmShutdown，然后在下一次操作时唤醒。

休眠/唤醒周期中哪些内容会保留（参见持久化）：

数据	休眠/唤醒期间
会话记录和事件历史	作为事件流持久化在 actor SQLite 中。无需启动虚拟机，即可通过 listPersistedSessions 和 getSessionEvents 读取；resumeSession 会在重启后的虚拟机中恢复会话。
已签名的预览 URL 令牌	持久化在 actor SQLite 中。请求会根据存储的令牌进行验证，虚拟机则会按需重启以提供服务，因此休眠后预览 URL 仍可使用。
文件	如果挂载由持久化驱动程序提供支持（基于数据库、S3 或沙盒挂载），文件会保留。内存挂载在唤醒时会变为空。
进程、Shell 和 cron 作业	不会保留。唤醒时重启长期运行的进程并重新安排 cron 作业（建议扩展）。

当会话、进程、Shell 或钩子处于活动状态时，actor 会保持唤醒；宽限期结束后则进入休眠。

功能概览

区域	用途	关键操作	文档	示例
文件系统	为 Agent 提供可读写的文件树	readFile、writeFile、mkdir、readdir、move	文件系统	GitHub
进程	运行命令和长期运行的程序	exec、spawn、waitProcess、killProcess	进程	GitHub
Shell	具有流式输出的交互式终端	openShell、writeShell、resizeShell、closeShell	进程	无独立示例
网络和预览 URL	访问虚拟机内的服务并将其共享到外部	vmFetch、createSignedPreviewUrl、expireSignedPreviewUrl	网络	GitHub
Cron	定时命令和周期性 Agent 会话	scheduleCron、listCronJobs、cancelCronJob	Cron	GitHub
Agent 会话	在工作区内驱动编码 Agent	createSession、sendPrompt、resumeSession、closeSession	会话	GitHub

以下两个细节值得提前了解：

• createSignedPreviewUrl 会返回相对路径以及令牌和有效期。使用客户端句柄的 getGatewayUrl() 方法构建完整 URL；它是客户端方法，而不是 actor 操作。
• 只能通过 actor 使用 exec 和 session 操作类型来安排 cron 作业。回调式 cron 操作定义在服务端代码中，不会通过 listCronJobs 序列化。

驱动编码 Agent 会话

目前仅支持 Pi Agent（@rivet-dev/agent-os-pi）作为会话 Agent；Amp、Claude Code、Codex 和 OpenCode 即将推出。请参阅 Sessions。

1. createSession("pi", { env: { ANTHROPIC_API_KEY } }) 会返回一个 sessionId。VM 不会继承主机的 process.env，因此 API 密钥需要在每个会话中显式传入，或通过 LLM 网关保存在服务端。
2. 建立实时连接并订阅 sessionEvent，以便在 Agent 工作时流式接收其输出，例如消息片段。
3. sendPrompt(sessionId, ...) 会启动一轮对话；cancelPrompt 会停止正在进行的一轮对话。
4. 当 Agent 请求使用工具时，客户端会收到 permissionRequest 事件，并通过 respondPermission 响应该请求；或者，服务端可通过 onPermissionRequest 配置钩子自动批准（请参阅 Permissions）。
5. 对话记录会自动以通用对话记录格式（Agent Communication Protocol，ACP）持久化。休眠后，resumeSession 会在重启后的 VM 中继续会话；listPersistedSessions 和 getSessionEvents 则无需启动 VM 即可读取历史记录。

主机工具

将后端函数作为 CLI 命令暴露给 Agent，供其在工作区中使用。通过 toolKit() 和 hostTool()（主机上的 Zod-schema'd JavaScript 函数）定义工具包，将其通过 agentOs({ options: { toolKits: [...] } }) 传入，然后就会将其安装为 agentos-weather forecast --city Paris --days 3 这样的命令，并注入 Agent 的系统提示词。Agent 无需搭建 HTTP 端点或 MCP 服务，即可调用你的后端；而且，CLI 形式的工具兼容代码模式，可大幅节省令牌。请参阅 Tools 和 工具示例。

何时挂载完整沙箱

agentOS 并非沙箱的替代方案，而是旨在与沙箱协同工作。当工作区需要原生二进制文件、浏览器、编译或桌面自动化时，请使用沙箱挂载：通过 SandboxAgent.start({ sandbox: docker() }) 启动由 Docker 支持的沙箱，将其文件系统作为原生目录（例如 /sandbox）映射到 VM 中，并通过 createSandboxFs 和 createSandboxToolkit 将沙箱进程控制暴露为主机工具。通过挂载，writeFile 和 readFile 等文件系统操作会透明地映射到沙箱中，同时由容器运行繁重的工作负载。

请参阅 Sandbox Mounting 了解混合模式，并参阅 agentOS vs Sandboxes 了解两者各自的优势：轻量级 VM 的冷启动时间近乎为零（约 6 ms），并通过 npm install 安装；而沙箱则是完整的 Linux 环境，按运行时间秒数计费。

架构

主题	概要
拓扑	每个 Agent 或用户对应一个 vm[workspaceId] Actor；Actor 键即工作区标识。
入口	用于文件、进程、网络、cron 和会话的 Actor 操作；用于流式传输事件的实时连接。
流式传输	每个 Agent 事件对应一个 sessionEvent；为启动的进程提供 processOutput 和 processExit；为交互式 shell 提供 shellData。
持久化	会话记录、事件历史和预览令牌存储在 Actor SQLite 中；文件通过持久化挂载保存。

Actors

• 键：vm[workspaceId]，例如 client.vm.getOrCreate(["my-agent"])
• 职责：负责一个工作区。首次执行操作时延迟启动 VM，提供所有能力操作，将签名预览 URL 请求代理到 VM 的虚拟网络，并将会话和令牌持久化到 Actor SQLite。
• 操作（分组列出；各领域中负载最重的操作）
  • 文件系统：readFile、writeFile、mkdir、readdir、readdirRecursive、stat、exists、move、deleteFile
  • 进程：exec、spawn、writeProcessStdin、waitProcess、listProcesses、killProcess
  • Shell：openShell、writeShell、resizeShell、closeShell
  • 网络：vmFetch、createSignedPreviewUrl、expireSignedPreviewUrl
  • Cron：scheduleCron、listCronJobs、cancelCronJob
  • 会话：createSession、sendPrompt、cancelPrompt、respondPermission、resumeSession、closeSession、destroySession、listPersistedSessions、getSessionEvents
• 队列
  • 无
• 事件
  • vmBooted
  • vmShutdown
  • sessionEvent
  • permissionRequest
  • processOutput
  • processExit
  • shellData
  • cronEvent
• 状态
  • SQLite
  • agent_os_sessions 和 agent_os_session_events（会话元数据及按 seq 排序的记录事件）
  • agent_os_preview_tokens（带过期时间的签名预览 URL 令牌）
  • agent_os_fs_entries（数据库支持的挂载所用的文件内容）

生命周期

sequenceDiagram
	participant C as Client
	participant A as vm actor
	participant V as agentOS VM
	participant P as Pi session

	C->>A: getOrCreate(["my-agent"])
	C->>A: writeFile("/tmp/hello.txt", ...)
	Note over A,V: first action boots the VM
	A-->>C: vmBooted
	C->>A: exec("echo hello | tr a-z A-Z")
	A->>V: run command
	V-->>A: {exitCode: 0, stdout}
	C->>A: spawn("node", ["/tmp/server.mjs"])
	C->>A: createSignedPreviewUrl(8080, 60)
	A-->>C: {path, token, expiresAt}
	C->>A: fetch(gatewayUrl + path)
	Note over A: token checked in SQLite, request proxied into the VM network
	C->>A: createSession("pi", {env})
	A->>P: start session
	C->>A: sendPrompt(sessionId, ...)
	loop streamed agent output
		P-->>A: agent event
		A-->>C: sessionEvent
	end
	Note over A: idle, sleeps after grace period (vmShutdown)
	C->>A: resumeSession(sessionId)
	Note over A,V: wake reboots the VM, restoring transcripts, preview tokens, and persistent mounts

安全检查清单

• 验证连接身份：在 agentOs() 配置中添加 onBeforeConnect 钩子，确保只有经过授权的调用方才能访问工作区。签名预览 URL 请求会有意跳过此钩子，因为令牌本身就是凭证；通过浏览器访问预览 URL 时，无法提供 Actor 连接参数。
• 通过权限控制 Agent 工具的使用：会话权限请求会作为 permissionRequest 事件广播，以便通过 respondPermission 进行人工审批；也可以运行服务端 onPermissionRequest 策略，用于自动化流水线。请参阅权限。
• 将预览 URL 视为持有者凭证：令牌为随机生成的 32 字符值，默认有效期为 1 小时，最长为 24 小时；可使用 expireSignedPreviewUrl 提前撤销。预览响应带有宽松的 CORS 标头，因此未经应用层身份验证，不要在预览端口上提供私密数据。
• 不要在浏览器中暴露大模型凭证：在可信的服务端代码中创建会话，并将密钥放入 createSession 的 env 中；或者通过 LLM 网关将密钥完全保留在服务端。会话密钥会注入 VM 内的会话环境，绝不会存储在 Actor 配置或 SQLite 中。
• 将挂载的沙盒视为独立的信任边界：挂载的沙盒是位于工作区 Wasm 和 V8 隔离区之外的完整 Linux 环境。在将其映射到 Agent 的 VM 之前，应限制其可访问的网络和文件系统范围。
• 设置资源和成本限制：限制每个工作区的内存和 CPU（maxMemoryMb、maxCpuPercent，请参阅安全）。活动会话、进程和 Shell 会使 Actor 保持唤醒状态，因此建议扩展设置每个工作区的会话上限和令牌预算。

参考索引

Actors

• 访问控制
• 操作
• Actor 密钥
• Actor 调度
• Actor 状态
• 身份验证
• Cloudflare Workers 快速入门
• Actor 之间的通信
• 连接
• 自定义检查器标签页
• 调试
• 设计模式
• 销毁 Actor
• Effect.ts 快速入门（Beta）
• 错误
• Fetch 和 WebSocket 处理程序
• 辅助类型
• 图标和名称
• 内存中状态
• 输入参数
• 生命周期
• 限制
• 底层 HTTP 请求处理程序
• 底层 KV 存储
• 底层 WebSocket 处理程序
• 元数据
• Next.js 快速入门
• Node.js 和 Bun 快速入门
• 队列和运行循环
• React 快速入门
• 实时功能
• Rust 快速入门（Beta）
• 扩展和并发
• 共享和加入状态
• SQLite
• SQLite + Drizzle
• Supabase Functions 快速入门
• 测试
• 故障排除
• 类型
• 原生 HTTP API
• 版本和升级
• 工作流

Agent OS

• Agent 间通信
• agentOS 与 Sandbox 的比较
• 身份验证
• 基准测试
• 配置
• 核心包
• 快速入门教程
• Cron 作业
• 部署
• 内嵌大模型网关
• 事件
• 文件系统
• 限制
• 大模型凭据
• 多人协作
• 网络与预览
• 权限
• 持久化与休眠
• Pi
• 进程与 Shell
• 队列
• 快速开始
• Sandbox 挂载
• 安全与身份验证
• 安全模型
• 会话
• 软件
• SQLite
• 系统提示词
• 工具
• Webhooks
• 工作流自动化

命令行界面

• 命令行界面

客户端

• Node.js 与 Bun
• React
• Swift
• SwiftUI

操作指南

• AI Agent
• AI Agent 工作区
• 聊天室
• 协作式文本编辑器
• Cron 作业与计划任务
• 每个租户一个数据库
• 在 VPC 或隔离网络中部署 Rivet
• 实时光标与在线状态
• 多人游戏

部署

• 部署到 Amazon Web Services Lambda
• 部署到 AWS ECS
• 部署到 Cloudflare Workers
• 部署到 Freestyle
• 部署到 Google Cloud Run
• 部署到 Hetzner
• 部署到 Kubernetes
• 部署到 Railway
• 部署到 Rivet Compute
• 部署到 Supabase Functions
• 部署到 Vercel
• 部署到虚拟机与裸机

通用

• Actor 配置
• 架构
• 跨源资源共享
• 面向大模型和 AI 的文档
• 边缘网络
• 端点
• 环境变量
• HTTP 服务
• 日志记录
• 池配置
• 生产环境检查清单
• 注册表配置
• 运行时模式
• WASM 与原生 SDK

自托管

• 配置
• Docker Compose
• Docker 容器
• 文件系统
• FoundationDB（企业版）
• 安装 Rivet Engine
• Kubernetes
• 多区域
• PostgreSQL
• 生产环境检查清单
• Railway 部署
• Render 部署
• TLS 与证书