How to Set Up a Local AI Agent Development Environment: The Complete Guide

Install Python 3.10 via Conda, configure API keys in .env files, clone the bojieli/ai-agent-book repository, and run chapter-specific quickstart.py scripts to explore self-contained AI agent experiments without heavy external dependencies.

The bojieli/ai-agent-book repository provides a modular "book + code" framework for experimenting with AI agent capabilities. Each chapter demonstrates concrete implementations of the core agent architecture—LLM + Context + Tools—through runnable experiments covering tool use, memory management, and multimodal interaction. This guide walks you through creating a reproducible local development environment using the exact dependency versions and configuration patterns defined in the source code.

Prerequisites and Core Architecture

Every experiment in the repository follows the abstract formula defined in the top-level README.md:

Agent = LLM + Context + Tools

• LLM: Any large language model accessible via API (OpenAI, Claude, Kimi, etc.) referenced at README.md lines 10-12.
• Context: Prompt engineering, KV-cache handling, and RAG modules detailed in Chapter 2 ("上下文工程") at book/chapter2.md lines 52-56.
• Tools: Perception and execution utilities invoked via the MCP protocol, linked in the tool table at README.md lines 57-58.

You need Python 3.10, Conda (recommended), and Git to proceed.

Step 1: Clone the Repository and Create the Python Environment

Start by cloning the repository and creating an isolated Conda environment following the specifications in chapter7/retool/README.md:

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

conda create -n ai-agent python=3.10 -y
conda activate ai-agent

Install the core documentation dependencies from requirements-docs.txt, which contains pinned MkDocs packages used for the online site (lines 9-11):

pip install -r requirements-docs.txt

Note: Each chapter contains its own requirements.txt for experiment-specific packages (e.g., chapter5/coding-agent/requirements.txt). Install these when you first run a specific chapter.

Step 2: Configure API Keys in Environment Files

Most experiments require external LLM API access. The repository provides env.example templates in each chapter directory. Copy and customize these:

cp chapter5/coding-agent/env.example .env

# Edit .env to add your keys:

# OPENAI_API_KEY=sk-...

# CLAUDE_API_KEY=...

The top-level README.md (lines 69-80) lists recommended providers for obtaining API keys. For offline-only demos like chapter9/streaming-speech, you may use the env.example template without valid keys to run local inference.

Step 3: Clone External Benchmark Repositories

Certain chapters depend on external benchmark suites and simulation environments. The README contains a "一键克隆脚本" (one-click clone script) referencing 19 external projects (lines 92-106). Execute these commands once after the initial clone:

git clone https://github.com/google-research/android_world.git chapter6/android_world
git clone https://huggingface.co/datasets/gaia-benchmark/GAIA chapter6/GAIA

# Continue with remaining repositories listed in the README

These clones populate chapter6/ and other directories with evaluation frameworks required for full experiments.

Step 4: Run Local Agent Experiments

Every chapter ships with a quickstart.py or --quick CLI flag that runs minimal examples using local data samples, skipping heavy API calls where possible.

Quick-Start Commands by Chapter

Chapter	Directory	Command	Feature
Web Search	chapter1/web-search	python quickstart.py	LLM-driven search
System Hints	chapter2/system-hint	python quickstart.py	Prompt-based instructions
Active Tool Selection	chapter4/active-tool-selection	python quickstart.py	Tool discovery
Coding Agent	chapter5/coding-agent	python quickstart.py	Offline coding demo
MiniMind Pre-training	chapter7/minimind	bash run_pretrain.sh --pretrain_max_steps 20	Tiny training run
Streaming Speech	chapter9/streaming-speech	python demo.py --quick	Real-time audio

For example, to test the Coding Agent without consuming API credits:

cd chapter5/coding-agent
python quickstart.py

To run a full LLM-enabled demonstration in quick mode:

python demo.py --quick

Locate specific quick-start instructions in each chapter's README by searching for "快速开始" (quick start) sections, referenced in README.md lines 179-180.

Step 5: Build the Documentation Site (Optional)

To regenerate the MkDocs site locally for offline reference:

mkdocs serve

The build script at scripts/build_site.sh mirrors the CI workflow used in GitHub Actions, ensuring consistency between your local build and the deployed site.

Summary

• Architecture: The repository implements Agent = LLM + Context + Tools across modular chapters.
• Environment: Use Conda with Python 3.10; install core deps via requirements-docs.txt and chapter-specific deps via individual requirements.txt files.
• Configuration: Copy env.example templates to .env and populate with API keys from providers listed in README.md.
• Dependencies: Run the clone commands from the README (lines 92-106) to fetch 19 external benchmark repositories.
• Validation: Execute quickstart.py or demo.py --quick in any chapter directory to verify your setup with minimal resource usage.

Frequently Asked Questions

Do I need API keys to run the experiments locally?

No. While full functionality requires LLM API keys (OpenAI, Claude, etc.) configured in .env files, many chapters provide quickstart.py scripts that run offline using local data samples. For example, chapter5/coding-agent/quickstart.py operates without network calls, and chapter9/streaming-speech/demo.py --quick runs in offline mode.

Which Python version and environment manager should I use?

The repository specifically recommends Python 3.10 and Conda as documented in chapter7/retool/README.md. While virtualenv works, Conda ensures compatibility with binary dependencies required by certain benchmarks like Android World in Chapter 6.

How do I add new external tools or benchmarks to my local environment?

Follow the pattern in the top-level README.md lines 92-106: clone external repositories into the appropriate chapter subdirectory (e.g., chapter6/android_world). Ensure you activate the chapter-specific Conda environment and install its requirements.txt before running integration tests.

What is the difference between quickstart.py and demo.py?

quickstart.py provides minimal, API-free demonstrations using cached data, ideal for testing your environment setup. demo.py (often with a --quick flag) executes the full agent pipeline including LLM calls but with reduced parameters for faster validation.

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