ai-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Agent

IMPORTANT: Before doing anything, you MUST read
BASE_SKILL.md
in this skill's directory. It contains essential guidance on debugging, error handling, state management, deployment, and project setup. Those rules and patterns apply to all RivetKit work. Everything below assumes you have already read and understood it.

重要提示：在进行任何操作之前，你必须阅读本技能目录下的
BASE_SKILL.md
文件。其中包含了调试、错误处理、状态管理、部署和项目设置的关键指南。这些规则和模式适用于所有RivetKit工作。以下所有内容均假设你已阅读并理解该文件。

Working Examples

示例实现

If you need a reference implementation, read the raw working example code in these templates:

ai-agent

Patterns for building AI agent backends with RivetKit, where each conversation is one Rivet Actor that owns its memory, its message queue, and its streaming output.

如果你需要参考实现，请查看以下模板中的完整示例代码：

ai-agent

使用RivetKit构建AI Agent后端的模式：每个对话对应一个拥有自身记忆、消息队列和流式输出的Rivet Actor。

Starter Code

初始代码

Start with one of the working examples on GitHub and adapt it. The sections below describe the flagship

ai-agent

example unless a variant is called out explicitly.

Variant	Starter Code	Use When
Queue-driven AI SDK agent	GitHub	You want a streaming chat agent where each conversation keeps its own persistent memory and processes one message at a time.
Sandbox coding agent	GitHub	The agent should run a coding agent (Codex by default) inside an isolated sandbox via Docker, Daytona, or E2B.
Durable streams agent (experimental)	GitHub	You want replayable, restart-safe prompt and response delivery through durable streams instead of actor state and events.
Agent with a workspace (agentOS)	GitHub	The agent needs its own persistent computer: a filesystem, processes, shells, and preview URLs. See the cookbook: AI Agent Workspaces.

从GitHub上的示例代码开始进行适配：GitHub。除非特别说明变体，否则以下章节均以旗舰版

ai-agent

示例为例。

变体	初始代码	使用场景
队列驱动的AI SDK Agent	GitHub	你需要一个流式聊天Agent，每个对话拥有独立的持久化记忆，且每次仅处理一条消息。
沙箱编码Agent	GitHub	Agent需要在隔离的sandbox中运行编码Agent（默认是Codex），可通过Docker、Daytona或E2B实现。
持久化流Agent（实验性）	GitHub	你希望通过持久化流而非Actor状态和事件，实现可重放、重启安全的提示词和响应交付。
带工作区的Agent（agentOS）	GitHub	Agent需要独立的持久化计算环境：文件系统、进程、Shell和预览URL。请参考食谱：AI Agent工作区。

Conversation Memory

对话记忆

Use one actor per conversation, keyed by a conversation or agent id (see Actor Keys). The agent actor's persistent state is the conversation memory: in the

ai-agent

example,

messages

and

status

live in JSON actor state and survive sleep and restarts with no external database. Every model call rebuilds the prompt from

c.state.messages

plus a system prompt, so memory and inference input are the same data.

Variant	Where Memory Lives	Persisted State Fields
`ai-agent`	JSON actor state	`messages` , `status`
`sandbox-coding-agent`	JSON actor state plus the sandbox ACP session	`messages` , `status` , `sessionId`
`experimental-durable-streams-ai-agent`	Durable streams; the actor stores only its conversation id and a read cursor	`conversationId` , `promptStreamOffset`

每个对话对应一个Actor，通过对话ID或Agent ID作为键（参考Actor Keys）。Agent Actor的持久化state即为对话记忆：在

ai-agent

示例中，

messages

和

status

存储在JSON格式的Actor状态中，即使Actor休眠或重启也不会丢失，无需外部数据库。每次模型调用都会从

c.state.messages

加上系统提示词重建输入，因此记忆和推理输入是同一数据。

