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

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 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 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, the read_file() function enables the agent to inspect source code, configuration files, and documentation before making modifications.

# 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 supports atomic file operations, ensuring the agent can safely generate new modules or update existing codebases.

# 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, this utility allows the agent to locate specific code patterns, TODO comments, or function definitions across the project tree.

# 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 provides directory traversal capabilities, enabling the agent to discover project structure and batch-process file collections.

# 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 supports package management, version control operations, and system diagnostics.

# 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, this tool handles calculations, data processing, and dynamic analysis tasks that require runtime evaluation.

# 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 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.

# 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 validates the JSON payload, maps the tool name to the corresponding function in 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 – Contains the CodingAgent class, _call_tool() dispatcher, and conversation loop logic.
• 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 – Provides the CLI interface that wires components together and displays the TODO list and status information.
• chapter5/coding-agent/config.py – Handles environment variables for API keys, model providers, and runtime configuration.
• 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:

{
  "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, while the dispatch logic lives in 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. This method validates incoming JSON payloads, routes requests to the appropriate functions in 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 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.

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