# bojieli/ai-agent-book: a 10-chapter open source AI agent book with runnable experiments

> The ai-agent-book repository by Li Bojie publishes the full text of "AI Agents in Depth" under Apache-2.0, alongside per-chapter Python experiments and prebuilt PDF and EPUB downloads. It is a book project with a code repository attached, not a library, and that distinction shapes how you should use it.

**bojieli/ai-agent-book** — 《深入理解 AI Agent：设计原理与工程实践》（李博杰 著）开源主仓库：全书正文、编译版 PDF 与按章配套代码

- Repository: https://github.com/bojieli/ai-agent-book
- Stars: 51,734 · Forks: 5,823
- Language: Python
- License: Apache-2.0
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/bojieli-ai-agent-book

## What ai-agent-book actually is, and who it is written for

This is the main repository for "深入理解 AI Agent：设计原理与工程实践" by Li Bojie. The README describes it as the open source home of the full book text, a compiled PDF, and per-chapter companion code. Ten chapters run from an introduction through context engineering, user memory and knowledge bases, tools, coding agents, interaction, evaluation, model post-training, and continuous evolution. The organizing formula the README repeats is Agent = LLM + context + tools.

The audience is engineers who already write code and want a mental model for agent systems rather than a framework tutorial. The README frames the competitive edge as harness engineering, meaning the scaffolding around a model, not the model itself. That framing tells you who the book is not for: someone looking for a drop-in library, or someone who wants a vendor-neutral survey of commercial agent products. The repository ships prose and experiments, and the value is in reading the prose and running the experiments.

The repository is not archived, and the last push was on 2026-07-21. The README documents a 2.0 revision that merged the old asynchronous interaction material and the multimodal agent material into a new chapter 6, shifting evaluation, post-training, and continuous evolution back by one chapter each. If you are holding an older PDF, the README says to download the latest build.

## The 10-chapter structure and the experiment directories next to it

Each chapter has two artifacts: a Markdown file under book/ and a sibling directory at the repository root. Chapter 1 maps to book/chapter1.md and chapter1/, chapter 2 to book/chapter2.md and chapter2/, and so on through chapter10/. The README's content table lists experiment counts per chapter: 4 for chapter 1, 10 for chapter 2, 12 for chapter 3, 5 for chapter 4, and 16 for chapter 5, with the remaining chapters truncated in the excerpt. The header table states 103 companion experiments in total, including local projects and external reproduction tracks, while an earlier line in the same README says 108. That inconsistency is worth noticing: the two numbers appear in different parts of the same document, and the README does not reconcile them.

Chapter topics are concrete enough to plan around. Chapter 2 covers KV cache behavior, prompt engineering, Agent Skills, and context compression. Chapter 3 covers cross-session user memory, RAG, structured indexing, and knowledge graphs. Chapter 4 covers the MCP protocol and divides tools into perception, execution, and collaboration categories, plus proactive tool discovery. Chapter 5 treats code as the tool that creates new tools and surveys production coding agents. Chapter 6 extends the observation and action space along modality and timing axes.

This layout matters for adoption. You can read a chapter without touching its directory, and you can run a directory without reading the chapter, but the two are designed as a pair. The chapter directory is where the code that the prose describes lives.

## Installing the shared environment and running a first chapter experiment

The repository root contains pyproject.toml, which packages the companion experiments under the distribution name agentbook, version 0.1.0, licensed Apache-2.0. The requires-python field is ">=3.11,<3.14", and a comment in the file explains the lower bound: the maintained python-constraint2 solver imported as constraint by chapter 5 requires 3.11 or newer, while the CUDA and ML stacks used by the training chapters do not yet publish a coherent Python 3.14 wheel set.

Dependencies are split into capability groups so you install only what a given chapter needs. The comments in pyproject.toml give the exact commands, using uv for lockfile-based resolution or pip for a fresh resolve:

```bash
uv sync --extra ch1
uv sync --extra ch7
pip install -e ".[ch1]"
```

The first command installs the chapter 1 group without the GPU stack. The second opts into the heavy fine-tuning dependencies for chapter 7, which the comment says you should opt into explicitly. The third is the pip equivalent for readers without uv, and the comment notes it resolves fresh rather than from the lockfile, so you may get different transitive versions than a uv sync produces.