变体	记忆存储位置	持久化状态字段
`ai-agent`	JSON Actor状态	`messages` , `status`
`sandbox-coding-agent`	JSON Actor状态 + 沙箱ACP会话	`messages` , `status` , `sessionId`
`experimental-durable-streams-ai-agent`	持久化流；Actor仅存储对话ID和读取游标	`conversationId` , `promptStreamOffset`

Message Handling

消息处理

In the

ai-agent

example, the client pushes user input onto the agent's

message

queue with

agent.connection.send("message", { text, sender })

. This is a queue push, not an action call. The actor's

run

hook (see Lifecycle) consumes the queue serially with

for await (const queued of c.queue.iter())

Serial queue consumption is the per-conversation concurrency guarantee: at most one in-flight model call per actor, with no extra locking. The

status

field (

thinking

while a model call is in flight) is UI signal only; the run loop is the actual lock. The loop also checks

c.aborted

inside the token stream so shutdown exits gracefully.

Variant	Message Ingress	Serialization Guarantee
`ai-agent`	`message` queue pushed via `connection.send`	`run` hook pops one queued message at a time with `c.queue.iter()` .
`sandbox-coding-agent`	`sendMessage` action, no queue	Each call awaits the sandbox round trip before broadcasting the result.
`experimental-durable-streams-ai-agent`	Durable prompt stream long-polled from `onWake`	`promptStreamOffset` is persisted per chunk, so restarts resume without reprocessing prompts.

在

ai-agent

示例中，客户端通过

agent.connection.send("message", { text, sender })

将用户输入推送到Agent的

message

queue中。这是队列推送操作，而非动作调用。Actor的

run

钩子（参考Lifecycle）通过

for await (const queued of c.queue.iter())

串行消费队列中的消息。

串行队列消费保证了每个对话的并发控制：每个Actor最多同时处理一个模型调用，无需额外锁机制。

status

字段（模型调用进行中时为

thinking

）仅用于UI提示；实际的锁由运行循环实现。循环还会在令牌流中检查

c.aborted

，以便在关闭时优雅退出。

变体	消息入口	序列化保证
`ai-agent`	通过 `connection.send` 推送至 `message` 队列	`run` 钩子通过 `c.queue.iter()` 一次弹出一条队列消息。
`sandbox-coding-agent`	`sendMessage` action，无队列	每次调用都会等待沙箱往返完成后再广播结果。
`experimental-durable-streams-ai-agent`	从 `onWake` 长轮询持久化提示词流	`promptStreamOffset` 按块持久化，重启后可恢复处理，无需重新处理提示词。

Streaming Responses

流式响应

The

ai-agent

actor broadcasts a

response

event for every model text delta. The payload carries

messageId

, the per-token

delta

, the cumulative

content

, and a

done

flag (plus

error

on failure), so clients can either append deltas or idempotently replace the message by

messageId

using

content

. The example frontend replaces by

messageId

, which tolerates dropped events. The terminal broadcast has an empty

delta

, the full

content

, and

done: true

Because the assistant message object lives in

c.state.messages

and is mutated in place during streaming, partial content persists if the actor restarts mid-stream. The example broadcasts once per AI SDK delta with no throttling; batching or throttling deltas is a recommended extension for high-traffic deployments, not something the example implements.

Variant differences:

sandbox-coding-agent

sends a single

response

broadcast with

done: true

after the sandbox finishes (no incremental streaming), and

experimental-durable-streams-ai-agent

appends per-token chunks to a durable response stream, then broadcasts

responseComplete

responseError

ai-agent

Actor会为每个模型文本增量广播

response

event。负载包含

messageId

、每个令牌的

delta

、累积的

content

以及

done

标志（失败时包含

error

），因此客户端既可以追加增量，也可以通过

messageId

使用

content

幂等性替换消息。示例前端通过

messageId

替换消息，这样可以容忍丢失的事件。最终广播的

delta

为空，包含完整的

content

且

done: true

。

由于助手消息对象存储在

c.state.messages

中，并在流式传输过程中被原地修改，因此如果Actor在流式传输中途重启，部分内容仍会保留。示例中每次AI SDK产生增量时都会立即广播，未做限流；对于高流量部署，建议扩展实现批量处理或限流增量，但示例未包含此功能。

