Introduction
"Agent = LLM + Context + Tools"
This is article #188 in the "One Open Source Project a Day" series. Today's project is AI Agents in Depth: Design Principles and Engineering Practice — written by Li Bojie (bojieli), with the full text, diagrams, and 95 hands-on experiments all open-sourced, and PDF/EPUB available for free download.
35,525 Stars, created September 2025, Apache-2.0. This is one of the most systematic AI agent technical books available, covering everything from foundational principles to production engineering, with 10 chapters spanning context engineering through multi-agent collaboration, paired with runnable experiments that map directly to industry benchmarks.
What You'll Learn
- The book's core formula and 10-chapter structure
- Key content and experiment design for each chapter
- How to run the experiments (uv / pip)
- How to choose a learning path based on your background
Prerequisites
- Basic Python
- General familiarity with LLMs and AI agents
- Chapter 7 (model post-training) requires GPU resources; other chapters do not
Project Background
Overview
This book organizes everything around a single core formula: Agent = LLM + Context + Tools. Each element matters: the LLM provides reasoning capability, context determines the capability ceiling, and tools connect to the external world. All 10 chapters drill into some dimension of this formula, building progressively from concepts to production-grade engineering.
"Open source" here is genuine: the full text is in Markdown and readable directly on GitHub; PDF/EPUB builds automatically from the main branch so you always get the latest version; the companion experiments are actually runnable code, not pseudocode examples.
Author
- Author: Li Bojie (@bojieli)
- Online reading: bojieli.github.io/ai-agent-book
- Primary language: Python (experiment code)
- License: Apache-2.0
Project Stats
- ⭐ GitHub Stars: 35,525+
- 🍴 Forks: 3,850+
- 📄 License: Apache-2.0
- 📅 Created: 2025-09-09
- 🌐 Translations: 13 languages (Chinese/English/Spanish/Indonesian/Arabic/Traditional Chinese (Taiwan)/Russian/Tamil/Vietnamese/Japanese/Turkish/Korean/Hungarian)
Downloads
Free PDF / EPUB (always pointing to the latest main branch build):
Online reading (multi-language switching, chapter folding, full-text search): bojieli.github.io/ai-agent-book
GitHub: book/chapter*.md contains the Chinese source text, readable directly in the browser.
10-Chapter Structure
All 10 chapters explore the core formula from different angles:
| Ch | Topic | Core Content | Experiments |
|---|---|---|---|
| 1 | Agent Fundamentals | Agent = LLM + Context + Tools; harness engineering | 4 |
| 2 | Context Engineering | KV Cache, prompt engineering, Agent Skills, context compaction | 9 |
| 3 | User Memory and Knowledge Bases | Cross-session memory, RAG, structured indexing, knowledge graphs | 13 |
| 4 | Tools | MCP protocol, perception/execution/collaboration tool types, async agents, proactive tool discovery | 7 |
| 5 | Coding Agent and Code Generation | Code as "the tool that creates new tools"; production-grade coding agent landscape | 13 |
| 6 | Agent Evaluation | Evaluation environments, metrics, statistical significance, evaluation-driven model selection | 13 |
| 7 | Model Post-Training | Pre-training / SFT / RL pipeline, tool-call internalization, sample efficiency | 16 |
| 8 | Agent Continuous Evolution | Learning from execution traces; updating knowledge, instructions, programs, parameters | 9 |
| 9 | Multimodal and Real-Time Interaction | Voice three-paradigm, Computer Use, robotics | 12 |
| 10 | Multi-Agent Collaboration | Collaboration frameworks, context sharing/isolation, emergent "agent society" | 8 |
Chapter Deep Dives
Chapter 2: Context Engineering
One of the most valuable chapters in the book, and the author's argument for where AI agent engineering competitive advantage really lives.
"Context determines the capability ceiling" is the chapter's core thesis: given the same LLM, vastly different capability emerges from different context quality. Topics:
- KV Cache mechanics: How to dramatically reduce latency and cost without modifying the model
- Prompt engineering: Not just "write better prompts" — systematic context construction methods
- Agent Skills: Structured capability declarations that let the LLM know what it "knows how to do"
- Context compaction: Information retention strategies for long sessions, preserving critical content while reducing token consumption
Chapter 3: User Memory and Knowledge Bases
Agents shouldn't start from scratch every time. This chapter breaks "memory" into engineerable components:
- User memory: Preserve user preferences, decision history, personalization across sessions
- RAG (Retrieval-Augmented Generation): Inject external knowledge bases into context dynamically, rather than baking into parameters
- Structured indexing: Beyond vector search — handling tables, code, numerical data
- Knowledge graphs: Representing and retrieving relational knowledge
Chapter 4: Tools
This chapter systematically maps the agent tool layer, with a focus on MCP (Model Context Protocol) principles and engineering practice. Tools are classified into three functional categories:
- Perception tools: Acquire external information (search, read, listen)
- Execution tools: Change external state (write files, call APIs, run code)
- Collaboration tools: Interact with other agents or humans
Also covers event-driven async agent design patterns and how agents can proactively discover available tools.
Chapter 5: Coding Agents and Code Generation
This chapter gives a precise framing: "Code is the tool that creates new tools." A coding agent's value isn't just writing code — it's dynamically extending its own capability boundary at runtime. Content covers:
- Complete architecture for a production-grade coding agent
- Code generation quality control: testing, validation, iteration
- Security boundaries for code execution sandboxes
- Common failure modes of coding agents
Chapter 6: Agent Evaluation
Evaluation is the hardest and most underestimated part of agent engineering. This chapter's experiments use industry-grade benchmarks directly:
| Benchmark | Type |
|---|---|
| SWE-bench | Code repair |
| OSWorld | GUI operation |
| android_world | Mobile operation |
| GAIA | General capability |
| tau2-bench | Customer service / workflows |
| terminal-bench | Terminal commands |
These aren't simplified in-house test sets — the experiments clone the original repositories and fix to specific commit SHAs, ensuring reproducibility against the same numbers published in papers.
Chapter 7: Model Post-Training
The chapter with the most experiments (16), covering the complete LLM training pipeline from scratch:
- Pre-training vs SFT vs RL: What each stage solves, decision framework
- Tool-call internalization: Training models to use tools better, not just prompting them to
- Sample efficiency: Maximizing learning from limited data
- When to choose SFT vs RL: Experiment-driven decision framework
Training frameworks used: verl (RL training), MiniMind (pre-training reproduction), AdaptThink, SandboxFusion (code execution sandbox) — all pinned to exact commit SHAs.
Chapter 9: Multimodal and Real-Time Interaction
Extending from text to voice, GUI, and the physical world:
- Voice three-paradigm: End-to-end voice, ASR+TTS cascade, streaming interaction
- Computer Use: Agents operating GUI interfaces; experiments use Anthropic claude-quickstarts and browser-use directly
- Robotics: XLeRobot, RoboCrew, lerobot-sim2real — from simulation to sim2real transfer
Chapter 10: Multi-Agent Collaboration
How group intelligence exceeds individual capability:
- Collaboration frameworks: task decomposition, role assignment, result aggregation
- Context sharing and isolation: What to share vs what must stay isolated
- Emergent "agent society": Stanford AI Town (generative_agents) experiment
- TalkAct (dual-agent architecture): Operating a computer while on a voice call
Running the Experiments
The project requires Python 3.10+. Using uv is recommended:
# Install uv
# https://docs.astral.sh/uv/getting-started/installation/
# Clone the repo
git clone https://github.com/bojieli/ai-agent-book.git
cd ai-agent-book
# Install dependencies for a chapter (chapter 2 as example)
uv sync --locked --extra ch2
# Run an experiment
uv run python chapter2/context/main.py
# Without uv
python -m pip install -e ".[ch2]"
python chapter2/context/main.pyAPI key configuration: Copy .env.example to .env and fill in at least one provider key:
cp .env.example .env
# Edit .env with your API keysSupported providers include: OpenAI, Anthropic, Google Gemini, DeepSeek, Kimi, Zhipu GLM, Qwen (via Siliconflow), and others. The book recommends having at least one key configured before running experiments that call models.
Learning Path Recommendations
Quick Overview (2–3 days)
Read Chapter 1 (fundamentals), then choose a chapter based on your focus:
- Primarily engineering practice → Chapters 2, 4, 5 (context engineering, tools, coding agent)
- Systematic evaluation → Chapter 6
- Training and optimization → Chapter 7
Complete Study (4–6 weeks)
Follow the order 1→2→3→4→5→6, running 1–2 experiments per chapter after reading. Chapter 7 (model post-training) requires GPU; it's optional. Chapters 9 and 10 depend on external repos — read the text first, then decide whether to run the experiments.
Reference as Needed
Search directly in the online version; each chapter is Markdown and readable directly on GitHub.
Resources
Official Links
- 🌟 GitHub: bojieli/ai-agent-book
- 🌐 Online reading: bojieli.github.io/ai-agent-book
- 📥 PDF (Chinese): AI-Agents-in-Depth-zh-CN.pdf
- 📥 PDF (English): AI-Agents-in-Depth-en.pdf
- 📖 Learning guide (Chinese): docs/zh-CN/LEARNING.md
Summary
AI Agents in Depth stands out for a few choices that aren't common in AI technical books:
Formula before structure: "Agent = LLM + Context + Tools" isn't just a marketing line — it's the organizing principle of the entire book. Every chapter answers the question: "For this element of the formula, how do you do the engineering well?" This structure keeps readers oriented throughout: they always know what they're studying and why.
Experiments mapped to industry benchmarks: The Chapter 6 experiments don't use the author's custom simplified test sets — they clone SWE-bench, OSWorld, GAIA, and other benchmarks widely used in both academia and industry, pinned to exact commit SHAs. The numbers you get are comparable to what's in papers.
Context engineering as its own chapter: This concept rarely gets dedicated treatment, but it genuinely is the most underestimated dimension of agent engineering. Given the same LLM, the difference in context construction approach often matters more than the difference in model choice.
Genuinely open source: Full Markdown source, automatic PDF/EPUB builds, all text, diagrams, and experiment code in the repository. Thirteen language translations from community contributors signal that the information density is high enough to be worth the translation effort.
If you're working on moving from "can call LLM APIs" to "can design and implement AI agent systems," this book provides a systematic path through that transition.
Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.
Visit my personal site for more insights and interesting products.