By peter_lzh Deep Understanding of AI Agents: A Free Chinese Technical Book on Design Principles and Engineering Practice
“Deep Understanding of AI Agents: Design Principles and Engineering Practice” is a Chinese technical book open-sourced by Li Bojie. The repository provides not only the full text and a compiled PDF, but also releases the experiment code, the figure-generation scripts, and community translations in several languages.
The whole book revolves around one core formula:
LLM is responsible for thinking and decision-making, context determines what the model can see, and tools determine what it can do. In reinforcement-learning terms, the three map to Policy, Observation Space, and Action Space. This turns prompts, memory, RAG, MCP, and code execution from unrelated tricks into different positions within the same agent system.
The book repeatedly stresses the Harness: the engineering capability outside the model that constrains and supports the agent, such as state, permissions, scheduling, tool validation, context management, and evaluation. A stronger model does not automatically fill in these parts for you.
Content Overview
The book is built around the core formula Agent = LLM + Context + Tools, across ten chapters:
- Chapter 1, Agent Basics starts from the new “model is the agent” paradigm, establishes the core formula Agent = LLM + Context + Tools, and introduces Harness engineering, the engineering capability outside the model, as the real source of competitiveness.
- Chapter 2, Context Engineering determines the ceiling of an agent’s ability. It covers the context structure of large-model APIs, KV-cache-friendly design, prompt engineering, dynamic prompts and agent skills, status-bar meta information, and context compression strategies.
- Chapter 3, User Memory and Knowledge Base lets an agent remember users across sessions and connect to external knowledge. It covers user memory systems, the basic RAG pipeline, and knowledge organization and retrieval beyond flat text (structured indexes, knowledge graphs, and more).
- Chapter 4, Tools are the agent’s hands. It covers tool classification and general design principles, the MCP protocol and the challenge of tool selection, the three categories of perception, execution, and collaboration tools, and event-driven asynchronous agents.
- Chapter 5, Coding Agent and Code Generation code is “a tool that creates new tools,” a meta-capability of general agents. Using a production-grade coding agent as an example, it shows the complete implementation of this strongest general-purpose tool.
- Chapter 6, Agent Evaluation turns an agent’s performance into comparable signals, from evaluation environments, dataset design, and metric systems to statistical significance, observability, evaluation-driven selection, and production-grade internal evaluation with simulation environments.
- Chapter 7, Model Post-Training a panorama of the three stages of pre-training, SFT, and RL. When to choose SFT versus RL, RLHF, algorithm comparisons, data and environments, and frontier exploration on teaching models tool calling and improving sample efficiency.
- Chapter 8, Agent Self-Evolution growth without changing weights. Three learning paradigms, from learning from experience and active tool discovery to “from tool user to tool creator,” move the agent from “smart” to “proficient.”
- Chapter 9, Multimodal and Real-Time Interaction extends perception and action from text to speech, GUI, and the physical world. The three speech paradigms (cascade, end-to-end full-modal, full-duplex), streaming speech perception and synthesis, Computer Use, and robotic manipulation.
- Chapter 10, Multi-Agent Collaboration the intelligence of a group can exceed that of an individual. A classification framework for multi-agent systems, when they truly beat a single agent, collaboration with shared versus unshared context, failure modes, and the emergent “agent society.”
The Real Differentiator: The Accompanying Experiments
The repository lets you verify nearly 80 chapter-organized project directories. They are not just pseudo-code snippets, but concrete controlled experiments that ground the book’s ideas.
Prompt-injection attack and defense: construct direct injection, indirect injection, and memory injection, then layer prompt hardening, source marking, and runtime validation. Readers see not just “defend against injection” but what context defense versus execution-layer fallback each solves.
Coding Agent: implement file read/write, search, shell, notebook, and task-list tools in Python, add status prompts, persistent shell, and post-write syntax checks, showing how the Harness outside the model affects usability.
Agent evaluation: beyond benchmarks such as Terminal-Bench, SWE-bench, GAIA, and OSWorld, the repository also provides experiments on model latency, throughput, success rate, and task cost analysis, turning “this model feels better” into comparable data.
Self-evolution and multi-agent: experiments ranging from distilling experience from successful trajectories and actively discovering tools to long-document translation, multi-role handoff, and private-context isolation collaboration cases.
Note that these directories vary in completeness: some are demos runnable after configuring an API key, some are reproduction guides depending on external repositories, and some are mainly design documents. The training and evaluation projects in chapters six and seven, plus some browser, robot, and multi-agent experiments, need extra code, GPU, external environments, or even real hardware.
One Map to Understand the Book’s Engineering View
You can compress the ten chapters into this learning map:
This is also what sets the book apart from “write a chatbot by following a framework’s API.” It does not attribute an agent’s ability entirely to the model, but treats context quality, tool boundaries, execution feedback, and independent verification as parts of the system capability.
For example, prompt injection cannot be solved by a single system prompt; high-risk operations still need execution-layer confirmation. Generating a PPT should not let the model declare success after writing the code; instead the page must be rendered and then checked and iterated by a vision model. These are concrete forms of the Harness in real tasks.
You Do Not Have to Read It Straight Through
If you are just starting to study agents systematically, read chapters one and two first to build the core formula and understand context, then pick one experiment each from the memory, RAG, and tools chapters of three and four to try hands-on.
To build a coding agent, focus on chapters two, four, five, and six: understand context and tools, see the full implementation, then use evaluation to check whether your changes actually help.
For model training, connect chapters one, two, six, and seven. Chapter six’s evaluation is the premise of chapter seven’s training, otherwise it is hard to tell what SFT or RL actually improved.
If you already ship products, jump by problem: context bloat in chapter two, memory and knowledge base in chapter three, async tools in chapter four, cost and model selection in chapter six, multimodal and collaboration in chapters nine and ten.