Skip to main content
Sign In
Core

Session Lifecycle

What a session is, the events one prompt produces, and how to steer or cancel a run.

A session is one agent’s conversation. Each agent key has exactly one session, and the session:

  • Keeps the full history of messages and tool calls.
  • Runs one prompt at a time, calling the model and tools until the model is done.
  • Streams events to every connected client while it runs.
  • Summarizes older messages when the context fills up.
  • Survives sleep, crashes, and deploys. See Architecture.
ClientAgentcalls the modelSandboxruns toolsprompteventstool callresultrepeats until the model stops calling tools

This client connects to the Quickstart agent, sends one prompt, and prints the events it receives:

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

const client = createClient<typeof registry>();
const conn = client.agent.getOrCreate(["user-123"]).connect();

conn.on("event", (event) => {
	if (event.type === "turn_start") console.log("\n[turn]");
	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
		process.stdout.write(event.assistantMessageEvent.delta);
	}
	if (event.type === "turn_end" && event.message.role === "assistant") {
		console.log(`\n[${event.message.usage.totalTokens} tokens]`);
	}
	if (event.type === "compaction_start") console.log("\n[compacting]");
});

await conn.prompt("Write an isPalindrome function in TypeScript, add tests for it, and run them.");
await conn.dispose();

Events

Every event arrives as event, with a type:

Event TypeWhen it fires
agent_start, agent_endA run starts or ends. Then agent_settled follows once the agent is fully idle, after any retry.
turn_start, turn_endA model response starts, or it and its tool calls are done. The turn_end event has the response’s usage: tokens and cost.
message_updateThe model streams output. Its assistantMessageEvent.type is text_delta, thinking_delta, or a tool call update.
message_endA message is complete: your prompt, a model reply, or a tool result.
tool_execution_start, tool_execution_endA tool starts or finishes. On a failure, isError is true.
auto_retry_start, auto_retry_endA failed model call is retried.
compaction_start, compaction_endOlder messages are summarized to free up context.

A client that connects mid-run only receives events from that point on, so read earlier messages with getMessages. To stop listening, call the function that on returns.

Steer, follow up, or cancel

While a run is in progress:

ActionWhat it does
steer(text)The agent reads the message after its current tool calls finish, before its next model call.
followUp(text)The agent reads the message once it has no tool calls left, and the run continues. On an idle agent it only queues.
abort()Cancels the run and stops any command still running in the sandbox. Daytona can’t cancel a command, so it runs until it exits or times out.

Calling prompt while a run is in progress throws. To queue it instead, pass streamingBehavior: "steer" or "followUp". On an idle agent, the prompt runs right away.

Compaction and errors

  • When the context fills up, the agent summarizes older messages and keeps going. Call compact to do it yourself. It cancels the run in progress first.
  • A failed model call is retried automatically. If it keeps failing, the run ends with an assistant message whose stopReason is "error", and the session is kept.

Next: Client SDK, how to call an agent from your backend or a browser.

Edit this page