# Understanding the Architecture of the AI Agent Book: A Modular Framework for LLM Agents

> Explore the AI Agent Book's layered architecture: LLM + Context + Tools. This modular framework guides you through progressive agent capabilities from basic ReAct loops to multi-agent collaboration.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: architecture
- Published: 2026-07-29

---

**The AI Agent Book implements a layered architecture based on the formula Agent = LLM + Context + Tools, organized into ten self-contained chapters that demonstrate progressive agent capabilities from basic ReAct loops to multi-agent collaboration.**

The **bojieli/ai-agent-book** repository transforms academic AI agent concepts into executable code, demonstrating how to build, evaluate, and evolve autonomous systems. Understanding the architecture of the AI Agent Book reveals a modular, chapter-driven design that allows developers to iterate through increasingly sophisticated agent implementations while maintaining clean separation between reasoning, memory, and tool execution layers.

## Core Architectural Formula

The architecture revolves around the fundamental equation **Agent = LLM + Context + Tools**. In this model, the **LLM** provides reasoning capabilities, the **Context** supplies knowledge through static or retrieved memory, and the **Tools** give the agent actionable capabilities to interact with external systems. This separation of concerns appears consistently across all ten chapters, enabling readers to swap individual components without breaking the overall system.

## The Ten-Chapter Modular Structure

The repository is divided into ten independent chapters, each containing self-contained experiments that build upon previous concepts. This progression creates a clean, extensible hierarchy:

1. **Agent Basics** (`chapter1/web-search-agent/agent.py#L26`) — Introduces the ReAct loop (Reason → Act → Observe → Answer) and basic tool usage
2. **Context Engineering** ([`chapter2/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter2/README.md)) — Covers KV-Cache optimization, prompt engineering, and context compression techniques
3. **User Memory & RAG** ([`chapter3/user-memory/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter3/user-memory/README.md)) — Implements persistent user memory and retrieval-augmented generation systems
4. **Tools** ([`chapter4/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/README.md)) — Explores the MCP protocol, perception/execution/collaboration tools, and async agent patterns
5. **Coding Agent** ([`chapter5/coding-agent/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/README.md)) — Demonstrates production-grade code generation and tool-driven self-improvement
6. **Evaluation** ([`chapter6/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter6/README.md)) — Provides benchmark suites, statistical significance testing, and evaluation-driven model selection
7. **Model Fine-Tuning** ([`chapter7/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter7/README.md)) — Compares SFT vs. RL approaches, tool-call internalization, and sample efficiency
8. **Continual Evolution** ([`chapter8/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter8/README.md)) — Implements learning from trajectories and dynamic updates of prompts and programs
9. **Multimodal & Real-Time** ([`chapter9/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter9/README.md)) — Covers voice interfaces, GUI automation, robotics, and computer-use paradigms
10. **Multi-Agent Collaboration** ([`chapter10/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter10/README.md)) — Explores swarm intelligence, shared/isolated context management, and emergent agent societies

According to the repository's main documentation, this structure explicitly maps the journey from simple single-agent systems to complex multi-agent societies while maintaining the core architectural formula throughout.

## Core Architectural Components

Each chapter implements a consistent set of core components that abstract the complexity of LLM interactions into manageable layers.

### LLM Wrapper and Backend Resolution

Every agent initializes an `OpenAI` or `OpenRouter` client through a centralized backend resolver. The `config.resolve_llm_backend` function abstracts provider-specific details for Moonshot, OpenRouter, and other LLM services, ensuring a uniform API across all chapters. This abstraction allows the same agent code to run against different model providers by changing configuration rather than implementation.

### Conversation History and Message Flow

The architecture maintains state through a mutable list of role-based messages (`system`, `user`, `assistant`, `tool`). This conversation history is passed to the LLM on every turn, enabling long-term memory or episodic resets depending on the chapter's requirements. The message format follows the OpenAI chat completions schema, ensuring compatibility with various backend providers.

### ReAct Trace and Observability

Every reasoning step, tool call, and observation is recorded in a `trace` list for debugging and evaluation. Helper utilities such as `format_trace_step` render these traces for UI display or logging. In [`chapter1/web-search-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/web-search-agent/agent.py), the `STEP_LABELS` dictionary (lines 26-33) defines visual icons for each step type, making the agent's thought process transparent and inspectable.

### Tool Abstraction Layer

Tools are defined as dictionaries with a `type` of `builtin_function` (for Moonshot) or native tool specs (for GPT-5), automatically injected into the LLM request payload. The `_get_tools` method in [`chapter1/web-search-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/web-search-agent/agent.py) (lines 39-56) demonstrates conditional injection based on backend availability, allowing the same agent to use either native provider tools or custom implementations.

### System Prompt Engineering

The system prompt encodes the agent's role, task decomposition guidelines, and tool usage instructions. The web-search agent uses a multi-step prompt that explicitly instructs the model to follow "think → act → observe → answer" patterns (lines 57-73 in [`chapter1/web-search-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/web-search-agent/agent.py)). This structured prompting ensures consistent behavior across different LLM backends.

### Modular Configuration

