Choose state lifetimes for AI agent workspaces
Choose appropriate lifetimes for agent process memory, sandbox files, persistent volumes, artifacts, and application state in Polyaxon.
An agent workspace is rarely simply “ephemeral” or “persistent.” Its Python process, scratch files, mounted volume, and stored reports can all have different lifetimes.
Design those lifetimes explicitly in Polyaxon. Keeping everything alive wastes capacity and complicates isolation; deleting everything at the end of a command makes multi-step work unnecessarily expensive.
Classify the state you actually need
| State | Suitable location | Important boundary |
|---|---|---|
| Variables used by one calculation | Process memory | Lost when that process exits |
| Files shared across commands in one session | Sandbox workspace | Depends on the mounted volume |
| Reports needed after execution | Run artifact storage | Retention and access policy apply |
| Mutable conversation or task records | Application database | Requires application-level consistency |
| Reusable dependencies | Reviewed container image | Changes require a new image revision |
The sandbox quick start uses an emptyDir volume for /workspace. Its files survive separate commands while the Pod remains, but they are lost when the Pod is replaced.
Separate calls to python script.py do not share Python variables merely because they run in the same sandbox. A persistent interpreter is a separate application design.
Choose a workspace lifetime from the interaction
For a one-shot report, start with a finite job and durable outputs. For a coding session that repeatedly edits and executes files, a sandbox-enabled service can retain the working directory across commands.
A shared persistent volume can retain files beyond one Pod, but it also introduces ownership, cleanup, and concurrent-write questions. Provision and authorize it through the appropriate storage connection, and ensure the application understands its access semantics.
Do not reuse a workspace across unrelated tenants just because the files are convenient to keep. Reuse must include a clear ownership model and a verified reset boundary.
Checkpoint the useful result, not the whole machine
At meaningful milestones, persist the source revision, generated patch, approved dataset references, and analysis outputs. The output persistence guide explains the distinction between scratch files and the synced outputs directory.
A checkpoint should describe how to reconstruct the work in a fresh environment. It need not include temporary caches, credentials, or every downloaded dependency.
If generated code cannot access the artifact store, let a trusted controller download selected files, validate them, and persist the approved evidence. Keep that collection path bounded by size and file type.
Design interruption as a normal event
A service may stop because of an absolute timeout, operator action, or infrastructure failure. Define what the user sees and how the next request resumes from durable state.
Termination settings bound the workload lifetime. Service culling, where supported and configured, stops idle services; it is not a promise to suspend and restore process memory.
Recreating a service from the same image is not enough if the session depended on unrecorded package installations or manual edits. Move those changes into the image, component, or checkpoint before relying on recovery.
Review the retention policy by state class
Decide separately when to stop compute, remove workspace storage, expire artifacts, and delete application records. Those actions are not interchangeable.
For a request that runs the ticket evaluator, turn that decision into a retention matrix:
| Retained item | Owner and lifetime decision | What a fresh executor needs |
|---|---|---|
| Downloaded scratch inputs | Workspace owner; remove with the session | Reload the approved manifest and predictions from their fixed revisions |
evaluation/summary.json | Evaluation owner; retain with the decision and its access policy | The exact saved report or the inputs needed to recompute it |
| Request-to-run mapping | Controller owner; retain through retries and unresolved submissions | Existing request ID, run UUID, and current disposition |
| Reusable lesson from the result | Memory owner; admit only after review | A versioned, scoped memory entry with provenance |
Record concrete retention periods in the application's policy; the table does not prescribe one period for every team. Continue with workspace replacement for the operating procedure and memory updates for the state that should outlive that workspace.
The practical design is often mixed: a short-lived execution environment, session-scoped scratch files, and deliberately durable results. Polyaxon provides the workload and artifact context; your application defines which state deserves to survive.