# AI Agents in Depth: Design Principles and Engineering Practice
[](https://github.com/bojieli/ai-agent-book) [](../../LICENSE) [](#-e-book) [](#-e-book)
**[中文](../../README.md) · [中文繁體](../zh-TW/README.md) · English ← current · [Tiếng Việt](../vi/README.md) · [தமிழ்](../ta/README.md)**
**Agent = LLM + Context + Tools** — This book builds on this core formula across 10 chapters, taking AI Agents from principles to engineering practice. The full text, illustrations, and **88 accompanying experiments** are all open source. You are welcome to run the experiments yourself.
| 📚 **10 chapters** of text, from basics to production | 📂 **88** companion projects (70+ standalone) | 🌐 **5 languages**: CN / zh-TW / EN / TA / VI |
| :---: | :---: | :---: |
## 📖 E-Book
> 📥 **Download** (full text, free and open source). These links always point to the latest build of the `main` branch; fixed editions are on the [Releases](https://github.com/bojieli/ai-agent-book/releases) page:
> - **Chinese (original)**: [PDF](https://github.com/bojieli/ai-agent-book/releases/download/latest/AI-Agents-in-Depth-zh-CN.pdf) · [EPUB](https://github.com/bojieli/ai-agent-book/releases/download/latest/AI-Agents-in-Depth-zh-CN.epub)
> - **Traditional Chinese (Taiwan)** (community translation, by [@tigercosmos](https://github.com/tigercosmos)): [PDF](https://github.com/bojieli/ai-agent-book/releases/download/latest/AI-Agents-in-Depth-zh-TW.pdf) · [EPUB](https://github.com/bojieli/ai-agent-book/releases/download/latest/AI-Agents-in-Depth-zh-TW.epub)
> - **English** (community translation, by [@nsdevaraj](https://github.com/nsdevaraj)): [PDF](https://github.com/bojieli/ai-agent-book/releases/download/latest/AI-Agents-in-Depth-en.pdf) · [EPUB](https://github.com/bojieli/ai-agent-book/releases/download/latest/AI-Agents-in-Depth-en.epub)
> - **Tamil** (community translation, by [@nsdevaraj](https://github.com/nsdevaraj)): [PDF](https://github.com/bojieli/ai-agent-book/releases/download/latest/AI-Agents-in-Depth-ta.pdf) · [EPUB](https://github.com/bojieli/ai-agent-book/releases/download/latest/AI-Agents-in-Depth-ta.epub)
> - **Vietnamese** (community translation, by [@toanalien](https://github.com/toanalien)): [PDF](https://github.com/bojieli/ai-agent-book/releases/download/latest/AI-Agents-in-Depth-vi.pdf) · [EPUB](https://github.com/bojieli/ai-agent-book/releases/download/latest/AI-Agents-in-Depth-vi.epub)
Chinese text source is in [`book/`](../../book/); Traditional Chinese (Taiwan)/English/Tamil/Vietnamese versions are community contributions (may lag behind the Chinese original), located in [`book-zhtw/`](../../book-zhtw/), [`book-en/`](../../book-en/), [`book-ta/`](../../book-ta/), [`book-vi/`](../../book-vi/) respectively.
The shared builder produces EPUB 3 editions for Simplified Chinese, Traditional Chinese (Taiwan), English, Tamil, and Vietnamese. See the [EPUB build instructions](../../EPUB.md).
🔧 Build the PDF yourself? (requires pandoc / xelatex / ElegantBook)
- **Text source**: `book/introduction.md` (intro), `book/chapter1.md` ~ `book/chapter10.md` (Chapters 1–10), `book/afterword.md` (afterword)
- **Build**: Install pandoc, xelatex, ElegantBook document class and required fonts, then run
```bash
cd book && bash build_pdf.sh
```
Figures are generated by `book/gen_*_figs.py` and stored in `book/images/`; see `book/preamble.tex` and `book/*.lua` for typography details.
## 📑 Content Overview (Chapters 1–10)
The book revolves around the core formula **Agent = LLM + Context + Tools**, with ten chapters building progressively:
| Ch | Topic | One-line Summary | Text | Code |
| :--: | --- | --- | :--: | :--: |
| 1 | 🚀 **Agent Fundamentals** | "Model as Agent" paradigm + **Agent = LLM + Context + Tools**; Harness engineering is the real competitive edge | [Read](../../book-en/chapter1.md) | [4](../../chapter1/README.en.md) |
| 2 | 🎯 **Context Engineering** | Context caps Agent ability: KV Cache, prompt engineering, Agent Skills, context compression | [Read](../../book-en/chapter2.md) | [9](../../chapter2/README.en.md) |
| 3 | 📚 **User Memory & Knowledge Bases** | Cross-session user memory + external knowledge: user memory, RAG, structured indexes, knowledge graphs | [Read](../../book-en/chapter3.md) | [13](../../chapter3/README.en.md) |
| 4 | 🛠️ **Tools** | Tools are the Agent's hands: MCP protocol, perception/execution/collaboration tools, event-driven async Agents, proactive tool discovery | [Read](../../book-en/chapter4.md) | [7](../../chapter4/README.en.md) |
| 5 | 💻 **Coding Agent & Code Generation** | Code is a "tool that creates new tools"; production-grade Coding Agent in full | [Read](../../book-en/chapter5.md) | [12](../../chapter5/README.en.md) |
| 6 | 🎯 **Agent Evaluation** | Turn performance into comparable signals: environments, metrics, statistical significance, evaluation-driven selection | [Read](../../book-en/chapter6.md) | [10](../../chapter6/README.en.md) |
| 7 | 🧠 **Model Post-Training** | Pre-training/SFT/RL three stages: when to choose SFT vs. RL, internalizing tool calls, sample efficiency | [Read](../../book-en/chapter7.md) | [14](../../chapter7/README.en.md) |
| 8 | 🔄 **Agent Self-Evolution** | Growth without changing weights: learning from experience, from tool user to tool creator | [Read](../../book-en/chapter8.md) | [6](../../chapter8/README.en.md) |
| 9 | 🎙️ **Multimodal & Real-Time Interaction** | Extending from text to voice, GUI, physical world: three voice paradigms, Computer Use, robotics | [Read](../../book-en/chapter9.md) | [7](../../chapter9/README.en.md) |
| 10 | 🤝 **Multi-Agent Collaboration** | Collective intelligence > individual: collaboration frameworks, context sharing/isolation, emergent "Agent Society" | [Read](../../book-en/chapter10.md) | [6](../../chapter10/README.en.md) |
> 💡 **Read** = read the chapter text on GitHub (markdown); **N** = number of companion projects, click for code. Project types (✅ Standalone / 📖 Reproduction / 🚧 Design) are explained in each chapter's README.
>
> 📚 How to read this book efficiently? See **[Learning Suggestions](LEARNING.md)** (core ideas, learning path, difficulty levels, practice tips).
## 🔑 API Keys
It is recommended to apply for API keys from several platforms for convenient learning. See [this guide](https://01.me/2025/07/llm-api-setup/) for model selection.
| Platform | Link | Notes |
| --- | --- | --- |
| **Kimi** (Moonshot) | | Kimi series, strong in long context and Agent capabilities |
| **Zhipu GLM** | | GLM-4.6 etc., strong Chinese ability, cost-effective |
| **Siliconflow** | | Various open-source models (DeepSeek, Qwen, etc.) |
| **Volcano Engine** | | ByteDance Doubao (closed-source), low latency in China |
| **OpenRouter** | | One-stop access to Gemini / Claude / GPT-5 etc. (official APIs need overseas IP/payment; OpenAI also requires overseas ID verification) |
## 📦 Appendix · Obtaining External Repositories
The 20 external repos for benchmarks, training frameworks, and robot platforms in Chapters 6, 7, 9, 10 are **not bundled** (due to size and licensing) and must be cloned into the corresponding directories.
### One-shot Clone Script
🔧 Expand clone commands (20 external repos)
```bash
# Chapter 6 · Evaluation Benchmarks
git clone https://github.com/google-research/android_world.git chapter6/android_world
git clone https://huggingface.co/datasets/gaia-benchmark/GAIA chapter6/GAIA
git clone https://github.com/xlang-ai/OSWorld.git chapter6/OSWorld
git clone https://github.com/SWE-bench/SWE-bench.git chapter6/SWE-bench
git clone https://github.com/sierra-research/tau2-bench.git chapter6/tau2-bench
git clone https://github.com/laude-institute/terminal-bench.git chapter6/terminal-bench
# Chapter 7 · Training Frameworks (bojieli/* are book-adapted forks)
git clone https://github.com/bojieli/minimind.git chapter7/MiniMind-pretrain/minimind # Exp 7-3 train LLM from scratch
git clone https://github.com/bojieli/minimind-v.git chapter7/MiniMind-pretrain/minimind-v # Exp 7-4 train VLM from scratch (projection layer)
git clone https://github.com/bojieli/AdaptThink.git chapter7/AdaptThink-original
git clone https://github.com/bojieli/AWorld.git chapter7/AWorld
git clone https://github.com/bojieli/SFTvsRL.git chapter7/SFTvsRL
git clone https://github.com/bojieli/verl.git chapter7/verl
git clone https://github.com/thinking-machines-lab/tinker-cookbook.git chapter7/tinker-cookbook
git clone https://github.com/bojieli/lighteval.git chapter7/Intuitor/lighteval
git clone https://github.com/19PINE-AI/rlvp.git chapter7/RLVP/rlvp # Exp 7-14 RLVP paper code
git clone https://github.com/PRIME-RL/SimpleVLA-RL.git chapter7/SimpleVLA-RL/SimpleVLA-RL # Exp 7-13 vision-language-action RL
# Chapter 9 · Browser Automation & Claude Examples
git clone https://github.com/browser-use/browser-use.git chapter9/browser-use
git clone https://github.com/anthropics/claude-quickstarts.git chapter9/claude-quickstarts
# Chapter 10 · Dual-Agent Architecture (now independent TalkAct project) + Stanford AI Town
git clone https://github.com/19PINE-AI/TalkAct.git chapter10/use-computer-while-calling
git clone https://github.com/joonspk-research/generative_agents.git chapter10/generative_agents # Exp 10-7 Stanford AI Town
```
> If a project README specifies a particular commit, `git checkout` to that version for reproducibility. Chapter 10's `use-computer-while-calling` has evolved into the independently maintained [19PINE-AI/TalkAct](https://github.com/19PINE-AI/TalkAct); this repo only keeps a pointer doc.
### Other Reproduction Paths
The experiments below have no dedicated clone command but specific reproduction methods:
| Experiment | Type | Notes |
| --- | :--: | --- |
| 6-2 / 6-3 / 6-4 / 6-9 | 📝 Reader exercise | Human benchmark, memory eval, JSON Cards vs RAG, memory selection — adapt Chapter 3's `user-memory` / `user-memory-evaluation` / `contextual-retrieval` |
| 5-12 | 📝 Reader exercise | Agent that creates Agents — bootstrap from `chapter5/coding-agent` |
| 7-8 | 📝 Reader exercise | Prompt distillation — see `chapter8/prompt-distillation` (cross-chapter reuse) |
| 7-9 | 📝 Reader exercise | CoT distillation `[Extension]` — design and acceptance criteria in book, no dedicated code |
| 6-11 | 🤖 Simulation eval | OpenVLA + RoboTwin2 — see `chapter7/SimpleVLA-RL` README for VLA training/env deps |
| 9-8 / 9-9 | 🔧 Real hardware | XLeRobot teleoperation and LLM Agent control — requires SO-100 arm, [Teleop](https://xlerobot.readthedocs.io/en/latest/software/getting_started/XLeRobot_teleop.html) · [LLM Agent](https://xlerobot.readthedocs.io/en/latest/software/getting_started/LLM_agent.html) |
| 9-10 | 🔧 Real hardware | RGB zero-shot Sim2Real grasping — [`StoneT2000/lerobot-sim2real`](https://github.com/StoneT2000/lerobot-sim2real) (simulation runs on pure GPU; deployment needs SO-100) |
## 🤝 Contributing
The book and accompanying code are fully open source. Pull Requests are very welcome:
| Type | Notes |
| --- | --- |
| 📝 **Book content** | Errata, additions, clearer wording, or new developments (text in `book/chapter*.md`) |
| 🐛 **Code improvements & bug fixes** | Make companion projects more robust, usable, and production-ready |
| 🧪 **New practice projects** | Add/replace better implementations for experiments, or contribute new examples |
| 🎨 **Figure design** | Make `book/images/` charts clearer and more polished (generated by `book/gen_*_figs.py`) |
| 🌐 **New translations** | Translations into more languages are welcome; see Traditional Chinese/Taiwan (`book-zhtw/`), English (`book-en/`), Tamil (`book-ta/`), Vietnamese (`book-vi/`) for reference |
Before submitting, please run the relevant experiments to confirm reproducibility; feel free to open an issue to discuss ideas first.
## 📄 License
This project is licensed under [Apache License 2.0](../../LICENSE). See the [`LICENSE`](../../LICENSE) file for details. Some sub-projects may include their own license information; refer to the sub-project for specifics.
## ⭐ Star History
Generated by [`scripts/gen_star_history.py`](../../scripts/gen_star_history.py), updated daily by [GitHub Actions](../../.github/workflows/star-history.yml) · Click image for live data
