# How to Run the AI Agent Book Examples: Complete Setup Guide

> Easily run the AI agent book examples from bojieli/ai-agent-book. Follow this guide to clone the repo, install dependencies, set API keys, and run multi-agent experiments.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Clone the bojieli/ai-agent-book repository, install dependencies from [`requirements.txt`](https://github.com/bojieli/ai-agent-book/blob/main/requirements.txt), configure your API keys in a `.env` file, and execute `python demo.py` in any chapter folder to run multi-agent experiments ranging from video editing to browser automation.**

The bojieli/ai-agent-book repository ships with self-contained practice projects that demonstrate the fundamental formula of **Agent = LLM + Context + Tools**. Each experiment resides in its own chapter directory and follows a standardized three-step workflow: install dependencies, configure environment variables, and run the demo script. This guide walks you through running these AI agent book examples locally, with specific focus on the video editing pipeline in Chapter 5 as a reference implementation.

## Step 1: Install Python Dependencies

Every chapter experiment includes a [`requirements.txt`](https://github.com/bojieli/ai-agent-book/blob/main/requirements.txt) file listing all necessary packages. Navigate to the specific chapter folder and install the dependencies before attempting to run any code.

```bash
cd chapter5/video-edit
pip install -r requirements.txt

```

The video editing experiment requires `openai`, `ffmpeg-python`, and `pydantic` for vision processing, video manipulation, and API calls. Other chapters may include additional dependencies like `selenium` for browser automation or `pytest` for testing tool integrations.

## Step 2: Configure API Access

All experiments rely on LLM APIs for agent orchestration. Copy the provided template and insert your credentials.

```bash
cp env.example .env

```

Edit the `.env` file to include either `OPENAI_API_KEY` or `OPENROUTER_API_KEY`. You can also override the default models by setting `TEXT_MODEL` and `VISION_MODEL` environment variables. The [`agents.py`](https://github.com/bojieli/ai-agent-book/blob/main/agents.py) file reads these configurations lazily at runtime, allowing you to swap models without modifying code.

## Step 3: Run the Video Editing Example (Chapter 5)

The video editing experiment (`chapter5/video-edit/`) demonstrates a full "Natural Language request → Vision locate → Blender-API code generation → Review loop" pipeline. This serves as the canonical example for understanding how to run AI agent book experiments.

### Verify Installation with Smoke Test

Run the smoke test first to validate your local pipeline without consuming API credits:

```bash
python demo.py --smoke

```

This generates a synthetic four-scene video, extracts a single frame, and creates a Blender Python (`bpy`) script using only local processing. If this succeeds, your ffmpeg and Python environments are correctly configured.

### Execute the Full Pipeline

Run the complete agent workflow with the default natural language request:

```bash
python demo.py

```

The default query processes the phrase "把冲浪的部分剪出来" (cut out the surfing part). To process your own video with a custom request:

```bash
python demo.py -i my_video.mp4 -o edited.mp4 "把演讲开场剪出来"

```

### Backend and Performance Options

The experiment auto-detects Blender installation but supports explicit backend selection:

```bash
python demo.py --backend blender  # Requires Blender in $PATH

python demo.py --backend ffmpeg  # Uses ffmpeg for 2D cuts only

```

For faster, cheaper iteration during development, use the `--quick` flag to reduce the Vision Agent to a single round of frame analysis instead of the default two-step coarse-to-fine sampling.

## Understanding the Agent Architecture

When you run [`demo.py`](https://github.com/bojieli/ai-agent-book/blob/main/demo.py), three specialized agents orchestrate the workflow as implemented in [`chapter5/video-edit/agents.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/video-edit/agents.py):

**VideoAnalyzerAgent** performs a two-step Vision locate: coarse sampling every 10 seconds followed by fine sampling every 1 second to identify precise start/end timestamps for the requested scene.

**ProposerAgent** constructs a Blender Python API script ([`edit.py`](https://github.com/bojieli/ai-agent-book/blob/main/edit.py)) that imports the source video, applies trims, and adds subtitles or speed effects. The generated script undergoes lint checking via `py_compile` before execution.

**ReviewerAgent** samples three key frames (start, middle, end) from the edited clip and submits them to the vision model for verification. Negative feedback triggers a revision cycle with the ProposerAgent, repeating up to three rounds until the output passes validation.

The [`video_editor.py`](https://github.com/bojieli/ai-agent-book/blob/main/video_editor.py) file abstracts the two rendering backends, while [`blender_editor.py`](https://github.com/bojieli/ai-agent-book/blob/main/blender_editor.py) handles headless Blender execution via `blender --background --python edit.py`.

## Running Other Chapter Experiments

All practice projects follow the same **install → configure → execute** pattern. Reference these entry points for specific domains:

**Chapter 2 – System-Hint Agents**

```bash
pip install -r chapter2/system-hint/requirements.txt
cp chapter2/system-hint/env.example .env
python chapter2/system-hint/main.py

```

**Chapter 4 – Perception Tools**
Navigate to `chapter4/perception-tools/`, install requirements, then run individual test files or [`demo.py`](https://github.com/bojieli/ai-agent-book/blob/main/demo.py) to experiment with tool-augmented perception agents.

**Chapter 5 – Coding Agent (Small Model Rules)**

```bash
python chapter5/small-model-codified-rules/demo.py

```

**Chapter 9 – Browser-Use**
Install ChromeDriver, configure your `.env` in `chapter9/browser-use/`, then execute:

```bash
python chapter9/browser-use/demo.py

```

**Chapter 7 – Training Frameworks**
Each subfolder (e.g., `chapter7/verl/`) contains a [`README.md`](https://github.com/bojieli/ai-agent-book/blob/main/README.md) with specific [`run.sh`](https://github.com/bojieli/ai-agent-book/blob/main/run.sh) scripts wrapping distributed training commands.

## Summary

- **Install once per chapter**: Run `pip install -r requirements.txt` in the specific experiment directory to get all Python dependencies.
- **Configure credentials**: Copy `env.example` to `.env` and set `OPENAI_API_KEY` or `OPENROUTER_API_KEY` before running any agents.
- **Test locally first**: Use `python demo.py --smoke` to verify ffmpeg and script generation without API calls.
- **Customize execution**: Pass custom video paths with `-i` and `-o`, force backends with `--backend`, or reduce costs with `--quick`.
- **Understand the pattern**: Each demo follows the Agent formula where specialized sub-agents (Analyzer, Proposer, Reviewer) collaborate to transform natural language into executable code.

## Frequently Asked Questions

### Do I need Blender installed to run the video editing examples?

No. While `chapter5/video-edit/` auto-detects Blender for high-quality 3D rendering, the pipeline falls back to `ffmpeg` for standard 2D video cuts and subtitle overlay. You can force either backend using the `--backend ffmpeg` or `--backend blender` flags according to your requirements.

### Can I use OpenRouter instead of OpenAI for the API calls?

Yes. The `env.example` template supports both `OPENAI_API_KEY` and `OPENROUTER_API_KEY` variables. Set your preferred provider in the `.env` file, and the [`agents.py`](https://github.com/bojieli/ai-agent-book/blob/main/agents.py) initialization logic will route requests accordingly. You can also override model names using `TEXT_MODEL` and `VISION_MODEL` environment variables.

### What is the difference between `--smoke` and `--quick` modes?

The `--smoke` flag generates a synthetic test video and validates the local pipeline—including ffmpeg frame extraction and Blender script generation—without calling any LLM APIs, making it free to run. The `--quick` flag executes the full agent pipeline but reduces the **VideoAnalyzerAgent** to a single round of vision sampling instead of the default two-step coarse-to-fine analysis, reducing token costs while still processing your actual input video.

### How do I troubleshoot import errors when running chapter experiments?

Ensure you are running `pip install` from within the specific chapter subdirectory (e.g., `chapter5/video-edit/`), not the repository root. Each experiment maintains an isolated [`requirements.txt`](https://github.com/bojieli/ai-agent-book/blob/main/requirements.txt) tailored to its specific agent tools. If ffmpeg errors occur, verify that ffmpeg is installed system-wide and accessible in your `$PATH` before running [`demo.py`](https://github.com/bojieli/ai-agent-book/blob/main/demo.py).