Agent Capsule - A pattern for building production AI agents as document folders powered by coding-agent as runtimes

agent-capsule.md

Agent Capsule

A pattern for building production AI agents as documents, not agent code.

This document presents the core concept, offering a concise and accessible overview to guide implementation.

The Core Idea

Most production agents are built with an Agent SDK (OpenAI, LangChain, LangGraph, etc.). You write code for tool dispatch, memory, sub-agents, session state, and so on. Every new capability requires a code change and a deployment.

The idea here is different: use an existing coding-agent (like claude-code) as agent's runtime engine, and define the agent as a folder of documents. This folder of documents could be also prompted using a coding agent - making the process of agent building, practically prompting.

The runtime already knows how to read a project, load instructions, use tools, maintain memory, and stream output.

This changes the development cycle. Instead of writing more code for any change, you prompt the coding agent to update folder structure and agent's documents. Iterating and delivering significantly faster.

Example: Building an Exec Assistant Agent with a prompt

You are an executive assistant agent for busy managers and executives.

1. Build CLAUDE.md system file.
2. Prep timeblocks - Every week, retrieve all upcoming events for the next 3 weeks. For each event, analyze preparation needs and create dedicated "prep" time blocks on the calendar, well in advance of each event. Ensure all context is available on the calendar event.
3. As you perform these actions, update agent documentation and memories to reflect the evolving needs and preferences of the executive. Use knowledge folder for it. Build any skills and scheduled tasks you need to accomplish the above.

Example directory tree for an agent built using the Capsule pattern:

agent-exec-assistant/
├── CLAUDE.md                # System prompt: identity, rules, behavior
├── skills/
│   ├── prioritize-tasks.md  # Skill: prioritization logic and heuristics
│   ├── calendar-sync.md     # Skill: calendar management and integration
├── knowledge/
│   ├── preferences.md       # Learned knowledge about the user/executive
│   └── org-policies.md      # Knowledge base entry for company policies
├── memory/
│   ├── recap-2024-06.md     # Memory—summarized learnings from June 2024
│   └── last-session.md      # State from the previous session
├── settings.json            # Tools, API credentials, permissions
└── version.json             # Versioning of the agent template

To transition from a local and personal agent to a production grade multi-user agent, we use an orchestration layer that:

1. Takes a template agent folder
2. Provisions isolated user workspaces
3. Runs agent capsules to process inputs This solves important challenges: how do you run this for many users, keep their memories separate, update the shared agent, inject credentials, handle triggers, and capture output.

Architecture

The architecture has two layers:

• Agent Layer - the files and state that define what the agent is.
• Execution Layer - the infrastructure that runs the agent safely for one or many users.

Agent Layer

Template - the reusable agent folder. It contains the developer-controlled files: CLAUDE.md, skills, agents, tool configs, settings.json, and version.json.

Workspace - a persistent per-user or per-org folder created from the template. It contains the template files plus user preferences and agent memory. This is where state lives.

The workspace usually has three layers:

• Layer 1: Template - shared, developer-controlled, versioned.
• Layer 2: User/org preferences - validated customizations.
• Layer 3: Agent memory - facts, summaries, entities, and learned context written by the runtime.

Capsule - an ephemeral secured runtime process spawned against one workspace. It reads the workspace, executes one prompt or session, writes memory back, returns output, and exits. The capsule is stateless. The workspace stores the state.

One template can be used to create many isolated workspaces:

                          EA Agent Template
                 ┌────────────────────────────────┐
                 │ ea-agent/                      │
                 │ ├─ CLAUDE.md                   │
                 │ ├─ skills/                     │
                 │ ├─ settings.json               │
                 │ └─ knowledge/                  │
                 └───────────────┬────────────────┘
                                 │
                      fork one workspace per user
                                 │
                 ┌───────────────┴────────────────┐
                 ▼                                ▼
      ┌───────────────────────────┐    ┌───────────────────────────┐
      │ Liran's EA Agent          │    │ Mike's EA Agent           │
      │ Workspace                 │    │ Workspace                 │
      │                           │    │                           │
      │ template-derived files:   │    │ template-derived files:   │
      │ - CLAUDE.md               │    │ - CLAUDE.md               │
      │ - skills/                 │    │ - skills/                 │
      │ - settings.json           │    │ - settings.json           │
      │                           │    │                           │
      │ user-specific state:      │    │ user-specific state:      │
      │ - knowledge/              │    │ - knowledge/              │
      │ - review preferences      │    │ - review preferences      │
      │ - learned repo context    │    │ - learned repo context    │
      └───────────────────────────┘    └───────────────────────────┘