变体差异：

sandbox-coding-agent

在沙箱完成后发送单个

response

广播，

done: true

（无增量流式传输）；

experimental-durable-streams-ai-agent

将每个令牌块追加到持久化响应流，然后广播

responseComplete

或

responseError

。

Architecture

架构

Topic	Summary
Topology	`agentManager["primary"]` singleton directory plus one `agent[agentId]` actor per conversation.
Ingress	Client pushes `AgentQueueMessage` payloads onto the agent's `message` queue with `connection.send` .
Streaming	One `response` broadcast per model delta, terminal broadcast with `done: true` .
Memory	Full transcript and status in JSON actor state; no external database.

The manager creates

AgentInfo

records and warms each agent through actor-to-actor communication:

createAgent

calls

c.client<typeof registry>()

, then

client.agent.getOrCreate([info.id])

and awaits

getStatus()

so the conversation actor exists before the client connects. The sandbox variant extends this topology with a

codingSandbox

actor that shares the agent's key (

codingSandbox.getOrCreate([c.key[0]])

), so the agent-to-sandbox mapping is implicit in the key space.

Actors

Key:
```
agentManager["primary"]
```
Responsibility: Directory actor. Creates
```
AgentInfo
```
records, lists agents, and warms each agent actor via
```
c.client()
```
.
Actions
- ```
createAgent
```
- ```
listAgents
```
Queues
- None
State
- JSON
- ```
agents
```
Key:
```
agent[agentId]
```
Responsibility: One actor per conversation. Holds the full message history and status, consumes queued user messages in its
```
run
```
loop, calls the model via the AI SDK, and broadcasts streaming deltas.
Actions
- ```
getHistory
```
- ```
getStatus
```
Queues
- ```
message
```
Events
- ```
messageAdded
```
- ```
status
```
- ```
response
```
State
- JSON
- ```
messages
```
- ```
status
```

Lifecycle

mermaid

sequenceDiagram
	participant C as Client
	participant AM as agentManager
	participant A as agent
	participant LLM as Model API

	C->>AM: createAgent(name)
	AM->>A: getOrCreate([info.id]) + getStatus()
	AM-->>C: AgentInfo
	C->>A: connection.send("message", {text, sender})
	Note over A: run loop pops queue via c.queue.iter()
	A-->>C: messageAdded (user message)
	A-->>C: messageAdded (assistant placeholder)
	A-->>C: status (thinking)
	A->>LLM: streamText(system prompt + history)
	loop each text delta
		LLM-->>A: delta
		A-->>C: response {messageId, delta, content, done: false}
	end
	A-->>C: response {delta: "", content, done: true}
	A-->>C: status (idle)

主题	概述
拓扑结构	`agentManager["primary"]` 单例目录 + 每个对话对应一个 `agent[agentId]` Actor。
入口	客户端通过 `connection.send` 将 `AgentQueueMessage` 负载推送到Agent的 `message` 队列。
流式传输	每个模型增量对应一次 `response` 广播，最终广播 `done: true` 。
记忆	完整对话记录和状态存储在JSON Actor状态中；无需外部数据库。

管理器创建

AgentInfo

记录，并通过Actor间通信预热每个Agent：

createAgent

调用

c.client<typeof registry>()

，然后调用

client.agent.getOrCreate([info.id])

并等待

getStatus()

，确保对话Actor在客户端连接前已存在。沙箱变体扩展了此拓扑，增加了

codingSandbox

Actor，其与Agent共享键（

codingSandbox.getOrCreate([c.key[0]])

），因此Agent与沙箱的映射在键空间中是隐式的。

Actors

