AI Agents Book | Nam Hoai Nguyen

Information

Full Name: AI Agents in Depth: Design Principles and Engineering Practice

Author Name: Bojie Li

This book is translated to 11 languages (English, Vietnamese, Chinese,…)

Aug 24, 2026

Instructions

The book "AI Agents in Depth: Design Principles and Engineering Practice" by Bojie Li serves as the definitive architectural blueprint to bridge this gap. Throughout its ten chapters, the author establishes a rigorous, system-level design philosophy built upon two foundational formulas:

Core Concept: Agent = LLM + Context + Tools (Brain + Eyes + Limbs)

Engineering Realization: Agent = Model + Harness (Core Brain + Operational & Governance Framework)

This article compiles and analyzes the entire text in comprehensive technical detail, providing an architect's guide to transitioning from basic prompting to industrial-strength Agent systems.

Architectural Roadmap

Part 1: Design and build agents (Chapter 1 - 6)

Chapter 1: Foundations of Modern Agents & Harness Engineering

The architecture of a modern Agent begins by defining the precise division of labor. If the Large Language Model (LLM) acts as the decision-making brain, the Harness (the engineering wrapper around the model) is the operational cockpit responsible for maintaining security boundaries, executing error recovery, and managing state.

The ReAct Loop: Modern Agents operate on a sequential loop: Thought → Action → Observation. The accumulated trajectory of this loop enables the model to dynamically update its understanding of the environment and plan its next moves.

Harness Engineering (Agent = Model + Harness): In enterprise environments, LLMs are powerful but inherently unpredictable (exhibiting hallucination, tool parameter mismatches, and parsing errors). The Harness introduces a robust, predictable system around the model, governing five key responsibilities:

Context Management: Ensuring the model has the most relevant, noise-free information at each decision epoch.

Tool Interface: Standardizing parameter schema definitions and managing invocation life cycles.

Constraints & Guardrails: Enforcing strict behavioral and security boundaries, operating on a "Default-unsafe" model for destructive actions.

Verification: Programmatically checking the correctness of tool outputs (e.g., executing static analyses or linters on generated code).

Correction: Automatically handling local failures (such as retrying failed API calls with modified parameters) without aborting the entire process.

Chapter 2: Context Engineering & Cache Optimization

If the LLM is the brain, the Context is its "eyes"—directly determining the upper bound of the Agent's capabilities. This chapter focuses on the API-level context structure and the physical hardware constraints of LLM serving infrastructure.

API-Level Context Structure: The token window is split into two distinct parts: the Static Prefix (System Prompt + Tool Schema Definitions) and the Dynamic Trajectory (ongoing conversation history, tool calls, and tool execution results).

Architectural Constraints of KV Cache & Prompt Cache:

KV Cache: An internal model mechanism that caches the Key-Value states of historical tokens to avoid redundant calculations during generation.
Prompt Cache: An inference engine-level optimization that caches static, identical context prefixes across different API requests. Landing a Prompt Cache hit reduces token costs up to 10x and slashes TTFT (Time-to-First-Token) from 3–5 seconds down to ~0.5 seconds.
The Append-Only Design Pattern: To maintain an unbroken Prompt Cache hit, the Static Prefix must be absolutely immutable (not even modified by a single space character). Any dynamic system state (such as timestamps, system variables, or dynamic instructions) must be appended as new messages at the very end of the trajectory, never injected into the System Prompt.

Request 1: | System Prompt + Tools (1200 tkn) | user: "What's the weather?" | -> Cache hit ✓
Request 2: | System Prompt + Tools (1200 tkn) | user: "What time is it?"    | -> Cache hit ✓ (Reuses KV Cache)
Request 3: | System + Tools + "Time: 10:30"   | user: "What's the weather?" | -> Cache MISS ✗ (Complete recalculation)

Agent Skills & Progressive Disclosure: To prevent "Lost in the Middle" syndrome and context bloating, the system implements Progressive Disclosure. Rather than stuffing every business SOP (Standard Operating Procedure) into the System Prompt, the Agent maintains a lean Metadata Catalog (~300 tokens) introducing available skills. Only when the Agent decides to activate a specific skill does the runtime read the detailed SKILL.md file and append it to the end of the trajectory, preserving the upstream KV Cache.

