IsuruMaduranga/harness-engineering-101

What it solves

LLM APIs are stateless: each turn you send the whole conversation as a JSON array and get text back. That makes building agents confusing. This book clarifies that everything called an “agent” is just a set of patches to that one loop. It addresses common failures like the model losing context, tool calls being limited, and the array growing too large, and it explains why frameworks exist and what they actually do.

How it works

The series walks through 16 chapters, each following the same shape: the failure, the minimal patch, and the cost of that patch. It grows a ~300-line toy agent in plain Python as it goes. The book is split into parts — The Wire (basics), Running Long (handling long contexts), The Ecosystem (frameworks and extensions), and Trust, Domains, and Data (guardrails, coding agents, RAG). It also includes appendices on advanced topics like model routing, worktrees, plan mode, and retries/streaming. The full source chapters live in src/*.md, along with a runnable toy harness in src/harness/ and diagram generators.

Who it’s for

Developers who want to understand AI agents at a fundamental level rather than just using high-level frameworks. It’s for anyone building LLM applications who has felt confused by the magic of agent frameworks or struggled with context management, tool calls, or debugging prompts. The author’s practical experience from building WSO2 copilots and the One Code coding agent grounds the explanations in real-world lessons.

Highlights

• Grows a toy agent from scratch in plain Python, showing each incremental step.
• Each chapter follows a consistent pattern: failure, minimal patch, cost.
• Covers essential topics: tools, caching, subagents, context budgeting, steering, guardrails, RAG, and more.
• Includes appendices on model routing, isolation with worktrees, plan mode, retries, rate limits, and streaming.
• Dual-licensed: prose under CC BY-NC-ND 4.0, code under MIT, so you can reuse the code freely.