Agentic Systems Baseline

A documentation-first baseline for designing, communicating, and reviewing production-grade agentic system architecture.

The latest static build is deployed at https://site-kappa-two-39.vercel.app/.

What this is

This repository is a structured reference for teams that are moving agentic AI from prototype to production. It collects the engineering lessons that show up again and again in production incidents, research papers, and field reports — loops, pipelines, tools, memory, routing, observability, security, resilience, and token economics — and turns them into concise, diagram-backed guides.

The baseline is opinionated but not prescriptive. It gives architects and engineers a shared vocabulary and a set of tested patterns so they can discuss, design, and review agentic systems without rebuilding the same mistakes from scratch.

Why it exists

The models are not the bottleneck. The failures come from the engineering around them:

• unbounded agent loops,
• growing context windows with no budget,
• guardrails written only in prompts instead of code,
• tools wrapped without failure-path handling,
• no observability into what the agent actually did.

This baseline treats the harness — the runtime, tooling, controls, and observability around the model — as the architecture. The model is one component inside that larger system.

What you will find

• Concepts — 16 engineering guides covering the full lifecycle of an agentic system, from production realities to context budgets.
• Architecture — C4 Context and Container, UML sequence and activity, BPMN workflow, D2 system layer, and DBML data-model views.
• Diagrams as code — every diagram is a plain-text source file under docs/diagrams/ and is rendered through a Kroki server.
• References — an aggregated, topic-grouped list of all external sources used in the concept pages.
• LLM-friendly copy button — every rendered page includes a "Copy for LLM" button that copies the original Markdown source to the clipboard.

Concepts at a glance

Page	What it covers
Production Realities	Cost explosions, control failures, provider outages, and the real reason agents fail in production.
Agent vs Workflow	The seven-level autonomy ladder and when to stop climbing it.
Pipeline	The request pipeline: validation, enrichment, context assembly, generation, and post-processing.
Agent Loop	ReAct loops, guardrails, termination taxonomy, and recovery strategies.
Tools and MCP	Tool design, MCP wiring, schema constraints, and failure-path responses.
Observability	Traces, metrics, OpenTelemetry GenAI conventions, and agent-specific signals.
Agent Security	Prompt injection, confused deputy, excessive agency, and defense in depth.
Resilience	Fail-closed, fail-open, graceful degradation, and surviving provider outages.
Harness Engineering	Guides, sensors, and the runtime controls that keep agents safe and useful.
Token Economics	Jevons paradox, hidden reasoning tokens, caching, and cost attribution.
Model Selection	API vs self-host vs hybrid, evaluation on your own data, and routing portfolios.
Smart Routing	Cost-quality routing, cascades, and cache-aware model switching.
RAG vs Long Context	When to retrieve, when to stuff the window, and how to combine both.
Memory Architecture	Procedural, semantic, episodic, and working memory through the CoALA lens.
Claude Code Memory	Production memory architecture from the leaked Claude Code build analysis.
Context Budget	Token budgets, compression, caching, and thinking strategy.

Architecture views

The architecture section uses multiple notations so each view answers a different question:

• C4 — Who uses the system and what are the containers?
• UML — How do runtime interactions and activities flow?
• BPMN — What are the workflow-level coordination steps?
• D2 — How do layers and components relate spatially?
• DBML — What is the data model?

All diagram sources live in docs/diagrams/ and are embedded through kroki-<type> fenced blocks.

Stack

• MkDocs Material for the documentation site.
• mkdocs-kroki-plugin to render diagrams through a Kroki instance.
• Kroki for converting plain-text diagram sources into SVG.
• mkdocs-copy-markdown to add a "Copy for LLM" button to every page.

Repository layout

.
├── mkdocs.yml             # MkDocs + plugins configuration
├── requirements.txt       # Python dependencies
├── README.md              # This file
├── docs/
│   ├── index.md
│   ├── concepts/          # Conceptual guides
│   ├── architecture/      # C4, UML, BPMN, D2, DBML views
│   └── diagrams/          # Authoritative diagram source files
└── site/                  # Generated static site (ignored by git)

Getting started

Install Python dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Serve locally:

mkdocs serve --dev-addr=127.0.0.1:8001

Then open http://127.0.0.1:8001.

Build a static export:

DISABLE_MKDOCS_2_WARNING=true mkdocs build --strict

The generated site is written to site/.

Kroki server

Diagrams are rendered by the mkdocs-kroki-plugin. By default it uses the public kroki.io server. To use a different server, set the KROKI_SERVER_URL environment variable:

export KROKI_SERVER_URL=https://your-kroki.example.com
mkdocs serve

Deployment

The project is deployed to Vercel as a static site built from the site/ directory.

DISABLE_MKDOCS_2_WARNING=true mkdocs build --strict
vercel --prod site

The current production deployment is at https://site-kappa-two-39.vercel.app/.

Adding diagrams

1. Add or edit the source file under docs/diagrams/.

2. Reference it from the matching page in docs/architecture/ with the appropriate kroki-<type> fence:

   ```kroki-plantuml
   @from_file:diagrams/c4/context.puml
   ```

3. Run mkdocs serve or mkdocs build to render.

Conventions

• All documentation is written in English.
• C4 Context and Container diagrams use PlantUML with the C4 stdlib.
• UML sequence diagrams use plain PlantUML.
• Workflows are modeled in BPMN 2.0 XML.
• System topology and component diagrams use D2.
• Entity-relationship models use DBML.
• Architecture pages include explanatory prose around each embedded diagram to describe what it shows, the notation used, and how it maps to baseline concepts.

Contributing

This baseline is a living document. When you add a new concept or expand an existing one:

• keep the prose engineering-focused and cite sources,
• add diagrams as plain-text sources under docs/diagrams/,
• update docs/concepts/references.md with the full citation,
• run mkdocs build --strict before committing.