Agent Status Bar: A dynamic, system-appended user message inserted at the end of the context, providing real-time metadata (e.g., current timestamp, tool call counts, active TODO checklists, system workspace path cwd, and detailed error logs) to make the hidden system state transparent to the LLM.

Chapter 3: User Memory & Knowledge Base (Advanced RAG)

How does an Agent maintain a persistent, cross-session user memory and retrieve information from millions of enterprise documents without suffering from context rot?

Two-Layer Memory Architecture:

Resident Layer (L0/L1): Active, persistent profiles structured as Advanced JSON Cards containing core, immutable user traits, kept permanently in the active context.

Retrieval Layer (L2): The raw, complete historic interaction trajectory indexed in database storage. The Agent uses Contextual Retrieval to fetch historic context as needed.

Advanced RAG Engineering: Moving beyond simple chunking to dense/sparse hybrid retrieval, multi-vector retrieval, and reranking. To preserve semantic context when documents are sliced, Anthropic's Contextual Retrieval method uses an LLM to prepend a brief, context-preserving summary to each chunk prior to vectorization.

Structured Indexing Systems:

RAPTOR: Recursively clusters and summarizes document chunks, constructing a hierarchical tree that allows the Agent to traverse from macro thematic overviews down to micro specific details.
GraphRAG: Extracts entity-relation networks and performs community detection, enabling the Agent to synthesize global answers across highly disconnected documents.

Agentic RAG: A shift from passive, single-turn "Retrieve -> Generate" pipelines to an active, iterative ReAct loop. The Agent analyzes the query, writes search queries, calls search tools multiple times, evaluates retrieved materials, and autonomously decides when it has accumulated sufficient information to formulate an answer.

Chapter 4: Tool Design – The Limbs of the Agent

Tools are the actuators that allow an Agent to perceive, query, and modify the digital environment.

Core Tool Classification:

Perception Tools: Acquiring state information from the environment (web search, file reading, multimodal document parsing). Tool outputs must be paginated, truncated, or summarized to prevent token storms.

Execution Tools: Modifying the state of the environment (running Python code, executing bash commands, writing files, calling external APIs).

Collaboration Tools: Controlling the lifecycles of sub-Agents (spawning, waiting, signaling).

Model Context Protocol (MCP): A standardized client-server protocol that uniformizes how AI Agents interface with tools, data sources, and services. MCP allows developers to build tool servers once and plug them seamlessly into any compatible front-end (e.g., Cursor, Claude Desktop, or OpenClaw).

Execution Security & Sandboxing: To mitigate Prompt Injection and Remote Code Execution (RCE) risks via poisoned tool inputs, the Harness must execute code within isolated, ephemeral sandboxes (e.g., gVisor, WebAssembly, or firewalled containers), implementing a strict "Execute - Verify - Feedback" loop.

Chapter 5: Coding Agents (OpenClaw) & The Meta-Capability of Programming

Writing code is not merely a software engineering task; it is the fundamental thinking language and system-building tool of general-purpose Agents. Practically any professional artifact (PDF reports, PowerPoint decks, web UIs, data visualizations) is best generated and iterated upon when expressed as executable code.

OpenClaw Architecture: Integrates three critical pillars: Deep Research, Computer Use, and Programming. It operates using 7 legendary general-purpose tools: Python Sandbox, Bash Shell, Read File, Write File, Edit File (diff-based), Glob, and Grep.

Programming as a Meta-Capability:

Rigorous Logic: Translating complex mathematical or logical reasoning into code, executing it, and verifying self-consistency via runtime outcomes.
Generative UI: Writing code to dynamically render visualizations, interactive forms, and dashboards, while automatically repairing layout or script errors via console log feedback.
Agent Bootstrapping: The ultimate recursive capability where a parent Coding Agent writes code to configure, spawn, test, and debug a specialized, next-generation child Agent.