键:
```
agentManager["primary"]
```
职责: 目录Actor。创建
```
AgentInfo
```
记录，列出所有Agent，并通过
```
c.client()
```
预热每个Agent Actor。
Actions
- ```
createAgent
```
- ```
listAgents
```
Queues
- 无
State
- JSON
- ```
agents
```
键:
```
agent[agentId]
```
职责: 每个对话对应一个Actor。保存完整消息历史和状态，在
```
run
```
循环中消费队列中的用户消息，通过AI SDK调用模型，并广播流式增量。
Actions
- ```
getHistory
```
- ```
getStatus
```
Queues
- ```
message
```
Events
- ```
messageAdded
```
- ```
status
```
- ```
response
```
State
- JSON
- ```
messages
```
- ```
status
```

生命周期

mermaid

sequenceDiagram
	participant C as Client
	participant AM as agentManager
	participant A as agent
	participant LLM as Model API

	C->>AM: createAgent(name)
	AM->>A: getOrCreate([info.id]) + getStatus()
	AM-->>C: AgentInfo
	C->>A: connection.send("message", {text, sender})
	Note over A: run loop pops queue via c.queue.iter()
	A-->>C: messageAdded (user message)
	A-->>C: messageAdded (assistant placeholder)
	A-->>C: status (thinking)
	A->>LLM: streamText(system prompt + history)
	loop each text delta
		LLM-->>A: delta
		A-->>C: response {messageId, delta, content, done: false}
	end
	A-->>C: response {delta: "", content, done: true}
	A-->>C: status (idle)

Security Checklist

安全检查清单

The examples ship without auth so they stay minimal. Apply this baseline before exposing an agent backend.

API keys stay server-side:
```
OPENAI_API_KEY
```
(or
```
ANTHROPIC_API_KEY
```
) is read by the AI SDK inside the actor process. The key never reaches the browser; clients only talk to the actor over RivetKit. The sandbox variant forwards keys into the sandbox env, never to the client.
Add authentication: The examples have no auth, so anyone who reaches the server can create agents, list them, and message any agent whose key they can guess. Add
```
onBeforeConnect
```
or
```
createConnState
```
checks with scoped tokens as a recommended extension. See Authentication.
Validate and rate-limit queue payloads: The example only skips bodies without a string
```
text
```
. Enforce payload size limits, schema validation, and per-connection rate limits as a recommended extension.
Derive sender identity server-side: The example trusts the client-supplied
```
sender
```
field verbatim. Bind sender identity to the authenticated connection instead.
Cap or trim message history: The example sends the full transcript on every model call with no cap. Trim or summarize old messages as a recommended extension so prompts and state stay bounded.
Set cost ceilings per conversation: Add per-agent token budgets and quotas as a recommended extension. The sandbox variant runs real compute, so also enforce per-user sandbox quotas and restrict sandbox network egress.

示例未包含认证功能以保持简洁。在对外暴露Agent后端前，请应用以下基线安全措施。

API密钥保留在服务端:
```
OPENAI_API_KEY
```
（或
```
ANTHROPIC_API_KEY
```
）由AI SDK在Actor进程内部读取。密钥永远不会传到浏览器；客户端仅通过RivetKit与Actor通信。沙箱变体将密钥转发到沙箱环境，而非客户端。
添加认证机制: 示例无认证功能，因此任何能访问服务器的人都可以创建Agent、列出所有Agent，以及向任何能猜到键的Agent发送消息。建议扩展实现
```
onBeforeConnect
```
或
```
createConnState
```
检查，并使用范围令牌。参考Authentication。
验证并限流队列负载: 示例仅跳过没有字符串类型
```
text
```
的请求体。建议扩展实现负载大小限制、Schema验证和每连接限流。
服务端推导发送者身份: 示例直接信任客户端提供的
```
sender
```
字段。应将发送者身份与已认证的连接绑定。
限制或裁剪消息历史: 示例每次模型调用都会发送完整对话记录，无上限。建议扩展实现裁剪或总结旧消息，以确保提示词和状态的大小可控。
设置每个对话的成本上限: 建议扩展实现每个Agent的令牌预算和配额。沙箱变体运行实际计算，因此还需强制每个用户的沙箱配额，并限制沙箱网络出站流量。

Reference Map

参考映射

Actors