Provider credentials are separate from package installation. The root .env.example tells you to copy it to .env at the repository root, and it documents three zero-cost paths. The OpenRouter option uses a model id ending in :free, and the file sets OPENROUTER_MODEL=google/gemma-4-31b-it:free. Ollama is the fully local option, with OLLAMA_BASE_URL=http://localhost:11434/v1 and no key required. Direct provider keys are also listed, including MOONSHOT_API_KEY, ARK_API_KEY, SILICONFLOW_API_KEY, DASHSCOPE_API_KEY, DEEPSEEK_API_KEY, KRILL_API_KEY, and ATLASCLOUD_ prefixed variables.

```bash
cp .env.example .env
```

After copying, uncomment the provider you actually use. The file states you do not need all of them, and that the chapter picks a provider and falls back to OpenRouter when that provider's key is absent. One exception is called out explicitly: chapter 1's live $web_search experiment requires Moonshot or Kimi, and the file says OpenRouter cannot substitute for it. The .env.example also warns that some experiments load an adjacent .env file or expect exported environment variables, so you should follow the experiment README when it gives narrower setup instructions.

If you prefer to read rather than run, the README points to prebuilt downloads. The latest build links are stable URLs under the releases/latest tag, including AI-Agents-in-Depth-zh-CN.pdf and AI-Agents-in-Depth-zh-CN.epub for Chinese, plus English, Spanish, Indonesian, Traditional Chinese (Taiwan), Russian, Tamil, Vietnamese, Japanese, Arabic, Turkish, Korean, Hungarian, and Hebrew editions contributed by named community translators. Fixed versions live under the Releases page.

## Building the PDF and EPUB yourself, and what the toolchain demands

The README hides the build instructions inside a collapsible details block, which is a reasonable signal that most readers should not bother. If you do want to rebuild, the EPUB path uses a unified build script documented in EPUB.md. The PDF path is heavier: the README states you need pandoc, xelatex, the ElegantBook document class, and the relevant fonts installed before running the build script from inside the book directory.

```bash
cd book && bash build_pdf.sh
```

