Skip to content

docs: update concept page with architecture diagram and fix broken links #734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FL4TLiN3 merged 2 commits into from
Mar 8, 2026
Merged

docs: update concept page with architecture diagram and fix broken links #734

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e034afc
docs: update concept page with architecture diagram and fix broken links
FL4TLiN3 Mar 8, 2026
2f070ac
docs: align concept card sections with architecture diagram layers
FL4TLiN3 Mar 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 57 additions & 18 deletions docs/understanding-perstack/concept.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,40 +11,79 @@ Perstack is built on a concept called **Expert Stack** — the harness that enab
> [!NOTE]
> The name "Perstack" combines the Latin word "perītus" (meaning "expert") with "stack". Perstack = Expert Stack.

## Expert Stack
## Expert Stack

Perstack organizes the complexity of micro-agents harness design into a simple stack model:
An agent harness needs a broad set of capabilities — almost like an operating system. Perstack organizes them into a simple stack with clear separation of concerns:

### Definition
```
┌──────────────────────────────────────────────────────────────────-┐
│ Interface │
│ CLI · Event streaming · Programmatic API │
├──────────────────────────────────────────────────────────────────-┤
│ Runtime │
│ Agentic loop · Event-sourcing · Checkpointing · Tool use │
├──────────────────────────────────────────────────────────────────-┤
│ Context │
│ System prompts · Prompt caching · AgenticRAG · Extended thinking │
├──────────────────────────────────────────────────────────────────-┤
│ Definition │
│ Multi-agent topology · MCP skills · Provider abstraction │
├──────────────────────────────────────────────────────────────────-┤
│ Infrastructure │
│ Sandbox isolation · Workspace boundary · Secret management │
└──────────────────────────────────────────────────────────────────-┘
```

Most of the features above are not new ideas. Perstack takes the usual harness building blocks — tool use, delegation, checkpointing, prompt caching, etc. — makes them easy to operate, puts them on top of standards you already know (MCP, TOML, Docker, SSE), and ships them as one runtime. Where cost or operational burden demands it, Perstack introduces its own take — micro-agents being the first example.

### Interface

The top layer exposes Perstack to users and applications.

<CardGrid>
<LinkCard title="Experts" href="/understanding-perstack/experts">Purpose-specific micro-agents.</LinkCard>
<LinkCard title="Skills" href="/references/skills">MCP tools (file ops, exec, custom MCP servers).</LinkCard>
<LinkCard title="Providers" href="/references/providers-and-models">LLM providers and models.</LinkCard>
<LinkCard title="perstack.toml" href="/references/perstack-toml">Declarative definition of experts, skills, and providers.</LinkCard>
<LinkCard title="CLI" href="/docs/references/cli/">Interactive TUI (`start`), headless JSON output (`run`), log inspection, and expert management.</LinkCard>
<LinkCard title="@perstack/runtime" href="/docs/guides/adding-ai-to-your-app/">Embed the runtime directly in TypeScript apps for serverless and custom integrations.</LinkCard>
<LinkCard title="Observability" href="/docs/operating-experts/observing/">Real-time activity log, token metrics, and delegation tree.</LinkCard>
</CardGrid>

### Runtime

The execution engine that drives the agentic loop.

<CardGrid>
<LinkCard title="Runtime" href="/docs/understanding-perstack/runtime/">9-state machine — generate, call tools, delegate, resolve, and finish.</LinkCard>
<LinkCard title="Events" href="/docs/references/events/">Step-level event-sourcing for full execution observability and replay.</LinkCard>
<LinkCard title="State management" href="/docs/using-experts/state-management/">Checkpoints, resume, and job hierarchy.</LinkCard>
<LinkCard title="Skill management" href="/docs/operating-experts/skill-management/">Dynamic skill lifecycle — connect, discover tools, execute, disconnect.</LinkCard>
</CardGrid>

### Context

What each expert sees and knows during execution.

<CardGrid>
<LinkCard title="Context windows" href="/understanding-perstack/context-windows">The context in which experts operate.</LinkCard>
<LinkCard title="Workspace" href="/understanding-perstack/workspace">The shared workspace in which experts operate.</LinkCard>
<LinkCard title="Delegations" href="/understanding-perstack/delegations">The delegation of tasks to other experts.</LinkCard>
<LinkCard title="Memory" href="/understanding-perstack/memory">The memory of the expert stack.</LinkCard>
<LinkCard title="Workspace" href="/docs/using-experts/workspace/">The shared filesystem where experts collaborate — not conversation history.</LinkCard>
<LinkCard title="Error handling" href="/docs/using-experts/error-handling/">Retries, provider-specific error normalization, and retryability detection.</LinkCard>
</CardGrid>

### Runtime
### Definition

How you declare what experts do and how they collaborate.

<CardGrid>
<LinkCard title="Event-sourcing" href="/references/events">The event-sourcing of the expert stack.</LinkCard>
<LinkCard title="Checkpoints" href="/references/checkpoints">The checkpoints of the expert stack.</LinkCard>
<LinkCard title="Skill management" href="/references/skill-management">The skill management of the expert stack.</LinkCard>
<LinkCard title="Experts" href="/docs/understanding-perstack/experts/">Purpose-specific micro-agents with a single responsibility.</LinkCard>
<LinkCard title="perstack.toml" href="/docs/references/perstack-toml/">Declarative config — experts, skills, providers, and global defaults.</LinkCard>
<LinkCard title="Skills" href="/docs/making-experts/skills/">MCP tools — file ops, exec, custom MCP servers.</LinkCard>
<LinkCard title="Providers" href="/docs/references/providers-and-models/">LLM providers, models, and model tier selection.</LinkCard>
</CardGrid>

### Infrastructure

Isolation and security boundaries that make agents safe to operate.

<CardGrid>
<LinkCard title="Container isolation" href="/understanding-perstack/container-isolation">The container isolation of the expert stack.</LinkCard>
<LinkCard title="Workspace boundaries" href="/understanding-perstack/workspace-boundaries">The workspace boundaries of the expert stack.</LinkCard>
<LinkCard title="Env vars/secrets" href="/understanding-perstack/env-vars-secrets">The env vars/secrets of the expert stack.</LinkCard>
<LinkCard title="Sandbox integration" href="/docs/understanding-perstack/sandbox-integration/">Container isolation with Docker — multi-arch, non-root, ~74 MB.</LinkCard>
<LinkCard title="Boundary model" href="/docs/understanding-perstack/boundary-model/">Workspace boundaries, path validation, and symlink traversal prevention.</LinkCard>
<LinkCard title="Isolation by design" href="/docs/operating-experts/isolation-by-design/">Environment sandboxing, secret management, and exec protection.</LinkCard>
<LinkCard title="Deployment" href="/docs/operating-experts/deployment/">Container images, `perstack install`, and production deployment patterns.</LinkCard>
</CardGrid>