Production-Grade Enterprise Agents: Unifying Harness, Skills & Virtual File Systems

Introduction: Three Fundamental Challenges for Enterprise Agents

Moving enterprise agents from demos to production raises three core questions: what a single task may access, how distributed domain experience enters the agent, and where multi-hundred-step work state should persist. Without unified answers, adding more models and MCP tools only yields a capable but ungovernable chatbot. This article proposes an architecture centered on three pillars: a unified harness for execution and safety, skills for domain capability distribution, and a virtual file system (VFS) for long-task context, evidence, and deliverables.

1. The Watershed Is the Runtime, Not the Model

A typical agent prototype consists of a model, system prompt, tools, and a loop returning tool results to the model. This suffices for demos like "query data then generate a report" but fails to answer production requirements: recovery after interruption, context explosion in long tasks, mixing permissioned data domains in one session, where model-generated code runs, who maintains domain prompts, and root-cause attribution for failures (model, tool, skill, or data).

These questions point to the agent harness — not a thin model SDK wrapper but a complete runtime that orchestrates model and tool calls, manages session state and checkpoints, controls tool exposure and human approval, loads skills, provides file and code execution environments, and emits traces for debugging and evaluation. The model sets the ceiling for a single inference; the harness determines whether that capability can enter enterprise processes reliably and controllably. Swapping models may improve answer quality but does not automatically yield permission isolation, failure recovery, asset governance, or delivery evidence.

Two Common but Unsustainable Patterns

One scenario, one agent: Sales prep, finance analysis, and incident inspection each copy a prompt and connect their own tools. Initial delivery is fast, but duplicated base logic diverges — each agent develops different retry, permission, audit, and output conventions, making it hard for domain teams to decide whether to modify the prompt, tool, or model.

Give everyone a coding agent: Coding agents offer strong file, terminal, and code execution capabilities, but they target engineering workspaces. Knowledge workers need business objects, governed data, and shareable reports — not arbitrary shell access. Exposing raw execution power transfers security risk and support cost to users.

Stripe experienced a similar phase before building its Knowledge AI Platform (Kai). Its NoCode Agent Builder produced over 4,000 workflow agents, leading to duplicate prompts, inconsistent quality, and maintenance difficulties. Kai pivoted to a shared runtime platform with domain-contributed skills rather than expanding micro-agent count. Stripe's official retrospective (https://stripe.dev/blog/meet-stripes-knowledge-ai-platform) frames this as a product and runtime boundary reconstruction, not merely retrieval optimization.

2. Overall Architecture: Stable Kernel, Variable Domain Capabilities

A scalable enterprise agent platform splits into four layers:

Entry points where users already work: web chat, enterprise IM, data platforms, ticketing systems, browser extensions. All call the same surface-agnostic API.

Control plane managing fast-changing, domain-owned assets: skills, agent configs, default tool sets, eval sets, versions, quality signals.

Enterprise harness handling unified identity, session scope, permissions, audit, and infrastructure adaptation.

Common runtime responsible for model calls, middleware, streaming events, checkpoints, and recovery.

