Can I Contribute to the AI Agent Book? A Complete Guide to Open Source Contributions

Yes, you can contribute to the AI Agent Book by submitting pull requests for content improvements, code experiments, translations, or build system enhancements to the bojieli/ai-agent-book repository.

The AI Agent Book is an open-source, community-driven guide that explains the design principles and engineering practices behind modern AI agents. Hosted in the public GitHub repository bojieli/ai-agent-book, the project welcomes contributions ranging from typo fixes to new research experiments. Whether you want to improve documentation, add runnable code samples, or translate chapters into new languages, the repository provides clear pathways for contributors to participate.

Types of Contributions You Can Make

The repository accepts five primary categories of contributions, each targeting specific directories within the codebase.

Book Content Improvements

Contribute to the core educational material by improving wording, adding missing explanations, or inserting the latest research findings. The markdown chapters live under the book/ directory (e.g., book/chapter1.md). When editing content, ensure your changes align with the existing style and run mkdocs serve to preview formatting before submission.

Code and Experiments

Fix bugs, make existing demos more robust, or add new practical projects. Each chapter ships with a set of runnable examples located in chapter*/ directories (for example, chapter5/coding-agent). Most experiment folders include a README.md with quick-run commands such as python chapter5/coding-agent/run.py to verify functionality.

Figures and Diagrams

Update or redesign visualizations generated by the book/gen_*_figs.py scripts. Output files should be placed in book/images/ and referenced correctly within the markdown source. Ensure generated figures maintain high resolution and consistent styling with existing diagrams.

Translations

Add or polish new language versions. The repository already hosts translations for English, Arabic, Traditional Chinese, Russian, Tamil, Vietnamese, Japanese, and others, each residing in book-<lang>/ directories (e.g., book-en/, book-ar/). When creating a new translation, mirror the structure of the main book/ directory and update the mkdocs.yml navigation to include the new language section.

Build System and CI

Improve the documentation infrastructure by modifying the MkDocs configuration (mkdocs.yml), enhancing CI workflows (.github/workflows/*), or optimizing the PDF/EPUB generation scripts (scripts/). The repository uses GitHub Actions to automatically lint Markdown, build distribution files, and run Python experiments on every pull request.

How to Contribute to the AI Agent Book

Follow this workflow to ensure your contributions meet the project standards and pass the automated CI pipeline.

Setting Up Your Development Environment

Start by forking the repository and cloning your local copy:

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

Install the development dependencies required to build the documentation:

pip install -r requirements-docs.txt

Launch the local documentation server to enable live preview of your changes. The site is built with MkDocs, and navigation is defined in mkdocs.yml:

mkdocs serve

Open http://127.0.0.1:8000 in your browser to view the site locally.

Making Your First Contribution

To add a new chapter to the book, create the markdown file and register it in the navigation configuration:

# Create a new markdown file

echo "# Chapter 11 – Future of AI Agents" > book/chapter11.md

# Register it in mkdocs.yml under the nav: section

# - Chapter 11: book/chapter11.md

When adding a new experiment, create the directory structure and implement your agent code:

mkdir -p chapter11/hello_world
cat > chapter11/hello_world/agent.py <<'PY'
from opencode import Agent

class HelloWorld(Agent):
    def act(self, input_text: str) -> str:
        return f"Hello, {input_text}!"
PY

Verify your experiment runs correctly:

python -c "from chapter11.hello_world.agent import HelloWorld; print(HelloWorld().act('Alice'))"

Submitting a Pull Request

After testing your changes locally, commit your work and push to your fork:

git add .
git commit -m "Add Chapter 11 outline"
git push origin main

Open a Pull Request through the GitHub web interface or using the GitHub CLI:

gh pr create --title "Add Chapter 11 outline" --body "Introduces future directions for AI agents."

Describe the purpose of your change, link any related issues, and ensure the CI pipeline passes. The repository runs automated tests defined in .github/workflows/build-latest.yml that lint Markdown, build PDF/EPUB outputs, and execute Python experiments.

Key Files and Directory Structure

Understanding the repository layout helps you locate the correct files for your contribution:

• README.md – Contains the contribution guidelines and high-level project overview.
• mkdocs.yml – Controls site navigation, theme configuration, and plugins.
• book/ – Markdown source of the main textbook (chapters 1-10).
• chapter*/ – Individual experiment folders accompanying each chapter (e.g., chapter5/coding-agent).
• scripts/ – Helper scripts for building PDFs, generating figures (book/gen_*_figs.py), and creating OG cards.
• .github/workflows/ – GitHub Actions definitions that run linting, tests, and documentation builds on every PR.
• LICENSE – Apache 2.0 license governing reuse and contribution.

Summary

• Yes, you can contribute to the AI Agent Book through multiple pathways including content editing, code experiments, translations, and infrastructure improvements.
• Content lives in book/, experiments in chapter*/, and translations in book-<lang>/ directories.
• Local development requires Python dependencies from requirements-docs.txt and uses mkdocs serve for preview.
• All changes must pass CI checks defined in .github/workflows/ before merging.
• Contributions are licensed under Apache 2.0, ensuring open access to the community.

Frequently Asked Questions

Do I need to be an AI expert to contribute to the AI Agent Book?

No, the project welcomes contributors at all levels. You can fix typos, improve explanations, or add beginner-friendly examples without deep AI expertise. Technical contributions involving agent implementations should follow the existing patterns in chapter*/ directories and include working code demonstrations.

How do I test my changes before submitting a pull request?

Run mkdocs serve to preview documentation changes locally at http://127.0.0.1:8000. For code contributions, execute the experiment's README.md instructions or run the specific Python files directly (e.g., python chapter5/coding-agent/run.py). The CI pipeline will automatically run additional linting and integration tests when you open a PR.

Can I contribute translations for languages not yet supported?

Yes, the repository actively seeks translations. Create a new directory following the book-<lang>/ naming convention (for example, book-de/ for German), mirror the structure of the main book/ directory, and update mkdocs.yml to include the new language in the navigation. Ensure translations maintain technical accuracy while adapting explanations for cultural context.

What happens after I submit a pull request?

The maintainers will review your submission against the automated CI checks defined in .github/workflows/build-latest.yml, which validate Markdown formatting, build PDF/EPUB outputs, and execute Python experiments. If checks pass, maintainers provide feedback or merge the contribution. Well-documented PRs with clear descriptions and linked issues receive faster review.

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