Access Control
Actions
Actor Keys
Actor Scheduling
Actor Statuses
AI and User-Generated Rivet Actors
Authentication
Communicating Between Actors
Connections
Custom Inspector Tabs
Debugging
Design Patterns
Destroying Actors
Errors
Fetch and WebSocket Handler
Helper Types
Icons & Names
Input Parameters
Lifecycle
Limits
Low-Level HTTP Request Handler
Low-Level KV Storage
Low-Level WebSocket Handler
Metadata
Next.js Quickstart
Node.js & Bun Quickstart
Queues & Run Loops
React Quickstart
Realtime
Rust Quickstart (Preview)
Sandbox Actor
Scaling & Concurrency
Sharing and Joining State
SQLite
SQLite + Drizzle
State & Storage
Testing
Troubleshooting
Types
Vanilla HTTP API
Versions & Upgrades
Workflows

访问控制
Actions
Actor Keys
Actor调度
Actor状态
AI与用户生成的Rivet Actors
认证
Actor间通信
连接
自定义检查器标签页
调试
设计模式
销毁Actors
错误
Fetch与WebSocket处理器
辅助类型
图标与名称
输入参数
生命周期
限制
底层HTTP请求处理器
底层KV存储
底层WebSocket处理器
元数据
Next.js快速开始
Node.js & Bun快速开始
队列与运行循环
React快速开始
实时功能
Rust快速开始（预览版）
沙箱Actor
扩容与并发
状态共享与合并
SQLite
SQLite + Drizzle
状态与存储
测试
故障排除
类型
原生HTTP API
版本与升级
工作流

Agent Os

Agent-to-Agent Communication
agentOS vs Sandbox
Authentication
Benchmarks
Configuration
Core Package
Cron Jobs
Deployment
Embedded LLM Gateway
Events
Filesystem
Limitations
LLM Credentials
Multiplayer
Networking & Previews
Overview
Permissions
Persistence & Sleep
Pi
Processes & Shell
Queues
Quickstart
Sandbox Mounting
Security & Auth
Security Model
Sessions
Software
SQLite
System Prompt
Tools
Webhooks
Workflow Automation

Agent间通信
agentOS vs 沙箱
认证
基准测试
配置
核心包
定时任务
部署
嵌入式LLM网关
事件
文件系统
限制
LLM凭证
多人协作
网络与预览
概述
权限
持久化与休眠
Pi
进程与Shell
队列
快速开始
沙箱挂载
安全与认证
安全模型
会话
软件
SQLite
系统提示词
工具
Webhooks
工作流自动化

Clients

Node.js & Bun
React
Swift
SwiftUI

Node.js & Bun
React
Swift
SwiftUI

Connect

Deploy To Amazon Web Services Lambda
Deploying to AWS ECS
Deploying to Cloudflare Workers
Deploying to Freestyle
Deploying to Google Cloud Run
Deploying to Hetzner
Deploying to Kubernetes
Deploying to Railway
Deploying to Rivet Compute
Deploying to Supabase Functions
Deploying to Vercel
Deploying to VMs & Bare Metal

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

Cookbook

AI Agent
AI Agent Workspaces
Chat Room
Collaborative Text Editor
Cron Jobs and Scheduled Tasks
Database per Tenant
Deploying Rivet in a VPC or Air-Gapped Network
Live Cursors and Presence
Multiplayer Game

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

General

Actor Configuration
Architecture
Cross-Origin Resource Sharing
Documentation for LLMs & AI
Edge Networking
Endpoints
Environment Variables
HTTP Server
Logging
Pool Configuration
Production Checklist
Registry Configuration
Runtime Modes

Actor配置
架构
跨域资源共享
LLM与AI相关文档
边缘网络
端点
环境变量
HTTP服务器
日志
池配置
生产环境检查清单
注册表配置
运行时模式

Self Hosting

Configuration
Docker Compose
Docker Container
File System
FoundationDB (Enterprise)
Installing Rivet Engine
Kubernetes
Multi-Region
PostgreSQL
Production Checklist
Railway Deployment
Render Deployment
TLS & Certificates

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