Chapter 6: Real-Time Multimodal Interaction

To move past the rigid, sequential "turn-taking" model of interaction, modern Agents must adapt to asynchronous, real-time, and multimodal environments.

Asynchronous Event-Driven Architecture: Implementing an internal Event Queue and Event Bus allows the Agent to receive real-time, asynchronous external triggers (e.g., incoming emails, webhooks, system interrupts) even when busy. It supports cascading cancellations and state serialization via trajectory preservation.

Millisecond-Scale Voice Interaction: The evolution of conversational voice systems:

Traditional Cascade Pipeline: Silero VAD (voice activity detection, 500-800ms latency) -> Whisper ASR (speech-to-text, 50-200ms) -> LLM (inference, 100-500ms) -> Fish Audio TTS (text-to-speech, 200-500ms). The accumulated sequential latency is highly unnatural.
Omnimodal End-to-End: Native audio-in, audio-out models that collapse latency boundaries.
Full-Duplex Communication: Allowing simultaneous listening and speaking, enabling natural user interruptions mid-speech.

Computer Use & Robotics:

Computer Use: Operating graphical user interfaces (GUIs) via visual grounding, click/type action spaces on virtual screens, and dynamic world models to parse applications.
Robotics: Mapping visual inputs to physical actuator commands using VLA (Vision-Language-Action) models, leveraging Sim2Real transfer to maintain policy fidelity when transitioning from simulated environments to the real world.

Chapter 7: Evaluating Agent Systems (Evaluating Agents)

If you cannot measure it, you cannot improve it. The book establishes a scientific three-level evaluation hierarchy:

┌────────────────────────────────────────────────────────┐
│ LEVEL 3: OPTIMAL OPTIMIZATION DECISIONS                │
│ (Selecting the best model based on budget & resources) │
└───────────────────────────▲────────────────────────────┘
                            │
┌────────────────────────────────────────────────────────┐
│ LEVEL 2: EVALUATION METHODOLOGY (How to score)         │
│ (Detailed Rubrics, LLM-as-a-Judge, Bradley-Terry)      │
└───────────────────────────▲────────────────────────────┘
                            │
┌────────────────────────────────────────────────────────┐
│ LEVEL 1: EVALUATION ENVIRONMENT (Where to measure)     │
│ (Simulators, Tool Verifiers, User Simulators)          │
└────────────────────────────────────────────────────────┘

Production-Grade Metrics:

Pass@k: Measures the system's capability ceiling (the Agent runs $k$ times, succeeding if at least 1 run is correct). Ideal for deep research and complex autonomous debugging.
Pass^k (Production Reliability): A rigorous business metric requiring $k$ consecutive runs to succeed flawlessly, ensuring zero catastrophic failures or unpredictable side effects.
Process (White-box) Metrics: Analyzing internal execution logs (average ReAct steps, tool parameter error rates, self-correction success rates) to diagnose system bottlenecks.

LLM-as-a-Judge: Utilizing state-of-the-art models (e.g., GPT-5, Gemini 2.5) to evaluate open-ended tasks against comprehensive, multi-dimensional scoring Rubrics.

Mitigating Length Bias: Judges naturally favor longer, verbose outputs. The system mitigates this by penalizing fluff in the Rubric, normalizing answer lengths before pair-wise comparison, and continually tracking the correlation coefficient between word count and score.

Chapter 8: Model Post-Training

When prompt engineering and Harness constraints hit their scaling limits, you must modify the internal weights of the LLM itself to optimize long-context handling and tool invocation accuracy.

SFT Memorizes, RL Generalizes:

Supervised Fine-Tuning (SFT): drapes the model in high-quality "input-output" demonstration pairs, teaching it to strictly conform to structural JSON tool-calling formats. Without SFT formatting stability, RL signals dissolve into NaN errors.
Reinforcement Learning (RL): Optimizes the model's policy by maximizing expected rewards through autonomous trial-and-error. RL enables the Agent to discover novel, highly optimal trajectories outside the initial training distribution, granting robust generalization capabilities in edge cases.

