Workspaces and sessions

An Agent Studio workspace is a local folder where you work. It can contain no agent projects yet, one project, or several projects in subfolders. It is not a Sapiom cloud resource.

An agent project is a source folder that Studio recognizes through sapiom.json. Studio groups recognized agents under workspace folders in the rail. A project outside a known session folder can still appear under No workspace until you open or start a session in its folder.

Sessions are coding-agent conversations

A session is one coding-agent process and conversation rooted in one working directory. Agent Studio can run several sessions at once and presents them as tabs for the agent or folder currently in focus.

The session’s working directory does not have to equal the selected agent project’s path. This matters when one workspace contains several agents: a session can stay rooted at the workspace while you select a particular agent for Canvas, Local Run, Deploy, or Prod Run.

State	What it controls
Workspace folder	The local directory the session works within.
Focused agent	Which agent’s sessions and project surfaces Studio shows.
Session binding	Which recognized agent Studio actions target for that session.
Session tab	Which coding-agent process and conversation receives your input.

Changing the focused or bound agent does not move files and does not change the session’s working directory.

Discovery and history

Studio discovers valid sapiom.json projects under folders you scan and remembers projects you connect directly. Discovery is intentionally bounded, so a deeply nested project may need to be opened or connected explicitly.

Session history is scoped to the working directory. It combines Studio’s own session records with conversations the coding agent still has in its history store.

There are two different continuation outcomes:

Resume conversation reattaches to the coding agent’s original conversation when that history still exists.
Continue with Studio context starts a new conversation in the same directory and seeds it from Studio’s recorded brief when native history is unavailable.

The second path preserves useful context, but it is not a verbatim replay of the original coding-agent transcript.

See Local and cloud for where each part of this model runs, or take the current Agent Studio tour.