ClassyGitshadowzzh

README.md

README.md

AI Agents in Depth: Design Principles and Engineering Practice

Stars License PDF Languages

中文 · 中文繁體 · English ← current · Tiếng Việt · தமிழ்

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 page:

Chinese text source is in book/; Traditional Chinese (Taiwan)/English/Tamil/Vietnamese versions are community contributions (may lag behind the Chinese original), located in book-zhtw/, book-en/, book-ta/, 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.

🔧 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

    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 4
2 🎯 Context Engineering Context caps Agent ability: KV Cache, prompt engineering, Agent Skills, context compression Read 9
3 📚 User Memory & Knowledge Bases Cross-session user memory + external knowledge: user memory, RAG, structured indexes, knowledge graphs Read 13
4 🛠️ Tools Tools are the Agent's hands: MCP protocol, perception/execution/collaboration tools, event-driven async Agents, proactive tool discovery Read 7
5 💻 Coding Agent & Code Generation Code is a "tool that creates new tools"; production-grade Coding Agent in full Read 12
6 🎯 Agent Evaluation Turn performance into comparable signals: environments, metrics, statistical significance, evaluation-driven selection Read 10
7 🧠 Model Post-Training Pre-training/SFT/RL three stages: when to choose SFT vs. RL, internalizing tool calls, sample efficiency Read 14
8 🔄 Agent Self-Evolution Growth without changing weights: learning from experience, from tool user to tool creator Read 6
9 🎙️ Multimodal & Real-Time Interaction Extending from text to voice, GUI, physical world: three voice paradigms, Computer Use, robotics Read 7
10 🤝 Multi-Agent Collaboration Collective intelligence > individual: collaboration frameworks, context sharing/isolation, emergent "Agent Society" Read 6

💡 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 (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 for model selection.

Platform Link Notes
Kimi (Moonshot) https://platform.moonshot.cn/ Kimi series, strong in long context and Agent capabilities
Zhipu GLM https://open.bigmodel.cn/ GLM-4.6 etc., strong Chinese ability, cost-effective
Siliconflow https://siliconflow.cn/ Various open-source models (DeepSeek, Qwen, etc.)
Volcano Engine https://www.volcengine.com/product/ark ByteDance Doubao (closed-source), low latency in China
OpenRouter https://openrouter.ai/ 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)
# 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; 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 · LLM Agent
9-10 🔧 Real hardware RGB zero-shot Sim2Real grasping — 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. See the LICENSE file for details. Some sub-projects may include their own license information; refer to the sub-project for specifics.

⭐ Star History

Star History Chart

Generated by scripts/gen_star_history.py, updated daily by GitHub Actions · Click image for live data