A session is a bounded unit of agent work that has a beginning, an end, and persisted state across multiple loops.
Sessions are the unit of work that cron schedules, that monitoring observes, and that audit replays. The session is the right granularity for almost every operational concern: the session is the unit that gets a name, the unit that gets a log, the unit that gets a status, and the unit that gets restarted.
Why sessions matter
Without sessions, an agent's work is a fuzzy continuous stream of loops and tool calls. The stream is hard to monitor (what is the agent doing right now?), hard to audit (what did the agent do yesterday?), and hard to recover (which loop should I restart from?). The session is the bounding box that makes the work observable.
The session lifecycle
A session has a clear lifecycle:
1. Init. The session is created with a unique id, a start timestamp, and an initial context. The init step is often triggered by a cron, a webhook, or a user prompt.
2. Run. The session runs through one or more agent loops. Each loop may read the session's memory, call tools, and write back to the session's memory. The session accumulates state as the loops run.
3. Persist. Between loops, the session's state is persisted to a durable store. The persist step is what makes the session recoverable across process restarts.
4. End. The session ends when the stop condition is met. The session's final state is committed to long-term memory, and the session is closed. The session is the unit that the audit log tracks.
Operator implications
The session is the right place to start when an operator is debugging an agent that is not making progress. Most production issues are not about the model's capabilities — they are about the session's lifecycle: the session is not persisting, the session is not being closed, the session is being restarted in the wrong state, or the session is running too long. The session is also the right place to start when an operator is adding observability — the canonical question is "what should the session log?"
Related terms
The session is the unit of work that cron schedules and that observability tracks. The session's persistence is the memory layer. The session's run is one or more agent loops. The session's branching is often gated by HITL approvals.
For the full primer, see First Steps: Sessions and Memory.
Sessions vs. logs
A session is not a log. A log is a passive record of what happened; a session is an active unit of work that has a lifecycle. The session knows when it started, when it ended, and what state it was in. The log is the record of the session's events, but the log does not have the session's lifecycle.
The session is the right abstraction for most operational concerns because the session is the unit that can be restarted, the unit that can be rolled back, and the unit that can be replayed. The log is the right abstraction for analysis (the log is the source of truth for what happened), but the log is not the right abstraction for control (the log cannot be restarted).