How to Install Dependencies for a Specific Chapter in AI Agents in Depth

Run uv sync --locked --extra chX from the repository root, replacing X with the chapter number, to install only the dependencies required for that specific chapter.

The bojieli/ai-agent-book repository structures its Python environment around modular extras defined in pyproject.toml, allowing you to install dependencies for a specific chapter without bloating your system with unused training frameworks. Each chapter maps to a named extra (e.g., ch1, ch2) that pins exact versions in the uv.lock file, ensuring reproducible experiments across macOS, Linux, and Windows.

Understanding the Chapter-Based Dependency System

The repository distributes a single core package named agentbook that contains shared utilities used across all experiments. Instead of installing everything upfront, the pyproject.toml file (lines 99‑118) declares optional dependency groups called extras, where ch1 through ch10 correspond to the ten chapters of the book.

When you request a specific extra, the installer resolves only the libraries referenced by that chapter. For example, the ch2 extra expands to ["agentbook[viz,docs,web,serve,providers,tokens,torch]"], which pulls in visualization tools (matplotlib, pandas), document parsers (pypdf, python-docx), web scraping utilities (aiohttp, beautifulsoup4, playwright), provider SDKs (openai, anthropic), and PyTorch for local inference.

Prerequisites and Environment Setup

Before installing chapter dependencies, clone the repository and ensure you have a compatible Python installer.

1. Clone the repository to obtain the source code and the uv.lock lockfile:

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

2. Install uv, the recommended package manager:

   # macOS/Linux
   
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows
   
   powershell -c "irm https://astral.sh/uv/install.ps1 | more"

   If you prefer not to use uv, ensure you have Python 3.10+ and pip available for the fallback method.

Installing Chapter Dependencies with uv (Recommended)

The uv tool reads the uv.lock file to reproduce the exact dependency tree tested by the authors. To install dependencies for a specific chapter, run the sync command with the --locked flag and specify the chapter extra.

Install Chapter 2 (Context Engineering) as an example:

uv sync --locked --extra ch2

This command performs three actions:

• Resolves dependencies from uv.lock rather than querying PyPI anew
• Creates an isolated virtual environment at .venv in the repository root
• Installs only the packages listed under the ch2 extra in pyproject.toml

Activate the environment before running experiments:

source .venv/bin/activate  # macOS/Linux

# or

.venv\Scripts\activate     # Windows

You can then execute the chapter’s entry point:

python chapter2/context/main.py

Installing Chapter Dependencies with pip (Fallback)

If you cannot use uv, install the same extras via editable pip install. This method resolves fresh versions from pyproject.toml instead of the locked file, which may result in slightly newer package versions.

python -m pip install -e ".[ch2]"

Replace ch2 with any chapter number (e.g., ch7 for evaluation, ch9 for continual evolution). Note that this approach bypasses the uv.lock guarantees, so version conflicts are possible.

Combining Multiple Extras for GPU and Training Stacks

Some chapters require heavy GPU-oriented frameworks that are excluded by default to keep the base environment lightweight. You can combine the chapter extra with training extras such as unsloth or vllm in a single command.

Install Chapter 7 with Unsloth fine-tuning support:

uv sync --locked --extra ch7 --extra unsloth

Install Chapter 2 with the vLLM inference server:

uv sync --locked --extra ch2 --extra vllm

The pyproject.toml file (lines 38‑45) defines a conflict matrix under [tool.uv] that prevents incompatible combinations from being installed simultaneously, protecting you from dependency resolution errors between unsloth and vllm.

Handling Per-Experiment requirements.txt Files

While chapter extras cover most dependencies, certain experiments ship with their own requirements.txt files when they need highly specific version pins or non-Python system dependencies (such as CUDA 12 or browser drivers).

For example, the Trajectory Verifier experiment in Chapter 9 requires isolated dependencies:

cd chapter9/trajectory-verifier
python -m pip install -r requirements.txt
python main.py

Only use these per-experiment files if you intend to run that specific script in isolation; otherwise, stick to the chapter extras to avoid redundant installations.

Summary

• The repository uses extras (ch1 through ch10) defined in pyproject.toml to group chapter-specific dependencies.
• uv is the recommended installer because it respects uv.lock for deterministic builds; use uv sync --locked --extra chX.
• pip works as a fallback with pip install -e ".[chX]", but resolves versions dynamically.
• Combine extras (e.g., --extra ch7 --extra unsloth) for GPU training stacks, respecting the conflict matrix at lines 38‑45 of pyproject.toml.
• Check for per-experiment requirements.txt files (such as in chapter9/trajectory-verifier/) only when running isolated scripts with unique system requirements.

Frequently Asked Questions

What is the difference between using uv and pip to install chapter dependencies?

uv installs exact versions recorded in uv.lock, ensuring bitwise reproducibility across machines, while pip re-resolves dependencies from pyproject.toml each time, which may install newer versions that introduce breaking changes. Both methods support the same [chX] extras syntax, but uv manages the virtual environment automatically.

Can I install dependencies for multiple chapters at once?

Yes. Pass multiple --extra flags to the sync command, such as uv sync --locked --extra ch2 --extra ch3, or list them in the pip command: pip install -e ".[ch2,ch3]". This merges the dependency sets for both chapters into a single environment.

Why does Chapter 9 have its own requirements.txt file?

The Trajectory Verifier experiment in chapter9/trajectory-verifier/requirements.txt requires specific versions of browser automation tools and CUDA libraries that conflict with the broader chapter extra. Use this file only when running that specific experiment in isolation; for other Chapter 9 scripts, rely on the ch9 extra.

Do I need to install CUDA or GPU drivers separately before running chapter installations?

The Python packages (such as torch or unsloth) pull in CUDA wheels automatically when you include GPU extras like unsloth or vllm. However, you must have a compatible NVIDIA driver installed on your host system. The chapter extras do not install system-level drivers, only Python bindings.

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