Work with sessions

Every agent interaction is a session — a sequence of messages exchanged between the user, the LLM, and tool results. Sessions let you inspect, resume, and persist conversations.

Working with Sessions

Sessions are created automatically by the Runner and contain the full conversation history.

Session Attributes

A Session has these attributes:

  • id — auto-generated unique identifier (e.g., session-20250407-143022-123456)
  • messages — list of Message objects in chronological order
  • working_directory — the directory relative paths resolve to (default .)
  • created_at — when the session was created

Saving and Loading Sessions

Persist a session to disk and resume it later.

The saved JSON file contains the message history, session ID, working directory, and creation timestamp. You can inspect it with any JSON viewer — it's not opaque binary.

Manual Session Manipulation

Sessions can be built up manually before passing to a runner.

Use Cases

Resuming a Long Conversation

Save after each significant agent run. If your process crashes, you still have the message history.

Building a Chat UI

Each message in a web UI maps to a session message.

Auditing Agent Behavior

The session's message history is your audit trail. You can log it, search it, and replay it to understand what the agent did and why.