How to Update Dependencies in the AI Agent Book Project: A Chapter-Based Guide

To update dependencies in the bojieli/ai-agent-book repository, navigate to the target chapter's directory, run pip list --outdated to identify upgradable packages, install updates with pip install -U <package>, and regenerate the lock file using pip freeze > requirements.txt to preserve the chapter's reproducible environment.

Updating dependencies in the AI Agent Book project requires a chapter-specific workflow because the repository isolates each experiment's Python environment. Unlike monolithic projects with a single root-level manifest, the bojieli/ai-agent-book organizes code into independent chapters—such as chapter5/coding-agent and chapter8/trajectory-verifier—each maintaining its own requirements.txt file. This guide explains how to safely update dependencies within this modular architecture.

Understanding the Chapter-Based Architecture

The repository structures each AI agent demonstration as a standalone chapter with isolated dependencies. For example, chapter5/coding-agent/requirements.txt manages packages for the coding agent implementation, while chapter7/orpheus/requirements.txt handles audio synthesis dependencies. This design prevents version clashes—allowing one chapter to use torch==2.1.0 while another requires torch==2.0.1—and ensures that updating one experiment never contaminates another's runtime. The CI pipelines defined in .github/workflows/*.yml enforce this isolation by installing only the specific chapter's requirements before executing tests.

Locating Chapter-Specific Requirements

Before updating, identify the exact requirements.txt driving your target code. Key dependency files include:

• chapter5/coding-agent/requirements.txt — Dependencies for the coding agent implementation
• chapter8/trajectory-verifier/requirements.txt — Packages for trajectory verification systems
• chapter7/orpheus/requirements.txt — Audio processing and speech synthesis libraries
• chapter4/async-agent/requirements.txt — Asynchronous agent dependencies

Each file acts as a pinned snapshot of a successful experiment, capturing exact versions needed for reproducibility.

Step-by-Step Dependency Update Process

Install Current Baseline

Navigate to the chapter directory and establish the current environment state. This ensures you are upgrading from the correct baseline versions recorded in the repository.

cd chapter5/coding-agent
pip install -r requirements.txt

Identify Outdated Packages

Query PyPI for available updates while maintaining the current environment's integrity.

pip list --outdated

This outputs a table showing installed versions versus latest releases, allowing you to identify specific packages requiring updates.

Upgrade and Regenerate Lock File

Update individual packages or perform bulk upgrades, then freeze the new state to requirements.txt. This step overwrites the previous pins with updated versions.

# Upgrade a specific package

pip install -U openai

# Or bulk upgrade all outdated packages

pip list --outdated | awk '{print $1}' | xargs -n1 pip install -U

# Regenerate the requirements file with new pins

pip freeze > requirements.txt

Always verify functionality after upgrading by running the chapter's test suite:

pytest tests

Alternative Workflow Using pip-tools

For automated dependency resolution and cleaner updates, use pip-tools to manage the chapter's requirements. This approach generates fully pinned files from high-level dependencies.

pip install pip-tools

# Generate a new requirements.txt with resolved dependencies

pip-compile --output-file=requirements.txt

# Sync environment to exactly match the generated file

pip-sync

This workflow ensures that dependency conflicts are resolved at compile time rather than during installation.

Why Chapter-Level Isolation Matters

Reproducibility: Each requirements.txt represents a snapshot of a working experiment. When you deliberately regenerate this snapshot using pip freeze, you preserve the reproducibility promise while modernizing dependencies.

CI Integration: The repository's GitHub Actions workflows (.github/workflows/*.yml) install chapter-specific requirements before running tests. Any breaking changes introduced during your upgrade will surface as pipeline failures, preventing unstable dependencies from merging into the main branch.

Version Isolation: By maintaining separate manifests in chapter4/async-agent/, chapter7/orpheus/, and other directories, the project allows incompatible library versions to coexist across different AI agent implementations.

Summary

• Navigate to the specific chapter directory (e.g., chapter5/coding-agent/) before performing any updates
• Run pip list --outdated to identify which packages have newer releases available
• Use pip freeze > requirements.txt to regenerate the lock file after successful upgrades
• Consider using pip-tools (pip-compile and pip-sync) for automated dependency resolution and environment synchronization
• Verify updates by executing the chapter's test suite or observing CI pipeline results in .github/workflows/

Frequently Asked Questions

Do I need to update dependencies at the root level of the repository?

No. The bojieli/ai-agent-book repository does not maintain a root-level requirements.txt. Each chapter—from chapter4/async-agent to chapter8/trajectory-verifier—maintains its own dependency manifest to ensure complete isolation between experiments. Always navigate to the specific chapter directory before running pip commands.

How do I upgrade all packages in a chapter simultaneously?

Navigate to the target chapter and run pip list --outdated | awk '{print $1}' | xargs -n1 pip install -U to bulk upgrade all outdated packages, then execute pip freeze > requirements.txt to save the new versions. Verify the upgrade succeeded by running pytest or the chapter's specific test commands, as the repository's CI pipelines will validate the changes against .github/workflows/*.yml.

Will updating one chapter's dependencies affect other chapters?

No. Because each chapter uses its own requirements.txt file and virtual environment isolation, updating dependencies in chapter5/coding-agent/ will not impact chapter8/trajectory-verifier/ or any other chapter. This architectural design ensures that experimental code remains stable even as individual chapters modernize their dependency stacks.

How does the CI system handle chapter-specific dependency updates?

According to the source code in .github/workflows/*.yml, the CI pipelines install requirements from the specific chapter being tested before execution. When you modify a chapter's requirements.txt and submit a pull request, the automated tests run against that exact dependency set, ensuring that updates do not break the book's executable examples.

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