This Trending AI Agent Book Tells You Which of Its Own Experiments Don't Run

bojieli/ai-agent-book ships ten chapters and per-chapter code, and the small icon next to each project is the most copyable thing in the repo.

Clone almost any repo that advertises "companion code" and you begin an archaeology project. Some directories run. Some need a dependency the README forgot. Some are a design document wearing a folder name. You find out which is which by burning an evening.

Then there's bojieli/ai-agent-book, currently sitting on the GitHub trending board, which puts one of three icons next to every single project before you clone anything: a checkmark for runs standalone, a book for this is a reproduction guide that depends on an external repo you must fetch yourself, and a construction sign for this is currently a design document and the working code isn't finished.

That legend is the best idea in the repository, and it has nothing to do with AI agents.

What the thing actually is

It's the open-source home of 《深入理解 AI Agent：设计原理与工程实践》, a Chinese-language book on AI agent design and engineering by Bojie Li, Chief Scientist at Pine AI. Apache 2.0. Roughly 2.7k stars, 287 forks, 15 watchers, and 257 commits as of this writing, which is a healthier star-to-fork ratio than most things that trend.

The whole book is in the repo, not just an ad for it. Chapter source lives in book/chapter1.md through book/chapter10.md as plain markdown, the compiled PDF sits beside it, and book/build_pdf.sh will rebuild it if you install pandoc, xelatex, and the ElegantBook document class. Even the figures are generated by committed scripts (book/gen_*_figs.py) rather than pasted in as images with no origin.

Ten chapters, organized around a formula the book states up front: Agent = LLM + context + tools. Chapter 2 covers context engineering, KV-cache-friendly design, and compression. Chapter 4 covers tool design, MCP, and event-driven async agents. Chapter 5 builds a production-grade coding agent. Chapter 6 is evaluation, including statistical significance and eval-driven model selection. Chapter 7 is post-training across SFT and RL. Chapter 10 is multi-agent collaboration, including a section on when multiple agents genuinely beat one, which is a question most multi-agent writing declines to ask.

The code sits in chapterN/project-name/, and the author says chapters 5, 8, 9, and 10 now have runnable demos verified against real LLM APIs.

Why the icons matter more than the chapters

Here's the pattern that made me stop scrolling. The README doesn't just tag each project. It publishes a table of exactly which projects are not standalone-runnable, listing them by name, so you know before you clone. Chapter 7's training experiments, most of chapter 6's benchmarks, browser-use and claude-quickstarts in chapter 9. All flagged as reproduction guides.

Then the appendix goes further. It gives you a copy-paste block of git clone commands for every external dependency, pinned with the commits the book verified against, pointing at benchmarks like SWE-bench, OSWorld, tau2-bench, terminal-bench, and GAIA, plus training frameworks the author forked and adapted under his own account.

And then it does the thing I've never seen a repo do. It has a section for experiments that need physical hardware you probably don't own, naming the SO-100 and XLeRobot arms and pointing at upstream documentation instead of pretending a pip install gets you there. Below that, another section for experiments the book poses as reader exercises with no dedicated code at all, saying so directly.

Four tiers of honesty about what you're getting: runs now, runs after you fetch this pinned commit, runs if you own this robot arm, doesn't run because it's homework.

Compare that to the normal experience of a trending repo, where the README is a sales page and the truth is a stack trace.

The reason this matters beyond politeness is that a repo's README is the only interface most people ever touch. Somebody arrives with forty minutes and a specific question. If the README tells them which forty minutes are worth spending, they get an answer. If it doesn't, they spend the forty minutes on setup, get a missing-dependency error, and form a permanent opinion about the project's quality that has nothing to do with the code. Expectation-setting is not documentation overhead. It's the difference between a person who learns something and a person who leaves.

There's a second-order effect too. Writing the labels forces the author to answer the question honestly for himself. You cannot put a checkmark next to a project without going and running it, which is presumably why the README specifies that chapters 5, 8, 9, and 10 were verified against live LLM APIs rather than assumed to still work.

Put this into practice

Copy the legend into your own README this week. This is the transferable move and it takes twenty minutes. Three symbols, defined once at the top, applied to every example or subproject you ship. Then add the honest inverse: an explicit list of what does not run standalone. The cost is one table. The benefit is that nobody files an issue that's actually a misunderstanding, and nobody walks away deciding your project is broken when it's working as designed.

Sort your own examples by what they depend on, not by topic. The reason this repo's tiers hold up is that the boundary between them is mechanical: does it need a network call to something outside the clone? Does it need hardware? Is there code at all? Those are questions with yes-or-no answers you can check, which is why the labels stay accurate as the repo changes. Tiers based on how polished something feels rot within a month.

Pin the commits for anything external. The reason the reproduction guides in this repo are usable rather than aspirational is that they name the exact upstream commit the author tested against. A git clone without a pin is a promise that decays.

If you want the content, start with the code, not the book. For an English reader, chapter5/coding-agent is the highest-value directory: a working coding assistant in plain Python with the file, search, shell, and project-management tools implemented rather than imported from a framework. After that, chapter2/local_llm_serving (which demonstrates that even a 0.6B local model can do decent tool calling given good system design) and chapter1/context, an ablation study that removes context components one at a time so you can watch agent behavior degrade. That ablation is a better teacher than most prose about context engineering.

Read the cursor-chats/ directory if you write with AI. The author committed the chat transcripts from building the book. Whatever you think of the practice, it's a rare primary document.

The honest limitations

The book is in Chinese, and so is the README. This is the big one and I won't soften it. If you don't read Chinese, you're getting the code directories, the file structure, and whatever survives machine translation of the chapter markdown. The markdown source translates better than a PDF would, which helps. It's still a real tax, and anyone telling you this is a drop-in English resource hasn't opened it.

"Trending" measures momentum, not adoption. The board position reflects how fast attention arrived, not whether anyone finished a chapter. The star count moved while I was researching this, from about 2.1k in indexed search results to 2.7k on the live page. Treat the number as weather.

The clone is smaller than the table of contents suggests. Once you subtract the reproduction guides, the hardware-dependent experiments, and the reader exercises, the volume of code you can actually run today is a fraction of the ten-chapter promise. The repo is honest about this, which is the whole point of the article, and it's still true.

The pinned training forks are one person's branches. Chapter 7 points at bojieli/verl, bojieli/minimind, bojieli/AdaptThink, and others: adapted forks maintained by the author. That's a reasonable way to guarantee reproducibility and it also means you're running an individual's modified branch of a training framework rather than upstream. Read the diff if you're going to run it on anything that matters.

Apache 2.0 covers the repo, not necessarily every subproject. The license section says so plainly: some subprojects carry their own license terms and those govern. If you're pulling code into commercial work, check per directory.

The author's most striking claim is a reproduction of someone else's. The chapter 1 experiment demonstrating LLM in-context learning beating traditional Q-learning by 250 to 400 times on sample efficiency is framed as reproducing a key insight from Shunyu Yao's "The Second Half" essay. Interesting, well-scoped, and a reproduction of a published argument rather than a new finding.

The takeaway

I care less about whether you read this book than about whether you steal its README.

Every one of us has shipped a repo where half the examples worked and the other half needed something we forgot to mention. The fix isn't more documentation. It's a three-symbol legend and a short list of what doesn't run, written at the moment you know the answer instead of leaving your users to discover it.

Go look at your own examples directory. You already know which folders would get the construction sign. Put it there.

Sources: bojieli/ai-agent-book on GitHub; the book directory; chapter1 code; Bojie Li's homepage.