Skip to content

Agentic AI Architecture

The sandbox is not an LLM agent itself. It is an execution substrate designed to be called by agentic workers. Its contract provides the primitives an agent loop needs: create an isolated session, execute code, exchange files, export results, and resume state.

flowchart TD
  classDef default fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc
  classDef highlight fill:#065f46,stroke:#34d399,stroke-width:2px,color:#f0fdf4
  Plan["Agent plan"]:::highlight --> Create["Create session with limits"]
  Create --> Execute["Run command"]
  Execute --> Inspect["Read stdout/files"]
  Inspect --> Execute
  Inspect --> Export["Sync artifacts"]
  Export --> Decide{"Need resume point?"}
  Decide -->|Yes| Snapshot["Stop and snapshot"]
  Decide -->|No| Cleanup["Stop/delete"]
  Snapshot --> Restore["Create session from snapshot"]
  Restore --> Execute
  linkStyle default stroke:#64748b,stroke-width:2px

Runtime abstraction

SandboxRuntime defines availability, session lifecycle, command execution, snapshot creation/deletion, and listing. The API does not need to know whether a command runs in a host scratch directory or a microVM.

The microsandbox adapter maps CPU, memory, workdir, volume binding, image/snapshot, and network policy into the msb SDK. Local mode rewrites guest /workspace paths into a host scratch directory and runs a subprocess.

Agent-facing semantics

Execution is request/response rather than streamed: stdout/stderr are captured, truncated to a configured maximum, written to logs, and retrieved with offset reads. The absence of command streaming simplifies persistence but means long-running agents need polling and timeout tuning.

Resumability

Snapshots require microsandbox, stop an active session first unless explicitly disabled, capture VM disk state, and optionally archive the workspace. Restoring validates that snapshot and requested workspace IDs match.