AgentScope AgentOS Workspace: Unified Directory Contract, 8 Pluggable Backends & Concurrent Deduplication

Why Agents Need a Workspace

Workspace = an isolated sandbox directory + execution container allocated per (agent_id, session_id) pair. Unlike stateless LLM chat, agents must write scripts, read configs, generate reports, save logs, mount skill packages ( SKILL.md), store MCP declarations, and offload large outputs to offline files — all without polluting a shared filesystem.

Unified Directory Contract (Four-Piece Suite)

All paths derive from a single join_path entry point; manual string concatenation is forbidden. The contract defines four top-level directories:

.mcp — MCP declaration configs (service name, transport stdio/HTTP, headers, bound tool list). Follows workspace lifetime.

skills — per-agent skill copies and SKILL.md files. Follows agent lifetime.

data — runtime data, context-compression artifacts, large tool-result offline files. Follows session lifetime.

sessions — state snapshots, execution traces, checkpoints. Follows session lifetime.

Data flows: declarations from .mcp → skill resources from skills → runtime output to data → traces to sessions.

Four reasons for the single join_path SSOT (Single Source of Truth): (1) backend paths differ (local '/', container paths, object-store prefixes, PVC mount points); (2) Windows vs Linux separator/case semantics; (3) path-sanitization gaps create ghost files; (4) security audits need a complete access-surface view.

Declaration vs Instance Separation — Millisecond Startup

.mcp

holds only static metadata (declarations). Real MCPClient connections (subprocess spawns, HTTP sessions, tool-list fetches) are created on first actual tool call. Example: 30 MCP services × full eager init = tens of seconds + 30 long-lived connections; lazy init = milliseconds, LRU eviction after use.

Cache key = (agent_id, session_id) (two-level). Why not agent_id alone? Concurrent sessions under same agent may carry session-scoped headers (tenant IDs, temp credentials, trace IDs) — reuse would leak credentials across sessions. Why not session_id alone? Team orchestration (leader + members) means different agents in one session have different skill sets, tool visibility, permission scopes — reuse would break isolation.

Eight Pluggable Backends Matched to Risk/Isolation Level

Eight backends implement the same WorkspaceBase contract; isolation strength scales with risk:

Local dev → Local backend — zero deps, fast debug

Standard prod → Docker — mature ecosystem, reproducible images

Untrusted input → E2B/OpenSandbox — remote isolation, controllable egress/quotas

Large-scale multi-tenant → K8s — aligns with quota/namespace/RBAC

macOS Apple Silicon → AppleContainer — native, no virtualization layer

Lightweight Linux sandbox → Bubblewrap — process-level isolation

Managed env-as-a-service → Daytona — environment-as-a-service model

Dependency layering: contract layer zero deps, local backend no extra deps, heavy backends opt-in.

Three Fine-Grained Locks + Future Pre-Warming

Three locks protect distinct mutation triggers; merging into one global lock would serialize unrelated operations (e.g., skill assembly blocking all MCP calls), killing throughput.

_bind_locks — protects Workspace instance creation + binding; triggered by concurrent first request for same (agent_id, session_id) _mcp_lock — protects MCP client list _mcps and .mcp file writes; triggered by concurrent first call to an MCP tool

_skill_lock — protects skills/ directory assembly; triggered by concurrent first load of an agent's skills

Double-checked locking pattern: query → acquire lock → re-query inside lock → create only if still absent. Without the inner re-check, high concurrency guarantees duplicate creation: Request A creates, Request B overwrites directories/records, leaving A's in-flight resources pointing to stale or half-written state — a heisenbug invisible in serial tests.

Pre-warming uses asyncio.Future placeholders: identity (agent_id/session_id) not ready yet, so real instance cannot be built. A Future occupies the slot; arriving requests await the same Future. Benefits: (1) identity verification stays correct — no premature instance with wrong credentials; (2) natural deduplication — all waiters share one creation; (3) unified error propagation — creation failure written into Future, all waiters receive it.

In single-process: asyncio.Lock. In multi-worker cluster: upgrade to distributed session lock + CAS lease; same pattern, swap lock implementation.

Skill Anti-Resurrection via _equipped_partitions Marker

Platform seeds skills on new agent deploy; users may delete some. On every startup, framework verifies seed completeness and auto-restores missing ones — causing deleted skills to resurrect. Solution: _equipped_partitions marker records that assembly has run once. Marker present ⇒ skip seed completeness check. First assembly ensures out-of-the-box usability; thereafter user deletions are respected. Principle: idempotency via state marker, not content comparison — content comparison conflicts with user intent.

Partition granularity fixed at agent level: each agent holds independent copy; Agent A's deletion doesn't affect Agent B; skill domains stay isolated.

Skill Index Incremental Cache: Dual-Factor Validation

On startup, no full scan of skill directories. Uses mtime quick filter + SHA-256 content hash for precise invalidation. Single-factor flaws: mtime alone — sync tools, archive extraction, container mounts may preserve/reset timestamps while content changes; hash alone — reading every SKILL.md each scan negates cache value. Layered logic: (1) cheap stat for mtime; (2) only changed mtime dirs get hashed; (3) hash mismatch ⇒ rebuild index entry. Most startups execute only a handful of stat calls.

Four lazy-loading layers compose progressive disclosure: declaration layer (no connections), index layer (no full scan), assembly layer (no repeat), instance layer (no pre-creation) — plus on-demand skill body fetch, deferred instance creation, large-result offload to disk.

Offload to Disk: Large Results Out of Prompt

Tool returns 30k-char logs → stuffing into context balloons token cost every turn, drowns core instructions. Offload writes full payload to data dir; prompt keeps only file path + summary; read-back tool fetches details when needed. Two industry patterns combined: threshold+truncate (simple, loses info) and offload+reference (preserves all, adds I/O roundtrip). Framework runs threshold check first; if exceeded, offloads and leaves summary.

Reusing workspace contract yields: (1) automatic isolation — (agent_id, session_id) scoping means Session A's logs invisible to Session B without extra auth code; (2) backend transparency — local writes to disk, sandbox writes to mounted dir, same join_path call; (3) lifecycle coupling — session teardown auto-cleans artifacts; ad-hoc /tmp usage leaks cleanup logic.

Boundary: offload ≠ state management. Authoritative state model is AgentState, event flow via MessageBus; workspace only provides physical storage location.

Four-Sentence Recap

Extract Workspace abstraction, promoting resource/state/execution concerns from agent business code into platform cross-cutting service.

Unified directory contract + single join_path SSOT; eight backends adapt isolation strength; backend swap requires zero business-code changes.

Declaration/instance split, (agent_id, session_id) two-level lazy loading with LRU eviction and dual-factor index invalidation, keeping startup lightweight.

Concurrency guards front-loaded to assembly phase: bind lock, Future slot, double-check; distributed deploy upgrades to session distributed lock + CAS lease.