A centralized `Config` class (imported from [`config.py`](https://github.com/bojieli/ai-agent-book/blob/main/config.py)) manages constants like `SEARCH_TIMEOUT` and model-specific defaults. This configuration layer allows each chapter to adjust runtime parameters without code duplication, supporting everything from quick prototyping to production deployments.

## The ReAct Interaction Loop

The architecture implements a standardized ReAct (Reasoning + Acting) loop that governs how agents process requests and interact with tools. This loop repeats up to `max_iterations` (default 5) to prevent endless cycles, as implemented in [`chapter1/web-search-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/web-search-agent/agent.py) (lines 99-107).

The interaction flow follows five distinct stages:

1. **Prompt Construction** — System prompt combines with user question and conversation history
2. **LLM Reasoning** — The model generates `reasoning_content` (captured and logged separately from final output)
3. **Tool Invocation** — When `finish_reason == "tool_calls"`, the agent parses JSON arguments and invokes local implementations like `search_impl`
4. **Observation Logging** — Tool results are appended as `tool` messages to the conversation history
5. **Answer Generation** — When the LLM finishes without tool calls, the content is returned as the final answer

This loop creates a deterministic execution pattern while allowing for complex multi-step reasoning when required.

## Advanced Extensibility Patterns

The architecture supports several advanced patterns that extend beyond basic ReAct implementations.

### Native Tool Integration

For GPT-5 and compatible models, the `_build_openrouter_request` method in [`chapter1/search-codegen/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/search-codegen/agent.py) (lines 31-49) constructs requests that mirror native Go implementations. This enables seamless use of `web_search` and `code_interpreter` tools without additional glue code, demonstrating how the architecture adapts to provider-specific capabilities.

### Chainable Agent Workflows

The `GPT5AgentChain` class (lines 66-78 in [`chapter1/search-codegen/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/search-codegen/agent.py)) demonstrates composable steps where each request's output becomes the next request's input. This pattern supports complex workflows across multiple agents while maintaining the core message-passing architecture.

### Learning from Experience

The reinforcement learning implementation in [`chapter1/learning-from-experience/rl_agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/learning-from-experience/rl_agent.py) creates a self-improving agent that samples from its own trajectories. This component updates policies without human-in-the-loop supervision, bridging the gap between static prompt engineering and dynamic agent evolution covered in Chapter 8.

## Implementation Examples

The following examples demonstrate the architecture in practice:

### Running a Basic Web-Search Agent

```python
from chapter1.web-search-agent.agent import WebSearchAgent

agent = WebSearchAgent(verbose=True)          # reads MOONSHOT_API_KEY from env

question = "Moonshot AI 的 Context Caching 是什么技术？"
answer = agent.search_and_answer(question)

print("Answer:", answer)
print("\nTrace:")
for step in agent.get_trace():
    print(step)

```

This instantiates the core ReAct loop, logging each thought, action, and observation before returning the synthesized answer.

### Using GPT-5 Native Tools

```python
from chapter1.search-codegen.agent import GPT5NativeAgent

gpt5 = GPT5NativeAgent(api_key="YOUR_OPENROUTER_KEY")
result = gpt5.search_and_analyze(
    topic="latest developments in transformer architectures",
    analysis_code="""
import matplotlib.pyplot as plt

# dummy analysis – in real case you would process the search results

plt.plot([1, 2, 3], [2, 3, 5])
plt.title("Trend")
"""
)

print(result["response"])

```

The request automatically includes both `web_search` and `code_interpreter` tools through the architecture's tool abstraction layer.

### Reinforcement Learning Loop

```python
from chapter1.learning-from-experience.rl_agent import RLAgent
from chapter1.learning-from-experience.game_environment import SimpleGameEnv

env = SimpleGameEnv()
rl_agent = RLAgent(env)

for episode in range(10):
    reward = rl_agent.run_episode()
    print(f"Episode {episode}: reward = {reward}")

```

This gathers trajectories for later use in SFT or RL fine-tuning, demonstrating the architecture's support for continual evolution.

## Summary

- The **AI Agent Book** architecture implements the formula **Agent = LLM + Context + Tools** across ten progressive chapters
- Each chapter is self-contained yet shares core utilities like [`config.py`](https://github.com/bojieli/ai-agent-book/blob/main/config.py), conversation history management, and the ReAct trace system
- The **ReAct loop** provides a deterministic execution pattern with built-in iteration limits (`max_iterations=5`) to prevent infinite loops
- **Tool abstraction** supports both custom implementations and native provider tools through conditional injection in `_get_tools`
- **Backend resolution** via `config.resolve_llm_backend` ensures provider-agnostic code that works with Moonshot, OpenRouter, and OpenAI APIs
- The modular design allows independent chapter execution while maintaining interlocking capabilities through shared data models

## Frequently Asked Questions

### What is the core formula behind the AI Agent Book architecture?

The architecture is built on the formula **Agent = LLM + Context + Tools**. The LLM handles reasoning, Context provides static or retrieved knowledge, and Tools enable external actions. This separation appears consistently across all ten chapters, from basic web search to multi-agent collaboration.

### How does the ReAct loop prevent infinite execution cycles?

The implementation in [`chapter1/web-search-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/web-search-agent/agent.py) sets a default `max_iterations` limit of 5 (lines 99-107). The loop tracks the current iteration count and terminates if the agent exceeds this threshold without reaching a final answer, ensuring deterministic resource usage.

### Can I use different LLM providers without rewriting agent code?

Yes. The architecture uses `config.resolve_llm_backend` to abstract provider-specific initialization. The same agent code runs against Moonshot, OpenRouter, or OpenAI APIs by changing environment variables or configuration constants, with provider-specific logic handled in `_get_tools` and `_build_openrouter_request` methods.

### How does the architecture support agent evolution and learning?

Chapter 1's [`rl_agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/rl_agent.py) and Chapter 8's continual evolution components implement learning-from-trajectory patterns. The architecture supports both offline fine-tuning (SFT/RL) and online prompt/program updates, allowing agents to improve from their own execution traces without human intervention.