The layering principle: solve generic agent problems once, keep enterprise-specific concerns at the enterprise layer, let domain experts maintain their knowledge. Stripe's Kai uses Deep Agents/LangGraph for the common runtime, then layers Stripe's own security and internal services. Deep Agents positions itself as an opinionated harness with filesystem, summarization, subagents, persistence, and HITL — not a business application (https://github.com/langchain-ai/deepagents).

Minimal Responsibilities of a Production Harness

A production-grade harness must provide:

Session lifecycle and checkpoint/restore

Tool registry, gateway, and parameter policy enforcement

Skill loading, versioning, and dependency declaration

Virtual file system (VFS) with scoped namespaces

Sandbox execution environment (isolated network, resources, credentials)

Human-in-the-loop (HITL) approval gates

Structured tracing for debugging and evaluation

Multi-surface API (web, IDE, CLI, bot)

These belong to the stable kernel. Business teams should not reimplement checkpoints or sandboxes to add a "weekly report" skill; platform teams should not become bottlenecks approving domain prompts.

3. Skills: Turning Domain Experience into Governable Software Assets

Tools answer "what can be done"; skills answer "in what scenario, following what process, using which tools, to what standard." An API to query pipeline logs is a tool; "locate failed stage, download relevant logs, distinguish code vs infrastructure failure, backfill ticket with fixed evidence format" is a skill.

This distinction makes skills the right boundary for enterprise capability distribution. A skill is neither a monolithic system prompt nor a mere tool description. A complete skill can include:

Metadata for discovery and routing

Model-executed steps, judgment criteria, and failure branches

Declared dependencies on tools, data, and runtime environment

Reusable scripts, reference materials, and artifact templates

Positive examples, near-miss negative examples, and result evaluations

Owner, version, risk level, and change log

Progressive Disclosure Solves Only Half the Problem

Deep Agents uses three-level progressive loading: at startup only skill name and description enter context; when the model deems a skill relevant, the full SKILL.md is loaded; scripts, references, and assets are loaded on demand. Official docs call this progressive disclosure (https://docs.langchain.com/oss/python/deepagents/skills).

Level 1: name + description          all candidate skills, responsible for discovery
Level 2: SKILL.md                    loaded on hit, responsible for execution strategy
Level 3: scripts/references/...      loaded when used, responsible for deterministic capabilities and detailed knowledge

This avoids stuffing all domain descriptions into the system prompt at once, but does not eliminate the catalog selection problem. Dozens of similarly described skills can still cause misselection or hesitation. LangChain's Kai case study reveals that when the system prompt grew to ~150 skills, frontier model selection quality degraded; Kai therefore moved from pure LLM selection to "retrieve or classify pre-filter, then LLM final judgment" (https://www.langchain.com/blog/how-stripe-built-their-knowledge-ai-platform-on-deep-agents).

Thus large-scale skill catalogs need two phases:

Phase 1 (high recall): narrow hundreds to a dozen.

Phase 2 (precision): LLM uses current session understanding for exact selection.

Only then does the harness register the chosen skill's allowed tools. This reduces both context cost and attack surface: irrelevant tools are not merely "discouraged" — they are absent from the model request.

Federated Ownership, Not Central Team Writing All Skills

Enterprise knowledge lives in finance, legal, sales, engineering, and ops. The platform team can define skill specs and runtime but cannot long-term maintain every domain's judgment criteria. A federated governance model works:

Platform team maintains schema, lint, release, permission compilation, evaluation, and observability.

Domain teams own skill content, reference materials, and business acceptance criteria.

Security team maintains mandatory policies and risk templates.

Users or projects may overlay local skills within controlled scope.

Same-name overrides follow explicit base → team → project → user priority.

Kai adopts similar layering: base skills always present, functional default skills loaded by user persona, personal skills added on top. The replicable insight is not Stripe's org chart but "platform does not monopolize knowledge, domain teams cannot bypass platform constraints."

Minimal Data Model for Skill Control Plane

Storing SKILL.md in Git is insufficient. The platform must generate a machine-readable registry and promote risk and quality to first-class fields:

name: release-rollback-weekly-report
version: 1.4.0
owner: devops-governance
domain: engineering.change-management
invocation: model
risk: write
allowed_tools:
  - query_pipeline
  - read_change_order
  - publish_iwiki_with_approval
data_scopes:
  - project:${session.project_id}
surfaces:
  - web
  - codex
eval_suite: evals/routing-and-output.json
status: promoted

These fields must drive runtime behavior: the registry compiles tool allowlists, HITL rules, available surfaces, and eval tasks. CI checks naming, directory consistency, duplicate descriptions, broken references, ownerless promoted skills, and structural issues like "write risk without approval policy."

Evaluate "Right Skill Chosen" Before "Skill Executed Well"

Skill evaluation has two layers. First, catalog routing : does it trigger when it should, confuse with neighbors, select multiple skills for composite tasks, refuse when no match exists. Second, execution result : correct tool calls, sufficient evidence, structured artifacts, no privilege escalation or unnecessary writes.

Optimizing only positive cases per skill is insufficient. High-value tests are near-miss negatives: "query build logs" vs "download build artifacts," "create issue" vs "fix existing MR." As catalog grows, report top-1 accuracy, top-k recall, mistrigger rate, miss rate, token cost, and specific confusion pairs — not just whether the final answer looks plausible.

4. Virtual File System: Long-Task Context Plane and Delivery Plane

Knowledge work isn't a stream of disposable chat messages. A complete task holds raw evidence, downloaded docs, query results, intermediate scripts, cleaned data, charts, report drafts, and final versions. Encoding all into message history causes three problems: escalating context cost, model difficulty locating latest versions, user inability to take over artifacts outside chat.

A Virtual Filesystem (VFS) gives agents familiar operations: ls, read, write, edit, grep. It doesn't require POSIX disk; paths can route to in-memory state, object storage, databases, remote workspaces, or read-only knowledge bases. The key is a stable, addressable, cross-turn workspace.

Suggested Session Filesystem Layout

/sessions/<session-id>/
  scope.json          # project, tenant, environment, permission snapshot bound to this session
  evidence/           # raw read-only evidence pulled by tools
  working/            # intermediate data, scripts, plans, drafts
  artifacts/          # user-consumable reports, charts, documents
  checkpoints/        # recoverable execution state or its index
  manifest.json       # artifact provenance, hash, owner, approval, delivery status

/skills/              # versioned skills, configurable read-only or controlled write
/memories/            # stable cross-session preferences and project conventions
/shared/              # team-shared assets only after explicit publish

Directory structure establishes information lifecycle. evidence/ is immutable by default, preventing models from "correcting" raw evidence; working/ changes freely; artifacts/ are committed outputs; only explicit publish moves content from session-private to /shared/. Thus temporary reasoning state never accidentally becomes organizational fact.

VFS and Sandbox Must Be Separate Boundaries

File persistence and code execution should not share the same host environment. Recommended model: agent runtime runs in a controlled service managing state via VFS; when tasks need Python analysis, chart generation, or PDF/PPT processing, the sandbox is invoked as a tool call.

Kai uses S3-backed multi-tenant VFS, materializing relevant files into the sandbox before execution, syncing changes back afterward; the agent itself runs outside the sandbox. This preserves cross-turn file world consistency while confining model-generated code risk to an isolated execution environment (https://www.langchain.com/blog/how-stripe-built-their-knowledge-ai-platform-on-deep-agents).

Note: Sandbox protects the host, but does not guarantee data safety inside. Input files, network, credentials, runtime limits, CPU/memory, output size, and sync-out paths must each be constrained independently.

How VFS Mitigates Context Bloat

VFS isn't magic to infinitely expand the context window; it separates "what current reasoning must see" from "what the task must retain but need not send every turn." When a tool returns a large log, the harness writes the full result to evidence/build-123.log and returns only path, summary, line count, and hash to the model. Later, if error localization is needed, grep and segmented reads retrieve relevant portions.

Long sessions also need summarization and checkpoints. Summarization compresses past dialogue; VFS retains verifiable facts and artifacts; checkpoints save execution state. They are not interchangeable: summaries alone lose detail, files alone lose decision process, checkpoints alone force every model call to carry full context.

Artifacts Must Carry Provenance and Delivery Status

Generating report.md ≠ delivery complete. Enterprise tasks often need to distinguish: real-time source? data window? local validation passed? pushed? deployed? business-accepted? A manifest.json serves as artifact contract:

{
  "artifact": "artifacts/rollback-weekly-report.md",
  "generated_at": "2026-08-06T10:30:00+08:00",
  "session_scope": {
    "project": "appset",
    "environment": "production-readonly"
  },
  "sources": [
    {"path": "evidence/change-orders.json", "sha256": "..."}
  ],
  "validation": {
    "local": "passed",
    "remote_pipeline": "not_run",
    "deployed": false,
    "accepted": false
  },
  "approvals": []
}

This lets UIs, downstream agents, and audit systems read structured facts instead of guessing true state from natural language "already done."

5. Security: From User Permissions to Session Capabilities

Traditional apps authorize by user identity: can this user read a project, modify a config? Agents add a delegation layer — user authorizes agent for a task. The user's full permissions should not automatically become the task's full permissions.

A sound effective capability model:

effective capability
  = user authorization
  ∩ agent configuration
  ∩ selected skill policy
  ∩ session/task scope
  ∩ tool-side enforcement

Example: a user with access to Customer A and B should not read B during an A-focused analysis. Session creation binds customer_id=A; tool services verify request target stays in scope. Model cannot widen scope via parameter tricks; sandbox scripts cannot bypass the same constraints.

Prompt Is Not a Security Boundary

"Do not access other customers" and "ask before writes" help the model choose correctly but cannot be the final control. Deep Agents' README explicitly adopts a "trust the LLM" model: the agent may do anything the tool allows; boundaries must be set at the tool or sandbox layer (https://github.com/langchain-ai/deepagents#security).

At least four gates are needed in practice:

Tool visibility: only register tools required by the current skill.

Parameter policy: tool gateway validates tenant, project, environment, object, and operation type.

Execution isolation: shell, scripts, and document parsing enter per-session sandbox with restricted network and resources.

Human approval: publish, delete, production changes, and cross-scope reads interrupt before execution.

Framework-built-in filesystem permissions also have limits. Deep Agents docs note its declarative permissions constrain only built-in file tools, not custom tools or MCP; sandboxes with arbitrary command execution need independent policies (https://docs.langchain.com/oss/python/deepagents/permissions). Therefore allowed-tools, MCP server permissions, sandbox policy, and business API authorization must be combined.

6. How a Request Traverses the Platform

Assembling the pieces, a request like "analyze last week's rollbacks for a project and publish a weekly report" should not become a single model call with all tools. Instead it follows an observable, interruptible execution chain:

Deliberate design choices: scope fixed at session gateway (not inferred by model); candidate skills and tool sets progressively narrowed; tool results become evidence files first, not unstructured context; write operations approved before actual call; final response references manifest state, not free-form model description.

State Split into Three Categories

Implementation can explicitly separate state:

class SessionContext(TypedDict):
    # immutable after session creation, not model-editable
    user_id: str
    tenant_id: str
    project_id: str
    environment: str
    capability_id: str

class AgentState(TypedDict):
    # checkpointable execution state
    messages: list
    plan: list
    selected_skills: list[str]
    pending_approvals: list[str]

class ArtifactState(TypedDict):
    # large objects and delivery facts saved via VFS
    evidence_paths: list[str]
    artifact_paths: list[str]
    manifest_path: str

Immutable session context must not mix with model-editable files or messages; AgentState suits checkpoint/restore; ArtifactState stores only paths and indexes, large files managed by VFS backend. This avoids accidental permission changes during summarization and prevents checkpoint databases from repeatedly serializing large documents.

7. Evolve from Existing Tooling, Not Rewrite Everything

Enterprises already have MCP, internal APIs, scripts, knowledge bases, and assorted agents. Introducing a unified harness doesn't mean rewriting all capabilities. A pragmatic path: unify the control protocol first, then incrementally replace the execution kernel.

Phase 1: Establish Asset and Risk Baseline

Inventory existing agents, skills, tools; answer five questions: who owns, which entry points, what data read, what writes possible, how success judged. Extract reusable domain flows from prompts into skills, distill deterministic logic into scripts or tools, convert global security reminders into runtime policies. Deliverables: registry, lint, eval baseline — not a new chat UI. Without baselines, later improvements cannot be proven safer or more accurate.

Phase 2: Adopt Unified Harness

Pick a high-frequency, read-heavy, low-write process with clear artifacts (e.g., run reports, account research, incident patrol). Route existing entry points through unified session API; place legacy tools behind tool gateway; create task scope; migrate tool results and reports into VFS. Do not build complex RAG, multi-agent collaboration, or self-improvement in v1. Verify the basic loop: task recovery, correct skill selection, evidence traceability, write blocking, user artifact takeover.

Phase 3: Two-Phase Skill Routing

While catalog stays in the dozens, measure pure LLM routing first — don't assume vector retrieval is better. As skill count and description overlap grow, add domain tags, keywords, embeddings, or lightweight classifiers for pre-filtering. Compare at least:

Top-1 and top-k selection quality

Skill/tool tokens injected per request

Latency to first valid tool call

Irrelevant tool exposure count

High-risk skill mistrigger rate

Only adopt pre-filter layer when it yields net gains on these metrics, justifying index updates, recall tuning, and permission filtering complexity.

Phase 4: Trace-to-Skill Improvement Loop

Production traces' highest value isn't call-chain visualization but finding harness and skill gaps: users repeatedly correcting same judgment, tool often failing then falling back, same task class repeatedly needing manual context, skill being preempted by neighbor. These patterns should auto-generate candidate regression cases and fix proposals.

But production agents must not directly modify production skills. Proper flow: trace detects issue → generate candidate patch and eval → owner review → run regression in isolation → merge and release. This leverages agents for self-analysis while preserving domain accountability and change audit.

8. Measuring Real Adoption

Agent platforms cannot rely on "call count" and "users say it's good." Track four metric groups:

Denominators must be explicit. "80% completion rate" needs clarification: 80 of 100 tasks that entered execution, or 80 of 85 after excluding clarifications, cancellations, and permission denials. Business impact must separate correlation from causation: high-skill users may adopt agents more; complex tasks naturally require more calls. Pre-launch baselines are more reliable than post-hoc growth percentages.

9. Five Common Pitfalls

Turning unified harness into a new monolithic agent: Unify execution, security, governance — not all domain prompts into one super-prompt. Skills remain domain-owned and loaded on demand; tools dynamically exposed.

Treating allowed-tools as full authorization: It only describes what the model should see in a skill. Real authorization lives in tool gateway and target service; MCP, custom scripts, sandbox must not become bypasses.

Treating VFS as an indefinite knowledge base: Session working files, organizational knowledge, and long-term memory have different lifecycles, ownership, compliance. Without publish process and TTL, VFS becomes another data swamp.

Premature multi-agent adoption: Subagents suit isolating large intermediate context or providing specialized capabilities, but add state, cost, permission inheritance, debugging overhead. If a deterministic script or single-agent plan works, don't split just because the framework supports it.

Only validating the happy path: Critical tests include permission denial, tool timeout, publish interruption, sandbox resource exhaustion, skill conflict, evidence expiry. An agent that only completes when all dependencies are healthy is still a demo.

10. Conclusion: Treat Agent as Platform Capability, Not Chat Feature

Enterprise agent competitiveness won't come long-term from "which latest model is integrated." Models will keep rotating; the enduring assets are: reusable, owned skills; verified tools and permission boundaries; recoverable execution state; traceable evidence and artifacts; and the engineering loop from production traces back to evaluation and improvement.

Unified harness, skills, and VFS solve three distinct layers: harness makes execution reliable and controllable; skills let scattered domain experience evolve independently; VFS gives long tasks stable context and delivery vehicle. Combined, the agent ceases to be a tool-calling chatbot and becomes a digital collaborator that can embed in enterprise workflows, own long-running tasks, and submit to governance.

This is the most transferable lesson from Stripe's Kai: not copying a framework name or chasing "built in a week" marketing numbers, but placing generic agent infrastructure, enterprise security boundaries, and domain ownership at the right layers. Frameworks can be swapped, models upgraded; with clear boundaries, enterprise capabilities don't rewrite with every tech choice.