How to Contribute to the AI Agent Book Project: 5 Ways to Get Involved

You can contribute to the AI Agent Book project by submitting pull requests for book content, companion code, SVG figures, or translations via the standard GitHub fork-and-clone workflow outlined in docs/en/README.md.

The AI Agent Book is an open-source, multilingual technical resource that teaches the core formula Agent = LLM + Context + Tools across 10 chapters and 93 companion experiments. Whether you want to fix typos in the Chinese source files located in book/, harden the standalone projects under chapter*/, or extend language support, this guide shows you exactly how to contribute to the AI agent book project with step-by-step instructions derived from the repository's source code.

5 Contribution Types Accepted by the Project

The "🤝 Contributing" section in docs/en/README.md defines five primary ways to participate. Each type maps to specific directories and requires slightly different validation steps.

1. Book Content Improvements

Edit the Markdown source files to fix typos, add clarifications, or expand sections. The canonical Chinese text lives in book/chapter*.md, while community translations reside in parallel folders like book-en/, book-zhtw/, and book-ja/.

2. Code Improvements

Harden the companion experiments by fixing bugs, adding tests, or improving error handling. Each chapter's standalone projects are stored in directories like chapter5/, chapter9/, etc., with individual README files (e.g., chapter5/README.en.md) documenting expected outputs.

3. New Practice Projects

Supply fresh experiments or alternative implementations that demonstrate concepts from the 10-chapter curriculum. Create a new subdirectory under the relevant chapter*/ folder and include a README.en.md following the existing pattern.

4. Figure Design

Improve the SVG diagrams stored in book/images/. These vector graphics illustrate agent architectures and workflows; edits require a vector editor or direct XML manipulation.

5. Translations

Extend the language set by creating new folders following the book-{locale}/ naming convention (e.g., book-ta/ for Tamil). Update the language selector in docs/en/README.md when adding support for a new locale.

Step-by-Step Contribution Workflow

Follow this exact sequence to ensure your pull request meets the repository's CI standards and maintainer expectations.

Fork and Clone the Repository

Start by creating your own fork, then clone it locally:

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

Install Optional Build Dependencies

If you plan to generate PDFs or EPUBs to verify formatting, install the toolchain referenced in the "🔧 Build the PDF yourself?" section of docs/en/README.md:

cd book && bash build_pdf.sh

This requires pandoc, xelatex, and the ElegantBook LaTeX class.

Validate Existing Experiments

Before modifying code, run a companion experiment to establish a baseline. For example, test the Chapter 5 coding-agent demo:

cd chapter5
bash run_demo.sh

Verify the output matches the specifications in chapter5/README.en.md.

Make Your Changes

• Documentation: Edit book/chapterX.md or its translation counterpart.
• Code: Modify files under chapterX/ or create new experiment directories.
• Figures: Edit SVGs in book/images/ using Inkscape or a text editor.

Run Local CI Checks (Optional)

The repository uses GitHub Actions for linting and star-history generation. You can invoke the star-history script locally to ensure your branch doesn't break the automation:

./scripts/gen_star_history.py

Commit and Push

Stage your changes with clear, descriptive messages:

git add .
git commit -m "Add XYZ to Chapter 3 and improve figure 3-2"
git push origin your-branch

Open a Pull Request

Navigate to your fork on GitHub and initiate a New pull request targeting the main branch of bojieli/ai-agent-book. The repository provides a PR template requiring you to describe the change, list affected files, and confirm you have run the relevant experiments.

Review and Iterate

Maintainers may request adjustments. Push additional commits to the same branch; the PR will update automatically.

Practical Contribution Examples

These concrete scenarios demonstrate the expected patterns for code, documentation, and asset contributions.

Adding a New Browser Automation Experiment (Chapter 9)

Create a minimal reproducible demo following the existing structure:

mkdir -p chapter9/browser-automation-new
cd chapter9/browser-automation-new

cat <<'EOF' > demo.py
import browser_use as bu

def main():
    browser = bu.Browser()
    browser.goto("https://example.com")
    print("Title:", browser.title)

if __name__ == "__main__":
    main()
EOF

cat <<'EOF' > README.en.md

# Browser Automation – New Demo

This experiment shows how to drive a Chromium browser using the `browser-use` library.

## Run

```bash
pip install browser-use
python demo.py

EOF

Optionally update the chapter index in [`chapter9/README.en.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter9/README.en.md) to link to your new experiment.

### Fixing a Typo in Chapter 2 (Chinese Source)

Edit the source file directly:

```bash
vim book/chapter2.md

# Locate and correct the error (e.g., "上下文" mistakenly written as "上文")

git commit -am "Fix typo in Chapter 2: 上下文 -> 上文"

Improving an SVG Figure

Modify vector assets using your preferred tool:

inkscape book/images/agent_architecture.svg

# Adjust arrow heads or color contrast, then save

# Verify rendering by opening the SVG in a browser

Key Files and Directory Structure

Understanding the repository layout helps you target the correct files for each contribution type:

• book/chapter*.md – Canonical Chinese text for each of the 10 chapters.
• book-en/, book-zhtw/, book-ja/ – Community translation folders.
• chapter*/ – Standalone companion code projects (93 experiments total).
• chapterX/README.en.md – Per-chapter indices listing experiments and usage instructions.
• book/images/*.svg – Source diagrams for the book figures.
• scripts/gen_star_history.py – CI script for generating repository analytics.
• .github/workflows/ – GitHub Actions pipelines for automated testing.
• LICENSE – Apache 2.0 open-source license.

Summary

• Five contribution types are accepted: book content, code improvements, new experiments, figure design, and translations.
• Source locations include book/ for text, chapter*/ for code, and book/images/ for SVG assets.
• Workflow follows standard GitHub practices: fork, clone, validate experiments, commit, and open a PR against main.
• Validation requires running companion experiments locally to ensure reproducibility before submitting.
• CI compliance can be tested locally using scripts/gen_star_history.py and the PDF build toolchain.

Frequently Asked Questions

Do I need to build the PDF to contribute code or translations?

No. PDF generation via book/build_pdf.sh is only necessary if you are modifying LaTeX templates or want to verify print formatting. Code experiments and Markdown edits do not require this step.

Can I add a completely new chapter instead of just experiments?

The core 10-chapter structure is currently fixed. However, you can propose new content by creating an issue first to discuss scope with maintainers, or contribute substantial new material as a "practice project" under an existing chapter directory.

What license covers my contributions?

All contributions are released under the Apache 2.0 license as specified in the repository's LICENSE file. By submitting a pull request, you agree to license your work under these terms.

How do I update the star-history chart in the README?

Run the Python script located at scripts/gen_star_history.py locally. This generates the star-history visualization displayed in the project README. The same script runs automatically via GitHub Actions in .github/workflows/star-history.yml.

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