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:

  • Holds every message, tool call, and tool result, in order.
  • Runs one prompt at a time. A run is one or more turns, and each turn is a model response plus the tool calls it asked for.
  • 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(["support", "customer-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("Find the failing test and fix it.");
await conn.dispose();

Events

Every event arrives as event, with a type:

TypeWhen it fires
agent_start, agent_endA run starts or ends. 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. turn_end has the response’s usage: tokens and cost.
message_updateThe model streams output. 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. isError marks a failure.
auto_retry_start, auto_retry_endA failed model call is retried.
compaction_start, compaction_endOlder messages are summarized to free up context.

on returns a function that removes the listener. A client that connects mid-run receives events from that point on. Read earlier messages with getMessages.

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.

prompt throws while a run is in progress. Pass streamingBehavior: "steer" or "followUp" to queue the prompt instead. If the agent is idle, it 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: Sandboxes, where the agent’s tool calls run.

Edit this page