Source files are laid out predictably. book/introduction.md holds the introduction, book/chapter1.md through book/chapter10.md hold the chapters, and book/afterword.md holds the afterword. Figures live as SVG files under book/images/ and are used directly at compile time. Typographic details are controlled by book/preamble.tex and Lua files matching book/*.lua.

The practical constraint here is the LaTeX and font dependency chain, not the Markdown. A missing CJK font or a mismatched ElegantBook version will fail the build in ways that are tedious to diagnose, and the README does not enumerate which fonts or which ElegantBook version you need. If you only want to read the book, the prebuilt PDF and EPUB downloads avoid this entirely. Build the PDF yourself only if you are editing the source or need a specific revision that the latest build does not reflect.

## Community translations lag the Chinese original

The README is explicit that the non-Chinese versions are community contributions and may lag behind the Chinese original. The Chinese source lives in book/, while the translations live in separate top-level directories: book-en/, book-es/, book-id/, book-ar/, book-zhtw/, book-ru/, book-ta/, book-vi/, book-ja/, book-tr/, book-ko/, book-hu/, and book-he/. Each translated README credits its translator by handle.

This is a real limitation rather than a footnote. The 2.0 revision restructured chapters 4 through 9, merging asynchronous interaction and multimodal agent material into a new chapter 6 and shifting three chapters back by one position. A translation that has not caught up will present the old chapter numbering, which means a reader following an English or Spanish PDF may be reading a structure that no longer matches the Chinese source, the experiment directories, or the online reading site. The README's own advice is to treat the latest version as authoritative.

If your Chinese reading is adequate, read the Chinese source. If it is not, use a translation but cross-check chapter numbering against the Chinese table of contents before you rely on a chapter-to-directory mapping. The experiment directories are not duplicated per language, so they follow the Chinese structure regardless of which translation you read.

## Where this repository is the wrong tool

The most common mismatch is treating agentbook as a library. It appears on PyPI-style metadata through pyproject.toml, but its stated purpose in that same file is "shared packaging and plumbing for the ai-agent-book companion experiments." There is no documented public API, no semantic versioning promise beyond 0.1.0, and no changelog describing interface stability. If you want a dependency to build a production agent on, this is not it. The dependencies it pulls in, openai, pydantic, python-dotenv, and requests, are the libraries you would actually build on.

A second mismatch is expecting the experiments to run without provider credentials or a local model. The .env.example documents free paths through OpenRouter's :free models and through Ollama, but the Ollama route needs enough RAM to hold the model, and chapter 1's live $web_search experiment cannot be served by OpenRouter at all. The README does not document offline operation for that experiment.

A third is version drift. The README notes the book moved from 1.4 to 2.0 with structural reorganization, and the header table's experiment count of 103 conflicts with the 108 stated elsewhere in the same README. Neither number is dated. If you are citing a specific experiment count or chapter number in your own work, verify it against the current book/ directory rather than the README summary tables.

Finally, the repository does not document rollback, deprecation policy, or a support channel beyond the GitHub issue tracker implied by the repository layout. The README is silent on all three.

## How this compares to a framework's own documentation

The obvious alternative for someone learning agent engineering is the documentation of a framework such as LangChain or an agent SDK, or a hands-on book like "AI Agents in Action." The difference in approach is structural. Framework documentation is organized around that framework's abstractions: you learn its chain, its tool interface, its memory class. The ai-agent-book is organized around a vendor-neutral formula, Agent = LLM + context + tools, and the chapters treat context engineering, memory, and tool design as separate problems with their own mechanisms, such as KV cache behavior, RAG, structured indexing, and the MCP protocol.

That means the book's chapters survive a framework change in a way that framework tutorials do not, but they also give you less runnable scaffolding for a specific stack. The 103 or 108 experiments are the bridge: they are concrete implementations, but the README describes them as companion experiments rather than as a reusable toolkit. If your goal is to ship an agent next week on a specific framework, that framework's own documentation is the faster path. If your goal is to understand why an agent's context window degrades or how tool discovery should work, the chapter structure here is the more useful organizing principle, and you can map its conclusions onto whichever framework you already use.

## Licence, maintenance, and what upgrading costs you

The repository is licensed Apache-2.0, and pyproject.toml declares the same licence for the agentbook package. That permits commercial use, modification, and redistribution with the usual attribution and notice requirements, and it includes a patent grant. The book text and the code sit under the same licence identifier here, which is convenient but worth confirming if you intend to republish translated chapters commercially. This is a description of the licence terms, not legal advice.

Maintenance is best judged by the push history. The repository is not archived and the last push was on 2026-07-21, with a rolling latest build at the same timestamp. The README describes the online reading site as rebuilding automatically on every push to main, so the site tracks the branch rather than a tagged release. There is no documented release cadence, and the only release entry is the rolling latest build.

The upgrade cost of following this project is mostly re-reading. The 1.4 to 2.0 transition moved chapters rather than changing an API, so any notes, bookmarks, or internal links you built against the old numbering will point at the wrong chapter. The rebuild cost is the LaTeX toolchain if you compile the PDF yourself, or nothing if you use the prebuilt downloads. The dependency cost is bounded by the capability groups: a chapter 1 reader installs a light set, while chapter 7 pulls in the fine-tuning stack, and the pyproject comments make that opt-in explicit rather than automatic.

## Conclusion

Adopt this repository if you want a structured, Chinese-first curriculum on agent engineering and you are willing to run the chapter experiments to get value from it. Skip it if you need a maintained Python package to import, if you cannot read Simplified Chinese and cannot accept community translations that the README says may lag the original, or if you need an API stability guarantee that a book repository does not offer. Before committing, check that your Python version falls inside the requires-python range in pyproject.toml, and read the chapter README for the specific experiment you intend to run, because the root .env.example states that some experiments load their own adjacent .env file.

## FAQ

### What is the best book on AI agents?

That depends on whether you want vendor-neutral mechanisms or a specific framework. This repository's book, "深入理解 AI Agent：设计原理与工程实践" by Li Bojie, is organized around Agent = LLM + context + tools and covers context engineering, memory, tools, coding agents, evaluation, and post-training across ten chapters, with companion experiments in per-chapter directories.

### How to build an AI agent book?

The repository structure shows the pattern: write chapter sources as Markdown under book/ (introduction.md, chapter1.md through chapter10.md, afterword.md), keep figures as SVG under book/images/, and build the PDF with book/build_pdf.sh after installing pandoc, xelatex, and the ElegantBook class. The EPUB path uses build_epub.sh and is documented in EPUB.md.

### Which AI agent is the best to learn?

The book does not rank agent products. Its approach is to separate the model from the harness, stating that harness engineering is where the competitive work happens, and to teach context, memory, and tool design as distinct problems. Chapter 5 covers production coding agents as a category rather than recommending one.

### What is Bill Gates' favorite book on AI?

The repository does not mention Bill Gates or any reading list outside this book, so there is nothing to report here.

## Sources

- [Official README](https://github.com/bojieli/ai-agent-book#readme)
- [Project repository](https://github.com/bojieli/ai-agent-book)
- [Release notes](https://github.com/bojieli/ai-agent-book/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bojieli-ai-agent-book