An agent is code you deploy once and talk to in sessions. Each session gets its own sandbox, so one user’s work never shares a machine with another’s.
Sessions
An agent is addressed by session. You send a request with a session id, and Sutra routes it to that session’s sandbox:
- The first request with a new id creates the sandbox.
- The sandbox stops when the session has been idle for the agent’s idle timeout.
- A later request with the same id starts the session again, with its session volume restored.
See Sessions for ids, listing and stopping, and Invocation contract for the requests themselves.
Revisions
An agent’s definition is a revision: the image or template, resources, processes, protocol, idle timeout and integrations. A revision never changes. To change the agent, create a new revision and make it active. New sessions use the active revision; a running session keeps the revision it started with. See Revisions.
Instances are sandboxes
A session’s sandbox is an ordinary sandbox. It appears when you list sandboxes, with owner set to the agent. You can run processes in it, read its files and reach its ports like any other sandbox. Because the agent owns it, you delete it by stopping the session or deleting the agent, not directly.
Identity and integrations
Each agent has its own workload identity. Its sessions use it to reach integrations and other platform services with no credential inside the sandbox. A session records the principal that invoked it, and delegated integrations act on behalf of that principal.