Agent Capsule: "Agents as Data" pattern for production AI agents (gist)

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. Build CLAUDE.md system file. 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. 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: Takes a template agent folder Provisions isolated user workspaces 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…

This excerpt is published under fair use for community discussion. Read the full article at Gist.