harness-engineering-101 README

项目的 README,来自 github.com/IsuruMaduranga/harness-engineering-101。合并为一个 markdown 文件:README.md。

Harness Engineering 101

The LLM is the brain. The harness is the body.

Version 1.1, October 2026.

AI usage disclosure: I drafted every chapter myself, from what I learned building WSO2 MI Copilot, WSO2 BI Copilot and One Code. I used Claude Code and One Code to reorder each chapter so it leads with the answer (the Minto pyramid), to polish the English, to generate the diagrams, and to write the code that draws the charts.

A blog series about building AI agents from first principles, published as a book.

📖 Read it online: https://isuruwijesiri.com/harness-engineering-101/

An LLM API is stateless. Every turn, you send the entire conversation as a JSON array and get text back. A harness is the program that builds, maintains, and protects that array. Everything the field calls "agents" is a set of patches to that one loop, and each patch exists because something concrete broke. This series develops that one idea across 16 chapters, growing a ~300-line toy agent in plain Python as it goes.

I use the same ideas in One Code, an open-source coding agent built on pi.

The rendered book reads best online at the link above. If you'd rather read the source here on GitHub, follow the chapters in order below. The full introduction is on the book's landing page.

Reading order

Every chapter has the same shape: the failure, the minimal patch, what the patch costs.

Part I — The Wire (nothing is magic)

# Chapter The failure it patches
1 It's Just a JSON Array "How do I even talk to this thing?"
2 The Brain: A Next-Token Black Box "Why does it behave like that?"
3 Tools: JSON Mapped to Functions The brain can't touch the world
4 The Agent Loop One tool call isn't enough
5 Caching: Why Order Matters Resending the array gets expensive

Part II — Running Long (the array under pressure)

# Chapter The failure it patches
6 Context Is a Budget, Not a Bag The window fills up
7 Subagents: Fork the Context One array can't hold all the work
8 Steering the Running Loop The brain drifts mid-task
9 Background Work and Time The loop is synchronous; the world isn't

Part III — The Ecosystem (naming what you already understand)

# Chapter The failure it patches
10 Every Framework Is a Wrapper Around Chapter 1 Abstraction anxiety
11 Extending the Body: MCP, Skills, Deferred Loading, Hooks Capabilities don't fit in the array
12 Debugging the Array You can't fix the prompt you can't see

Part IV — Trust, Domains, and Data

# Chapter The failure it patches
13 Reflexes and Guardrails The loop will do something dumb
14 Case Study: Coding Agents How specialized does the body need to be?
15 RAG Was a Harness Pattern All Along A thousand names for one idea

Epilogue

Appendix — Advanced Topics

Standalone pieces. Read them when you need them.

Repository layout

Path What it holds
src/*.md The chapters and appendices (the book source)
src/SUMMARY.md The book's table of contents
src/harness/ The runnable toy harness, one file per stage
src/diagrams/ Diagram generators and their generated PNGs
book.toml mdBook configuration
scripts/sync-to-blog.sh Builds the book and mounts it into the blog for serving

Building the book locally

cargo install mdbook mdbook-mermaid   # or: brew install mdbook (+ mdbook-mermaid binary)
mdbook serve --open                    # live-reloading preview at http://localhost:3000
mdbook build                           # static site into ./book

mdbook-mermaid renders the inline mermaid diagrams; without it those blocks show as raw code.

Regenerating the quantitative diagrams

cd src/diagrams && python3 gen_all.py   # Python 3.10+, matplotlib

License

This repository is dual-licensed:

© 2026 Isuru Wijesiri.

harness-engineering-101 (IsuruMaduranga/harness-engineering-101)

正在搜索数据库…

这是什么?这是一本书(最初是一个博客系列),通过用 Python 从零搭建一个 “harness” 来讲解 AI 智能体的实际工作原理。书中把大语言模型视为无状态的大脑,而 harness 是包裹在它外面的代码,负责管理对话数组、工具和状态。
这是一本书还是一个代码仓库?主要是一本书,共 16 章,外加一个后记和一个附录,可以在线阅读,也可以在 GitHub 上查看。书中的文字会配合各章内容,逐步构建一个约 300 行、可以运行的简化版 Python 智能体(位于 src/harness/)。
这本书是怎么组织的?全书分为四个部分:通信线路、长时间运行、生态系统,以及信任/领域/数据,共 16 章。后记包含一个带完整注释的简化版 harness,另有四个独立的进阶主题附录章节。
想在本地构建这本书需要什么?你需要 mdBook 以及 mdbook-mermaid 插件,才能渲染章节中嵌入的 Mermaid 图表。没有该插件的话,图表会以原始代码块的形式显示。
我可以随意复制或改编这些章节吗?不可以。正文采用 CC BY-NC-ND 4.0 许可,你可以在署名的前提下分享,但不能用于商业用途,也不能发布修改版。只有 src/harness/ 和 src/diagrams/ 下的 Python 代码采用 MIT 许可,可以自由复用。
什么是 'One Code'?One Code 是作者开源的编程智能体,基于名为 'pi' 的运行时构建,实践了本书所讲的 harness 理念。
为什么要从零构建智能体,而不是直接用框架?本书认为,所有智能体框架都只是围绕同一个无状态 JSON 数组循环的封装(见第 10 章)。因此理解这个循环,就能看清你之后使用的任何框架背后的原理。
这本书会讲 RAG 和 MCP 吗?会的。第 15 章把 RAG 重新阐释为一种 harness 模式,第 11 章则讲解如何通过 MCP、Skills、延迟加载和 hooks 来扩展 harness。
大小
1.8 MB
星标
657
更新
提交Nov 02
时长
2个月
提交 · 90 天