How to Set Up the AI Agent Book Project Locally: Complete Installation Guide

To set up the AI agent book project locally, clone the repository from bojieli/ai-agent-book, install global dependencies including Python 3.10+, pandoc, and xelatex, navigate to your target chapter, install chapter-specific Python packages via requirements.txt, configure required API keys, and execute the experiment script.

The AI Agent Book is a modular open-source repository that combines a Markdown-based textbook with over 90 runnable experiments. Each chapter maintains independent dependencies and documentation, allowing you to run individual experiments or the entire project locally. This guide covers the complete workflow to set up the AI agent book project locally based on the actual source structure and build scripts.

Clone the Repository

Begin by obtaining the source code and all documentation from the main branch:

git clone https://github.com/bojieli/ai-agent-book.git
cd ai-agent-book

The top-level README.md serves as the primary entry point, providing download links for pre-built PDFs and an overview of the repository structure. The source files for the book itself reside in the book/ directory, while individual experiments are organized under chapter*/ subdirectories.

Install Global Development Dependencies

While chapter-specific Python packages are isolated, the build pipeline requires several system-level tools for PDF generation and document processing. Install the following dependencies if you intend to build the book locally or run experiments that require document conversion:

Tool	Purpose	Installation Command
Python 3.10+	Core runtime for all experiments	sudo apt install python3 python3-pip
pandoc	Markdown-to-PDF conversion engine	sudo apt install pandoc
xelatex (TeX Live)	LaTeX engine with CJK font support	sudo apt install texlive-xetex
ElegantBook	LaTeX class required by build_pdf.sh	tlmgr install elegantbook
librsvg2-bin	SVG-to-PDF rasterization	sudo apt install librsvg2-bin
CJK Fonts	Songti SC, Heiti SC, Arial Unicode MS	Install via OS package manager

These global dependencies are optional if you only plan to run Python experiments without generating the PDF. However, the book/build_pdf.sh script will fail without the complete LaTeX toolchain.

Configure and Run a Chapter Experiment

Each chapter follows a consistent quick-start pattern documented in its respective README.md. The standard workflow involves entering the chapter directory, installing Python dependencies, configuring environment variables, and executing the entry point script.

The universal pattern across all chapters is:

1. Navigate to the specific chapter or experiment subdirectory
2. Install dependencies: pip install -r requirements.txt
3. Export required API keys (e.g., MOONSHOT_API_KEY, OPENROUTER_API_KEY)
4. Run the experiment: python main.py or bash run.sh

Example: Running the Learning-From-Experience Experiment

The chapter1/learning-from-experience directory contains a complete reinforcement learning experiment that demonstrates the setup process:

# Navigate to the experiment directory

cd chapter1/learning-from-experience

# Install chapter-specific Python dependencies

pip install -r requirements.txt

# Configure the Moonshot/Kimi API key for LLM integration

export MOONSHOT_API_KEY="your-api-key-here"

# Launch the experiment

python main.py

According to chapter1/learning-from-experience/README.md, this experiment implements a learning-from-experience loop and requires the Moonshot API for the LLM branch. Alternative API providers are documented in the chapter's quick-start section (快速开始).

You can apply this same pattern to other chapters, such as chapter2/local_llm_serving/ or chapter4/agent-with-event-trigger/, each containing their own requirements.txt and setup instructions.

Build the Full PDF Documentation (Optional)

To generate an offline copy of the textbook, use the provided build script in the book/ directory:

cd book
bash build_pdf.sh

The build_pdf.sh script performs several operations:

• Validates the presence of all chapter Markdown files (introduction.md, chapter1.md, etc.)
• Invokes pandoc with Lua filters (crossref.lua, experiment_box.lua) for cross-references and experiment callouts
• Compiles using the ElegantBook LaTeX class
• Outputs 深入理解-AI-Agent-李博杰-v1.3.pdf

This process requires the complete LaTeX dependency stack outlined in the previous section. The script will exit with errors if elegantbook.cls is missing or if CJK fonts are not properly configured.

Managing External Dependencies

Some experiments rely on external frameworks and benchmarks not included in the main repository. The top-level README.md contains a "一键克隆脚本" (one-click clone script) section listing required external repositories.

For example, to set up the GAIA benchmark environment for Chapter 6:

git clone https://github.com/google-research/android_world.git chapter6/android_world

Consult the collapsible "🔧 想自行编译 PDF？" section in README.md for the complete list of external dependencies and clone commands.

Troubleshooting Common Setup Issues

Symptom	Root Cause	Solution
ImportError: No module named...	Missing chapter dependency	Re-run pip install -r requirements.txt in the chapter directory
pandoc errors about missing LaTeX class	ElegantBook not installed	Run tlmgr install elegantbook or place elegantbook.cls in your TEXMF tree
API key errors during LLM experiments	Environment variable not exported	Export MOONSHOT_API_KEY or OPENROUTER_API_KEY as specified in the chapter README
Docker experiments fail on macOS	glibc version incompatibility	Use the provided Dockerfile or run the experiment on a Linux VM per chapter instructions

Summary

• Clone the repository from https://github.com/bojieli/ai-agent-book.git to obtain all source files and experiments.
• Install global dependencies (Python 3.10+, pandoc, xelatex, ElegantBook) only if building the PDF locally.
• Navigate to individual chapter directories and run pip install -r requirements.txt to install isolated Python environments.
• Export required API keys (such as MOONSHOT_API_KEY) before running LLM-dependent experiments.
• Execute experiments using python main.py or provided shell scripts like run.sh.
• Build the complete textbook offline using cd book && bash build_pdf.sh when LaTeX dependencies are available.

Frequently Asked Questions

Do I need to install LaTeX dependencies to run the Python experiments?

No. The global dependencies including pandoc, xelatex, and ElegantBook are only required for building the PDF documentation via book/build_pdf.sh. You can run individual chapter experiments by installing only the Python packages listed in each chapter's requirements.txt file.

How do I obtain the required API keys for LLM experiments?

Many experiments in chapter1/ and subsequent chapters require a MOONSHOT_API_KEY for the Moonshot/Kimi API or an OPENROUTER_API_KEY for OpenRouter access. These keys must be exported as environment variables before running scripts. Check the specific chapter's README.md (particularly the "快速开始" section) for alternative API providers and configuration instructions.

Can I run the experiments on Windows or macOS?

The Python experiments generally run on any platform supporting Python 3.10+. However, Docker-based experiments may fail on macOS due to glibc version incompatibilities, requiring a Linux VM. The PDF build pipeline is tested primarily on Linux environments with texlive-xetex and specific CJK fonts, though Windows Subsystem for Linux (WSL) may work with proper font configuration.

Where can I find the setup instructions for a specific chapter?

Each chapter contains a dedicated README.md file (e.g., chapter1/learning-from-experience/README.md, chapter2/local_llm_serving/README.md) with a quick-start section detailing exact commands, required API keys, and expected outputs. These files provide the authoritative setup instructions for their respective experiments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}