AI Agent Engineering Handbook

An organized collection of patterns, architectures, and implementation details from 30+ AI agent frameworks — extracted by reading their actual source code, system prompts, and compaction logic.

Not opinions. Not tutorials. Just documented patterns from codebases that are running in production.

Most agent knowledge in 2026 is either surface-level blog posts or buried in source code nobody has time to read. We went through the codebases of OpenClaw, Claude Code, LangGraph, CrewAI, Hermes Agent, and 25+ others to document how they actually work — the agent loops, the prompt assembly, the context management, the memory systems, the tool architectures.

• LangGraph vs CrewAI vs PydanticAI — which one for what?
• How does OpenClaw's SOUL.md / AGENTS.md pattern work and why does everyone copy it?
• Why do agents get worse the longer they run? (context rot, and 12 ways to fight it)
• MCP servers are eating 72% of my context window — how do I fix tool sprawl?
• Should I use one agent or multiple? When does multi-agent actually help?
• How does Claude Code handle compaction? What survives, what gets dropped?
• What's the actual agent loop code? Is it really just a while loop?
• Skills as markdown vs. compiled tools — what do the top frameworks use?
• How does Hermes Agent improve itself over time? (episodic memory + self-evolution)
• What's the minimum viable agent architecture for production?

Things we found that weren't obvious:

• A 100-line agent scores 74% on SWE-bench. The loop is the easy part. Context assembly, tool design, and memory are what matter.
• Context quality degrades starting at ~25% window fill, not at 100%. Every frontier model tested shows this (Chroma Research, 18 models).
• Three MCP servers consumed 143K of 200K tokens with tool descriptions alone — before the agent read a single user message. Tool selection accuracy drops from 43% to 14% with bloated toolsets.
• Personality and operational instructions should be separate files. OpenClaw, Claude Code, and Hermes converged on this independently.
• The primary reason to use sub-agents is context isolation, not parallelism. Anthropic measured 90.2% improvement.
• Skills defined as markdown files (not code) is the dominant extensibility pattern across Claude Code, OpenClaw, and Cline. Progressive 3-tier loading cuts token cost by 94%.
• Re-injecting instructions near the end of context defeats "instruction centrifugation" — system prompt influence fading as context grows.

_{Star counts as of March 2026.}

Coding agent             → Claude Agent SDK, Cline, Roo Code
Visual / no-code         → n8n, Dify, Langflow
Personal assistant       → OpenClaw, Hermes Agent
Multi-agent (graphs)     → LangGraph
Multi-agent (roles)      → CrewAI
Enterprise .NET/Java     → MS Agent Framework, Google ADK
Type safety              → PydanticAI
TypeScript native        → Mastra
Minimal footprint        → smolagents
Self-improving           → Hermes Agent
Browser automation       → browser-use, Stagehand

├── README.md
├── COMPREHENSIVE_AGENT_ENGINEERING_GUIDE_2026.md   ← The guide (~5,000 lines)
├── COMPREHENSIVE_AGENT_ENGINEERING_GUIDE_2026.pdf  ← PDF version
├── CONTRIBUTING.md
└── LICENSE

Contributions welcome. See CONTRIBUTING.md.

Corrections, new framework analyses, production patterns you've discovered — anything that makes this more accurate and useful.

Dmitriy Vasilyev · AI Enthusiast

MIT