# Coding Agent Architecture: A Deep Dive into the Seven Core Tools

> Explore the Coding Agent architecture built with seven core tools: Read, Write, Grep, Glob, Bash, Code Interpreter, and Generic Executor for autonomous coding workflows.

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

---

**A Coding Agent relies on seven deterministic tools—Read, Write, Grep, Glob, Bash, Code Interpreter, and a Generic Executor—to manipulate files, execute commands, and maintain state, enabling lightweight autonomous coding workflows.**

The Coding Agent architecture implemented in the `bojieli/ai-agent-book` repository demonstrates how a minimal toolset can power complex LLM-driven development tasks. This design centers on seven core utilities that handle file operations, pattern matching, shell execution, and runtime state management. Understanding this architecture provides a blueprint for building auditable, sandboxed autonomous coding systems.

## Three-Layer Architecture Design

The Coding Agent architecture separates concerns into three distinct layers, each with specific responsibilities and implementation files.

### LLM Core Layer

The **LLM Core** generates natural-language plans and invokes tools through a dispatcher. According to the source code in `bojieli/ai-agent-book`, this layer lives in [`chapter5/coding-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/agent.py) within the `CodingAgent` class. This class maintains the conversation loop, processes model outputs, and routes tool calls to the appropriate handlers.

### Tool Layer

The **Tool Layer** exposes concrete operations the LLM can invoke. These implementations reside in [`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py) and provide deterministic, sandboxed capabilities for file system and code execution. Each tool is stateless and receives arguments via a JSON-RPC-like schema defined in the `tool_specs` dictionary.

### Runtime State Layer

The **Runtime State** tracks environmental context and execution metrics. Stored in `CodingAgent.system_state`, this layer maintains the current working directory, operating system details, Python version, and `tool_call_counts` statistics. This state persists across tool invocations, enabling the agent to maintain context throughout a coding session.

## The Seven Core Tools Explained

The Coding Agent architecture derives its capabilities from seven specialized tools. Six perform concrete operations, while the seventh serves as the dispatch mechanism.

### 1. Read Tool (`read_file`)

The **Read** tool loads file contents from disk, handling both text and binary formats. Located in [`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py), the `read_file()` function enables the agent to inspect source code, configuration files, and documentation before making modifications.

```python

# Example: Reading a source file

content = read_file(path="src/utils.py")

```

### 2. Write Tool (`write_file`)

The **Write** tool creates or overwrites files with supplied text. The `write_file()` function in [`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py) supports atomic file operations, ensuring the agent can safely generate new modules or update existing codebases.

```python

# Example: Creating a new helper module

write_file(path="src/helpers.py", text="# Auto-generated helper\n")

```

### 3. Grep Tool (`grep`)

The **Grep** tool searches file contents using regular-expression patterns. Implemented as `grep()` in [`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py), this utility allows the agent to locate specific code patterns, TODO comments, or function definitions across the project tree.

```python

# Example: Searching for TODO comments

matches = grep(pattern=r"#\s*TODO", files=["src/**/*.py"])

```

### 4. Glob Tool (`glob_files`)

The **Glob** tool lists files matching Unix-style glob patterns. The `glob_files()` function in [`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py) provides directory traversal capabilities, enabling the agent to discover project structure and batch-process file collections.

```python

# Example: Discovering all Python modules

files = glob_files(pattern="src/**/*.py")

```

### 5. Bash Tool (`run_bash`)

The **Bash** tool executes shell commands within the runtime environment. The `run_bash()` function in [`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py) supports package management, version control operations, and system diagnostics.

```python

# Example: Installing dependencies

bash_output = run_bash(command="pip install -r requirements.txt")

```

### 6. Code Interpreter (`run_python`)

The **Code Interpreter** executes Python code snippets and returns results. Implemented as `run_python()` in [`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py), this tool handles calculations, data processing, and dynamic analysis tasks that require runtime evaluation.

```python

# Example: Statistical analysis of codebase

stats = run_python(code="""
import json, pathlib
todos = [p for p in pathlib.Path('src').rglob('*.py') if '# TODO' in p.read_text()]

print(json.dumps({'count': len(todos)}))
""")

```

### 7. Generic Executor (`_call_tool`)