Execution Layer

Runtime Engine - a coding agent responsible for the main mechanism - loading prompt, using skills, calling mcps, etc. Examples include Claude Code, OpenCode, and Pi.

Capsule Orchestrator - the infrastructure and tooling to manage templates, workspaces and agent capsules. This layer is also responsible to facilitate input and output channels between capsules to the user.

When input arrives, the orchestrator starts a capsule against the right workspace:

User Input / Webhook / Schedule
              │
              ▼
 ┌────────────────────────────┐
 │        Orchestrator        │
 └────────────────────────────┘
              │ spawn runtime_engine(input, workspace)
              ▼
 ┌──────────────────────────────────────┐
 │   Runtime Engine: claude-code        │
 │   Workspace:                         │
 │     Liran (template: pr-agent)       │
 │                                      │
 │   Execute with full context          │
 └──────────────────────────────────────┘
              │ generated response
              ▼
 ┌─────────────────────────────┐
 │        Orchestrator         │
 │  routes output to web/slack │
 └─────────────────────────────┘
              │
              │ agent's output (+streaming)
              ▼
         User / App

Operations

Create. Copy the template into a new workspace, initialize preferences, and create an empty memory area.

Run. Spawn a capsule for a one-shot prompt, webhook, or scheduled task and return output.

Connect. Open a resumable interactive session against a workspace.

Update. Ship a new template version by replacing Layer 1 while preserving preferences and memory. Breaking changes can run migrations.

Delete. Remove the workspace and revoke credentials.

The Orchestrator

To manage Workspaces at scale, you need a thin code layer (an Orchestrator) that sits between your product and the agent runtime. This infrastructure handles:

• Provisioning & Workspace management - Creating Workspace directories from templates when users sign up.
• Trigger handling - Receiving chat messages, scheduled events, or webhooks, and spawning the runtime process against the correct Workspace.
• Scheduling - Owning the scheduler and firing scheduled skills or tasks against the correct Workspace at the right time.
• Credential management - Storing OAuth tokens securely and injecting them as environment variables when spawning the runtime.
• Output routing - Capturing the runtime's streaming stdout and delivering it to the right destination (Web UI, Slack, etc.), including streaming support.

Canopy is an open-source reference implementation of the Agent Capsule pattern. It includes the specs and a basic CLI for provisioning and running Workspaces; the broader orchestration layer is still being built.

Everything that requires intelligence lives in documents. Everything that requires traditional software engineering lives in the orchestration infrastructure.

Discussion & Security

The Agent Capsule pattern is a shift toward "Agent as Data." By treating an existing, highly capable coding agent (like Claude Code, OpenCode, or Pi) as a generic execution engine, the agent itself becomes just a directory of text files.

This approach leverages existing capabilities built into modern coding agents, which already handle substrate functions like context loading, following instructions, tool usage, MCP, file operations, streaming, and session management. The capsule pattern treats these as runtime features and shifts all product-specific behaviors into the document layer.

Robust security is essential for production use. Required controls include:

• Workspace isolation — Each workspace must remain strictly separated.
• Validated user and agent writes — Only authorized changes should be permitted at each layer.
• Template immutability — The foundational (template) layer must not be alterable at runtime.
• Secure credential management — Secrets and OAuth tokens should be safely stored and used.
• Tool allowlisting — Only approved tools should be accessible by the agent.
• Sandboxed execution — Any code or learned skills must run in a tightly controlled environment.

Additionally, each layer (template, user, agent memory) must be composed so that higher layers cannot override or weaken safety rules set by lower ones. All sensitive operations—such as invoking agent tools or modifying memory—should be narrowly scoped and fully auditable to minimize risk.

In summary: the capsule specifies what the agent is, while the orchestrator controls where and how the agent is permitted to run.