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.
- Source repo
- bojieli/ai-agent-book
- Stars
- ★ 55k
- Last updated
- 19d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 41/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers wanting a systematic deep dive into AI Agent theory and engineering can follow the 10 chapters and run experiments from basics to production.
- Not a fit if
- Readers who only want the book text, not to run code
- Teams without GPUs that want to run Chapter 8 post-training
- Source review
- 41/100 · Major gaps 8 safety controls not found
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.
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.
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 does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Understanding AI Agents: Design Principles and Engineering Practice This agent | 41 · Major gaps | CLIFree + model costs | ★ 55k | 19d ago | Python | — |
| Haystack | 52 · Major gaps | Library / SDKFree + model costs | ★ 27k | today | Python | OpenAI API |
| Hello-Agents | 54 · Major gaps | Web appFree + model costs | ★ 84k | 5d ago | Python | OpenAI API |
| mu Coding Agent | 77 · Good | Desktop appFree + model costs | ★ 525 | 3d ago | TypeScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- 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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Always-fresh PDF and EPUB builds from the latest main branch, rebuilt automatically on every book-content change. Assets are overwritten in place, so these download URLs are stable. - 简体中文: [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) …View on GitHub ↗
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.