Skip to main content

Agent Sessions

An Agent Session is the durable record of a single agent's working life — a sleep/wake-capable container that accumulates an append-only timeline of everything the agent did: stage transitions, tool calls, LLM calls, human input, artifacts, errors, and handoffs. Where an experiment tracks a pipeline, a session tracks an agent across that work, so you can open it after the fact and watch the whole story replay.

Scenario: A long-running research agent ran overnight, slept while it waited on a human approval, woke, called three tools, then handed off to a writer agent. The next morning you open the session, scrub its timeline, and see exactly which tool result led to the final artifact.

Session lifecycle

A session moves through a small status set. Sleeping sessions can be woken to rehydrate recent context; terminal sessions are immutable.

Status Meaning
Pending Created but not yet started.
Active Currently working — new events are being appended.
Sleeping Paused, awaiting a wake (e.g. blocked on an approval). Waking rehydrates recent context.
Completed / Cancelled / Failed Terminal. The timeline is frozen and fully replayable.

The event timeline

Every meaningful moment is recorded as an immutable, sequence-numbered AgentSessionEvent. The detail page renders them newest-first and reconstructs a replay view from the full sequence. Event kinds include:

wake / sleep — session resumed or paused
transition — agent state change
stage_started / stage_completed
tool_call / tool_result
llm_call — an inference request
human_input — a person intervened
artifact — output produced
handoff_out / handoff_in — work passed between agents
error / note

In the UI

  • Agent Sessions lists every session for the team with its agent, status, and event count.
  • The session detail page renders the replay reconstruction alongside the raw event timeline (most recent 500 events). From here you can Wake a sleeping session or Cancel an active one (both require the edit-content permission).

MCP tools

Agents and the assistant manage sessions over MCP — including waking a slept session and replaying its timeline programmatically.

Tool Description
agent_session_list List sessions for the team.
agent_session_get Fetch a single session with its status and counts.
agent_session_events Page through the append-only event timeline.
agent_session_replay Reconstruct the session state from its event sequence.
agent_session_wake Wake a sleeping session and rehydrate recent context.
agent_session_sleep Put an active session to sleep until woken.
agent_session_handoff Hand the session's work off to another agent.
agent_session_cancel Cancel an active or sleeping session.
Because the timeline is append-only and sequence-numbered, a replay is faithful no matter how long the session ran or how many times it slept — making sessions the primary tool for post-hoc debugging of autonomous agents.

Related concepts

  • Agents — the worker a session belongs to.
  • Experiments — the pipeline a session often executes against.
  • Audit Log — the team-wide record of mutating actions.