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

Clone the bojieli/ai-agent-book repository, install dependencies from 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 file listing all necessary packages. Navigate to the specific chapter folder and install the dependencies before attempting to run any code.

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.

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 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:

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:

python demo.py

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

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:

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, three specialized agents orchestrate the workflow as implemented in 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) 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 file abstracts the two rendering backends, while 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

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 to experiment with tool-augmented perception agents.

Chapter 5 – Coding Agent (Small Model Rules)

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

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

python chapter9/browser-use/demo.py

Chapter 7 – Training Frameworks Each subfolder (e.g., chapter7/verl/) contains a README.md with specific 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 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 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.

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