Understanding AI Agents: Design Principles and Engineering Practice
A comprehensive open-source book with 10 chapters and 95 hands-on experiments, based on 'Agent = LLM + Context + Tools' to take you from fundamentals to production.
Evidence shows this is a book repository with code examples and build scripts, no obvious malicious behavior. But as an Agent product, there is no documentation or implementation of least privilege, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, or source attribution. Hence all trust criteria score 0.
Self-consistency: Dependencies and chapter aggregates in pyproject.toml align with README and code comments, and build workflows are coordinated, score 2. Dependency availability: uv.lock and dependency resolution workflow are provided, but lockfile completeness not verified, score 2. Failure messages: Build scripts have error handling, but user-facing failure message documentation is lacking, score 1.
Audience and scenarios: README and chapter descriptions clarify target readers and scenarios, score 2. Capability boundaries: Chapter aggregates and optional dependencies define capability scope, score 2. Trigger precision: Build workflows have clear triggers, but Agent trigger mechanisms are unclear, score 1. Environment fit: Supports multiple platforms and Python versions, score 2.
Information architecture: Directory structure is clear, chapters and code organized well, score 2. Install notes: Detailed installation guide and dependency groups provided, score 2. Naming stability: Version numbers hardcoded in build scripts, but naming strategy not explicit, score 1. Examples and FAQ: Test scripts and examples exist, but FAQ missing, score 2. Known limitations: Dependency conflicts and platform restrictions commented in pyproject.toml, score 2. License: Apache-2.0 license file present, score 2. Versioning changelog: No CHANGELOG found, score 1. Maintenance responsibility: GitHub Actions and issue tracker present, but maintainers not explicit, score 1.
Output usability: Build artifacts (PDF/EPUB) and code examples are directly usable, score 2. Marginal value: As book companion code, provides practical runnable examples, score 2. Cost benefit: Dependency groups and optional installs reduce usage cost, score 2.
Claim traceability: README and code comments reference specific chapters and features, score 2. Cross-source corroboration: Build workflows and test scripts corroborate each other, but lack external verification, score 1. Fact-inference separation: Code comments distinguish facts and inferences, score 2.
- This repository is book companion code, not a full Agent product, so trust-related criteria cannot be assessed.
- Dependency security not verified; recommend checking uv.lock and dependency sources.
- No user confirmation or data flow transparency mechanisms provided; caution if used for actual Agent deployment.
What does this agent do, and when should you use it?
This is the official open-source repository for Bojie Li's book 'Understanding AI Agents: Design Principles and Engineering Practice'. It contains the full 10-chapter text, compiled PDF/EPUB, and 95 chapter-by-chapter code experiments. The book is built around the core formula 'Agent = LLM + Context + Tools', covering LLM basics, context engineering, user memory and knowledge bases (RAG), tools and MCP, Coding Agents, evaluation, model post-training (SFT/RL), continuous evolution, multimodal interaction, and multi-agent collaboration. The repository provides the original Chinese version plus 12 community-translated languages (English, Spanish, Indonesian, Arabic, etc.) and online reading with multilingual support. Experiments require Python 3.10+, and can be installed with uv or pip. Some experiments need API keys or local Ollama.
The repository enables book reading and experiment execution: users can read online or download PDF/EPUB; read Markdown chapters (e.g., book/chapter1.md); run 95 experiments, e.g., uv run python chapter1/context/main.py. Experiments cover context compression, KV cache, RAG, knowledge graphs, MCP tool invocation, Coding Agents (e.g., SWE-bench), evaluation benchmarks (e.g., GAIA), model post-training (MiniMind, verl), multimodal (browser automation, robotics), and multi-agent (TalkAct, Stanford AI Town). A one-click clone script fetches external repos (e.g., android_world, OSWorld) as dependencies. Install dependencies per chapter with uv sync --locked --extra ch1, and configure API keys in .env (e.g., Kimi, GLM, DeepSeek).
- Developers wanting a systematic deep dive into AI Agent theory and engineering can follow the 10 chapters and run experiments from basics to production.
- Engineers working on context engineering (KV cache, compression) can run 9 experiments from Chapter 2.
- Developers building RAG or knowledge graph applications can use Chapter 3 examples for user memory, structured indexing, and knowledge graphs.
- Engineers integrating MCP protocols or building tools can leverage Chapter 4's 7 experiments, including event-driven async agents.
- Researchers or engineers exploring Coding Agents can use Chapter 5's 13 experiments with SWE-bench to practice code generation.
- ML researchers interested in model post-training (SFT/RL) can run 16 experiments in Chapter 7 using frameworks like MiniMind, verl, and unsloth.
What are this agent's strengths and limitations?
- Comprehensive coverage from theory to practice with 10 chapters and 95 hands-on experiments, making it a one-stop resource for learning AI agents.
- Multilingual support: 13 languages including English, Spanish, etc., with online reading and community translations for global accessibility.
- Open source and free under Apache-2.0, with all book content, images, and code accessible for learning and contribution.
- Rich experiment variety spans RAG, MCP, coding agents, evaluation, post-training, multimodal, and multi-agent systems, ideal for applying concepts.
- Requires external API keys for many experiments, which may incur costs and depend on network access and provider availability.
- Complex setup: requires Python 3.10+, uv or pip, and per-chapter dependency management; additional system dependencies like CUDA or browsers may be needed.
- Many experiments rely on cloning external repositories (e.g., SWE-bench, GAIA) pinned to specific commits, adding setup steps and potential version conflicts.
- Community translations may lag behind the Chinese original, so content could be outdated or inconsistent across languages.
How do you install or deploy this agent?
Clone the repo: git clone https://github.com/bojieli/ai-agent-book.git. Install uv (official docs) or use pip. From the repo root, install per-chapter dependencies: uv sync --locked --extra ch1 (replace ch1 with chapter number) or python -m pip install -e ".[ch1]". System dependencies like browsers, CUDA, or FFmpeg may be required per experiment README.
How do you use this agent?
Read online at bojieli.github.io/ai-agent-book or download PDF/EPUB from Releases. To run experiments, set up .env (copy .env.example and add at least one provider key), then run from root, e.g., uv run python chapter1/context/main.py. For some experiments, clone external repositories using the appendix script.
FAQ
How much does it cost to run experiments?
Do I need a GPU?
all extra but excludes local training stacks; use special extras like vllm or unsloth for those.