GRPO (Group Relative Policy Optimization): DeepSeek's breakthrough RL algorithm that completely eliminates PPO's resource-heavy critic network. GRPO generates a group of outputs (e.g., 16 rollouts) for a single query, using relative within-group comparison to estimate the advantage function, drastically optimizing memory footprint and training throughput on SWE-bench.

Process-Supervised Reward Systems: Interlocking Outcome Reward (overall goal success) and Process Reward (step-by-step reasoning correctness) alongside Path Validation Rewards (RLVP) to completely suppress Reward Hacking.

Chapter 9: Continual Self-Evolution of Agents

How can an Agent grow smarter and more reliable with every task it performs without requiring constant model weight updates? Chapter 9 outlines a dual-loop architecture utilizing 4 Update Carriers:

Update Carrie	Content Updated	Target Scenario
Experience Base	Markdown Sops, comparative success/failure cases	Storing factual, case-specific business rules
Prompt & Skill	Modifying, patching, or adding system-level instructions	Rapidly adjusting conceptual thinking rules
Program (Workflow)	Compiling stable execution paths into hard-coded scripts	Automating consistent, repeatable procedures
Model Parameters	Extracting gold-standard trajectories for SFT/DPO data	Deeply embedding stylistic and reasoning habits

Sleep Learning: To prevent instant, toxic feedback (such as transient network drops or adversarial user poisoning) from corrupting the system, the Agent runs two isolated loops:

Online Execution Loop: The Agent focuses entirely on executing the task at hand, writing immutable, raw trajectories as cryptographic proof of execution.
Offline Consolidation Loop: Running in the background when the system is idle, this loop reviews trajectories, consolidates duplicate knowledge, resolves contradictions, proposes candidate system updates, and runs extensive regression tests.

The Root-of-Trust Boundary: Under no circumstances is an evolving Agent permitted to modify its own validation criteria (such as test cases, release thresholds, or monitoring scripts) to prevent the Agent from lowering the bar to report artificial progress.

Chapter 10: Multi-Agent Collaboration

When a task's complexity exceeds the context window or attention capacity of a single Agent, the problem must be scaled to an organizational level by coordinating a network of specialized, collaborating Agents.

Collaboration Frameworks:

Shared Context: Excellent for small-group discussions, but prone to rapid context bloat and conversational noise.

Isolated Context: The peak of modular system design. Agents operate in isolated address spaces, communicating exclusively via structured JSON messages, event buses, or virtual filesystems.

Virtual Filesystem (VFS): Organizing the multi-agent storage space into four cleanly isolated directories mounted under a single root:

                   Virtual Filesystem Root (/)
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
  /scratch/<id>        /workspace/shared          /mnt/gdrive
   (Private Space)     (Shared Workspace)      (External Mount)
  - Ephemeral sandbox  - Shared read/write      - External cloud storage
  - Cleared on exit    - Optimistic lock/git    - External access auth

Classic Collaboration Patterns:

Peer-to-Peer: The Proposer-Reviewer pattern. For example, a Translation Agent translates text -> a Proofreading Agent edits the grammar -> a Vision Agent inspects screen-render layout images to evaluate PPTX structure from a multi-modal perspective.
Manager-led: A central coordinator Agent dynamically decomposes and routes workloads to a pool of parallel, subordinate specialized Agents.
OS Analogy: Mapping multi-agent lifecycles to operating system primitives (spawning sub-agents as fork, waiting as join, cancelling as kill, and tracking state via JSONL trajectory logs).

System Failure Modes: Guarding against race conditions on shared workspaces, cascading error amplification across agent chains, common-cause cognitive failures (when all agents run on the same base LLM), and the diffusion of responsibility.

The true AI Agent revolution does not lie in searching for a "perfect" foundational model. It lies in the engineering of the systems surrounding it. As Bojie Li concludes, even as foundational models grow more capable, the intelligent Harness that protects safety boundaries and manages state will not disappear. Instead, it will continuously migrate to new frontiers of capability—where humans and intelligent machines co-exist, create, and evolve together.