The **Generic Executor** serves as the tool dispatcher that marshals arguments and records usage statistics. Located in [`chapter5/coding-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/agent.py) as the `_call_tool()` method, this component validates tool requests, executes the corresponding function, updates `system_state.tool_call_counts`, and returns outputs to the LLM.

```python

# Example: Internal dispatch mechanism

result = agent._call_tool(name="write", args={"path": "README.md", "text": "# Project"})

```

## Execution Flow: From LLM to Tool Invocation

The Coding Agent architecture follows a five-step execution loop that connects the LLM to physical file system operations:

1. **User Input Processing** – The system sends the user prompt to the LLM along with the current `SystemState` snapshot, including directory context and previous tool outputs.

2. **LLM Reasoning** – The model analyzes the request and emits a JSON payload when tool intervention is required. The payload specifies the tool name and arguments according to the `tool_specs` schema.

3. **Tool Dispatch** – The `_call_tool()` method in [`chapter5/coding-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/agent.py) validates the JSON payload, maps the tool name to the corresponding function in [`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py), and executes the operation.

4. **State Update** – After execution, the agent increments `system_state.tool_call_counts` for the specific tool and captures any side effects, such as modified files or new directory states.

5. **Result Integration** – The tool output returns to the LLM as formatted text, enabling the model to continue reasoning, issue additional tool calls, or generate the final user-facing response.

## Implementation Details and Key Files

The Coding Agent architecture spans multiple files in the `bojieli/ai-agent-book` repository, each serving a distinct architectural function:

- **[`chapter5/coding-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/agent.py)** – Contains the `CodingAgent` class, `_call_tool()` dispatcher, and conversation loop logic.
- **[`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py)** – Implements the six concrete tools: `read_file()`, `write_file()`, `grep()`, `glob_files()`, `run_bash()`, and `run_python()`.
- **[`chapter5/coding-agent/main.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/main.py)** – Provides the CLI interface that wires components together and displays the TODO list and status information.
- **[`chapter5/coding-agent/config.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/config.py)** – Handles environment variables for API keys, model providers, and runtime configuration.
- **[`book-en/chapter5.md`](https://github.com/bojieli/ai-agent-book/blob/main/book-en/chapter5.md)** – Documents the design rationale and theoretical foundation for the seven-tool architecture.

The JSON-RPC-like invocation schema enables transparent tool usage. When the LLM requires a file search, it generates:

```json
{
  "tool": "grep",
  "args": {"pattern": "# TODO", "files": ["src/**/*.py"]}

}

```

The dispatcher executes `grep()` and returns matched lines, allowing the model to proceed with context-aware refactoring tasks.

## Summary

- The Coding Agent architecture consists of three layers: the LLM Core (`CodingAgent` class), the Tool Layer (seven utilities), and the Runtime State (`SystemState`).
- The seven core tools include Read, Write, Grep, Glob, Bash, Code Interpreter, and the Generic Executor dispatcher.
- Tool implementations reside in [`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py), while the dispatch logic lives in [`chapter5/coding-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/agent.py).
- The system tracks tool usage via `system_state.tool_call_counts`, enabling execution auditing and rate limiting.
- All tools are exposed through a JSON-RPC-like schema, allowing the LLM to invoke deterministic functions through structured JSON payloads.

## Frequently Asked Questions

### What are the seven core tools in the Coding Agent architecture?

The seven core tools are **Read** (`read_file`), **Write** (`write_file`), **Grep** (`grep`), **Glob** (`glob_files`), **Bash** (`run_bash`), **Code Interpreter** (`run_python`), and the **Generic Executor** (`_call_tool`). These tools handle file operations, pattern matching, shell execution, Python code evaluation, and request dispatching respectively.

### How does the Coding Agent track tool usage across sessions?

The agent maintains a `SystemState` object within the `CodingAgent` class that records `tool_call_counts` for each utility. After every tool invocation in `_call_tool()`, the system increments the corresponding counter, enabling runtime monitoring and execution auditing.

### Where is the tool dispatcher implemented in the source code?

The tool dispatcher is implemented as the `_call_tool()` method in [`chapter5/coding-agent/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/agent.py). This method validates incoming JSON payloads, routes requests to the appropriate functions in [`chapter5/coding-agent/tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter5/coding-agent/tools.py), and manages the return of results to the LLM.

### Why does the Coding Agent architecture limit itself to seven specific tools?

The deliberate constraint to seven deterministic tools creates a **minimal, auditable surface area** that can be easily sandboxed and secured. According to the [`book-en/chapter5.md`](https://github.com/bojieli/ai-agent-book/blob/main/book-en/chapter5.md) documentation, this limited toolset covers the essential "perception" and "execution" operations needed for coding tasks while minimizing the risk of unintended side effects or security vulnerabilities.