Agent

Sessions

Create agent sessions, send prompts, stream responses, and replay event history.

Create sessions with any supported agent type
Stream responses in real time via sessionEvent subscriptions
Replay events with sequence numbers for reconnection and history
Persist transcripts automatically in SQLite across sleep/wake cycles
Universal transcript format using the Agent Communication Protocol (ACP)

Currently only Pi is supported as an agent. Amp, Claude Code, Codex, and OpenCode are coming soon.

Create a session

Use createSession to launch an agent inside the VM. Returns session metadata including capabilities and agent info.

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
console.log(session.sessionId);
console.log(session.capabilities);
console.log(session.agentInfo);

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();

`env`

Environment variables to pass to the agent process. The VM does not inherit from the host process.env, so API keys must be passed explicitly.

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

`cwd`

Working directory for the agent session inside the VM. Defaults to /home/user.

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  cwd: "/home/user/project",
});

`mcpServers`

Pass MCP servers to give the agent access to additional tools. MCP servers provide typed tool definitions that the agent’s LLM can discover and call natively.

Local MCP server

Run an MCP server as a child process inside the VM.

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  mcpServers: [
    {
      type: "local",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      env: {},
    },
  ],
});

Remote MCP server

Connect to an MCP server running outside the VM.

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  mcpServers: [
    {
      type: "remote",
      url: "https://mcp.example.com/sse",
      headers: {
        Authorization: "Bearer my-token",
      },
    },
  ],
});

`additionalInstructions`

Append custom instructions to the agent’s system prompt.

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  additionalInstructions: "Always write tests before implementation.",
});

`skipOsInstructions`

Skip the base OS instructions injection. Tool documentation is still included even when this is true.

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  skipOsInstructions: true,
});

Send a prompt

Use sendPrompt to send a message to an active session. The response contains the agent’s reply.

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
const response = await agent.sendPrompt(
  session.sessionId,
  "Create a TypeScript function that checks if a number is prime",
);
console.log(response);

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();

Stream responses

Subscribe to sessionEvent to receive real-time streaming output from the agent.

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

// Subscribe to session events before sending the prompt
agent.on("sessionEvent", (data) => {
  console.log(`[${data.sessionId}]`, data.event.method, data.event.params);
});

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
await agent.sendPrompt(session.sessionId, "Explain how async/await works");

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();

Cancel a prompt

Use cancelPrompt to stop an in-progress prompt.

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

// Start a long-running prompt
const promptPromise = agent.sendPrompt(
  session.sessionId,
  "Refactor the entire codebase to use TypeScript strict mode",
);

// Cancel after 10 seconds
setTimeout(async () => {
  await agent.cancelPrompt(session.sessionId);
}, 10_000);

const response = await promptPromise;
console.log(response);

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();

Resume, close, and destroy sessions

resumeSession reconnects to a session that was suspended (e.g. after sleep)
closeSession gracefully closes a session
destroySession removes the session and all persisted data

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

// Resume a previously created session
const resumed = await agent.resumeSession("session-id-from-earlier");

// Close without destroying persisted data
await agent.closeSession(resumed.sessionId);

// Destroy session and all persisted events
await agent.destroySession(resumed.sessionId);

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();

Runtime configuration

Change model, mode, and thought level on a live session.

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

// Change model
await agent.setModel(session.sessionId, "claude-sonnet-4-6");

// Change mode (e.g. "plan", "auto")
await agent.setMode(session.sessionId, "plan");

// Change thought level
await agent.setThoughtLevel(session.sessionId, "high");

// Query available options
const modes = await agent.getModes(session.sessionId);
console.log(modes);

const options = await agent.getConfigOptions(session.sessionId);
console.log(options);

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();

Use getSequencedEvents to replay in-memory session events (for live reconnection while the VM is running), or getSessionEvents to replay from persisted storage (for transcript history, including when the VM is not running). See Events for details on the difference.

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
await agent.sendPrompt(session.sessionId, "Hello");

// Get all events
const events = await agent.getEvents(session.sessionId);
console.log(events);

// Get events with sequence numbers (for pagination/reconnection)
const sequenced = await agent.getSequencedEvents(session.sessionId, {
  since: 0,
});
console.log(sequenced);

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();

Persisted session history

Query session history from SQLite. Works even when the VM is not running.

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

// List all persisted sessions
const sessions = await agent.listPersistedSessions();
for (const s of sessions) {
  console.log(s.sessionId, s.agentType, s.createdAt);
}

// Get full event history for a session
const events = await agent.getSessionEvents(sessions[0].sessionId);
for (const e of events) {
  console.log(e.seq, e.event.method, e.createdAt);
}

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();

Multiple sessions

A single VM can run multiple sessions simultaneously. Each session has its own agent process but shares the same filesystem. Use different session IDs to manage them independently.

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

// Create two sessions in the same VM
const coder = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
const reviewer = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

// Coder writes code
await agent.sendPrompt(coder.sessionId, "Write a REST API at /home/user/api.ts");

// Reviewer reads and reviews the same file
await agent.sendPrompt(reviewer.sessionId, "Review /home/user/api.ts for issues");

// Close each session independently
await agent.closeSession(coder.sessionId);
await agent.closeSession(reviewer.sessionId);

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();

Recommendations

Subscribe to sessionEvent before calling sendPrompt to avoid missing early events.
Use getSequencedEvents with since for reconnection. Track the last sequence number you processed.
Use listPersistedSessions and getSessionEvents to build transcript history UIs without requiring a running VM.
Call closeSession when done to release resources. Use destroySession only when you want to permanently delete session data.