深入理解 AI Agent：设计原理与工程实践

本仓库是《深入理解 AI Agent：设计原理与工程实践》一书的开源主仓库，包含全书正文与配套示例代码。全书正文、配图与配套实验代码全部开源，欢迎把实验亲手跑一遍、提 issue 和 PR。

📖 电子书

全书正文与编译好的 PDF 位于 book/ 目录：

• 正文源码：book/introduction.md（引言）、book/chapter1.md ~ book/chapter10.md（第一至第十章）、book/afterword.md（后记）

• 编译版 PDF：book/深入理解-AI-Agent-李博杰-v1.0.pdf

• 自行编译：安装 pandoc、xelatex、ElegantBook 文档类与相关字体后，运行

  cd book && bash build_pdf.sh
  

  图表由 book/gen_*_figs.py 生成、存于 book/images/，排版细节见 book/preamble.tex 与 book/*.lua。

📑 内容速览（第 1–10 章）

全书围绕核心公式 Agent = LLM + 上下文 + 工具 展开，十章内容如下：

• 第 1 章 · Agent 基础知识：从"模型即 Agent"的新范式出发，建立 Agent = LLM + 上下文 + 工具 的核心公式，并引入 Harness 工程——模型之外的一切工程能力，才是真正的竞争力所在。
• 第 2 章 · 上下文工程：上下文决定 Agent 的能力上限。深入大模型 API 的上下文结构、KV Cache 友好设计、提示工程、动态提示词与 Agent Skills、状态栏元信息，以及上下文压缩策略。
• 第 3 章 · 用户记忆和知识库：让 Agent 跨会话记住用户、并接入外部知识。涵盖用户记忆系统、RAG 基础管道，以及超越扁平文本的知识组织与检索（结构化索引、知识图谱等）。
• 第 4 章 · 工具：工具是 Agent 的双手。讲工具分类与通用设计原则、MCP 协议与工具选择的挑战、感知/执行/协作三类工具，以及事件驱动的异步 Agent。
• 第 5 章 · Coding Agent 与代码生成：代码是"能创造新工具的工具"，是通用 Agent 的元能力。以生产级 Coding Agent 为例，展示这一最强通用工具的完整实现。
• 第 6 章 · Agent 的评估：把 Agent 的表现变成可比较的信号。从评估环境、数据集设计、指标体系，到统计显著性、可观测性、评估驱动选型，直至生产级内部评估与仿真环境。
• 第 7 章 · 模型后训练：预训练、SFT、RL 三阶段全景。何时选 SFT、何时选 RL，RLHF、算法比较、数据与环境，以及让模型学会工具调用、提升样本效率的前沿探索。
• 第 8 章 · Agent 的自我进化：不改权重也能成长。三种学习范式，从经验中学习、主动工具发现，到"从工具使用者到工具创造者"，让 Agent 从"聪明"走向"熟练"。
• 第 9 章 · 多模态与实时交互：把感知与行动从文本扩展到语音、GUI 与物理世界。语音三范式（级联/端到端全模态/全双工）、流式语音感知与合成、Computer Use 与机器人操作。
• 第 10 章 · 多 Agent 协作：群体的智能可以高于个体。多 Agent 分类框架、何时真正优于单 Agent、共享与不共享上下文的协作、失败模式，以及涌现的"Agent 社会"。

💻 配套代码

所有项目按章节组织，与全书十章一一对应，涵盖从基础概念到高级技术的完整学习路径。每个项目都是可独立运行的完整示例，目录为 chapterN/项目名/。

🚀 第 1 章 · Agent 基础知识

learning-from-experience - 强化学习 vs LLM 对比

chapter1/learning-from-experience/

对比传统强化学习（Q-learning）与基于 LLM 的上下文学习，复现 Shunyu Yao 的 "The Second Half" 博文中的关键洞察。通过寻宝游戏展示 LLM 如何以 250-400 倍的样本效率超越传统 RL。

核心概念：强化学习、上下文学习、样本效率、先验知识

web-search-agent - Kimi K2 模型即 Agent

chapter1/web-search-agent/

实现具备基础深度搜索能力的 Agent，能够进行多轮搜索和信息整合。

核心概念：网络搜索、模型原生 Agent

search-codegen - GPT-5 原生工具集成

chapter1/search-codegen/

构建能够基础深度搜索能力和代码沙盒能力的 Agent，综合利用网络搜索、代码执行等工具实现复杂分析。

核心概念：网络搜索、代码生成、模型原生 Agent

context - 上下文消融研究

chapter1/context/

通过系统性的消融实验展示 Agent 上下文各个组件的重要性。支持多种 LLM 提供商（SiliconFlow Qwen、字节 Doubao、月之暗面 Kimi），配置不同的上下文模式观察 Agent 行为变化。

核心概念：上下文管理、工具调用、ReAct 循环、消融研究

🎯 第 2 章 · 上下文工程

local_llm_serving - 本地 LLM 部署与工具调用

chapter2/local_llm_serving/

跨平台的本地 LLM 部署方案，自动选择最佳后端（vLLM 或 Ollama）。展示即使 0.6B 的小模型也能通过良好的系统设计实现出色的工具调用能力。支持流式响应，实时显示思考过程。

核心概念：模型部署、Chat Template、流式处理、工具调用

attention_visualization - 注意力机制可视化

chapter2/attention_visualization/

可视化 LLM 的完整输入输出 token 序列和注意力权重分布，深入理解模型如何处理上下文、进行推理和调用工具。

核心概念：注意力机制、token 分析、推理过程可视化

kv-cache - KV Cache 友好的上下文设计

chapter2/kv-cache/

探索不同上下文管理模式对 KV Cache 的影响，演示常见的错误模式如何破坏缓存效率。通过实验展示正确的上下文设计如何显著降低延迟和成本。

核心概念：KV Cache、上下文优化、性能调优

context-compression - 上下文压缩策略

chapter2/context-compression/

实现并对比多种上下文压缩策略，包括摘要、关键信息提取、语义压缩等。在保持 Agent 能力的同时减少 token 使用量。

核心概念：上下文压缩、token 优化、信息密度

prompt-engineering - 提示工程消融研究

chapter2/prompt-engineering/

扩展 Tau-Bench 框架，通过系统性的消融实验量化不同提示工程因素对 Agent 性能的影响。展示语气风格、指令组织、工具描述等因素如何影响任务完成率。

核心概念：提示工程、消融研究、性能基准测试

system-hint - 系统提示优化

chapter2/system-hint/

研究系统提示（System Hint）对 Agent 行为的影响，探索如何通过优化系统提示提升性能。

核心概念：系统提示、行为引导、提示优化

log-sanitization - 日志脱敏处理

chapter2/log-sanitization/

实现智能的日志脱敏系统，在保留调试信息的同时保护敏感数据。

核心概念：隐私保护、日志处理、数据安全

📚 第 3 章 · 用户记忆和知识库

user-memory - 用户记忆系统

chapter3/user-memory/

构建长期用户记忆系统，让 Agent 能够记住用户偏好和历史交互，提供个性化服务。

核心概念：长期记忆、个性化、用户建模

user-memory-evaluation - 用户记忆评估框架

chapter3/user-memory-evaluation/

系统化评估用户记忆系统的准确性、相关性和有效性，包含多种测试场景和评估指标。

核心概念：评估框架、测试用例、性能度量

dense-embedding - 稠密嵌入向量检索服务

chapter3/dense-embedding/

构建向量相似性搜索服务，对比研究 ANNOY（基于树）和 HNSW（基于图）两种近似最近邻索引算法。展示不同索引策略在性能、内存占用和更新能力上的权衡。

核心概念：稠密嵌入、向量检索、ANN 算法、语义搜索

sparse-embedding - 稀疏检索引擎

chapter3/sparse-embedding/

从零实现基于 BM25 算法的稀疏向量搜索引擎，通过丰富的日志和可视化接口展示搜索引擎的内部工作机制，理解词频权重计算和倒排索引原理。

核心概念：稀疏嵌入、BM25、TF-IDF、精确匹配

retrieval-pipeline - 混合检索流水线

chapter3/retrieval-pipeline/

构建完整的检索流水线，结合稠密检索、稀疏检索和神经重排序。通过精心设计的测试用例，系统性展示混合检索在不同场景下的优势互补效果。

核心概念：混合检索、神经重排序、跨编码器、检索融合

multimodal-agent - 多模态信息提取

chapter3/multimodal-agent/

对比三种多模态处理策略：原生多模态处理、提取为文本、工具化分析。通过统一框架下的消融研究，揭示不同技术路径在保真度、成本和灵活性上的权衡。

核心概念：多模态、视觉理解、OCR、端到端处理

structured-index - 结构化索引

chapter3/structured-index/

实现并对比 RAPTOR（递归抽象树）和 GraphRAG（知识图谱）两种先进索引策略。通过索引技术手册演示如何构建反映知识内在层次和关联的结构化索引。

核心概念：RAPTOR、GraphRAG、层次摘要、知识图谱

agentic-rag - 智能体 RAG

chapter3/agentic-rag/

对比传统 Non-Agentic RAG 与 Agentic RAG 的性能差异。展示 Agent 如何通过 ReAct 模式主导迭代式信息检索，在处理复杂司法问答时显著提升答案质量。

核心概念：Agentic RAG、ReAct 循环、迭代检索、主动探索

agentic-rag-for-user-memory - 利用 Agentic RAG 构建用户记忆

chapter3/agentic-rag-for-user-memory/

将 Agentic RAG 框架应用于管理用户对话历史，通过多轮迭代搜索能力处理跨会话的记忆检索，实现基础回忆和多会话检索能力。

核心概念：用户记忆、对话历史索引、跨会话检索

contextual-retrieval - 上下文感知检索

chapter3/contextual-retrieval/

实现 Anthropic 提出的上下文感知检索技术，通过为文本块生成包含核心上下文的前缀摘要，解决传统分块方法的上下文丢失问题，将检索失败率降低 49-67%。

核心概念：上下文增强、前缀生成、语义锚定、检索优化

contextual-retrieval-for-user-memory - 上下文感知的用户记忆系统

chapter3/contextual-retrieval-for-user-memory/

将上下文感知检索技术应用于用户记忆构建，结合 Advanced JSON Cards 与上下文感知 RAG，形成双层记忆结构，实现更高层次的主动服务能力。

核心概念：双层记忆、结构化事实、上下文检索、主动服务

structured-knowledge-extraction - 结构化知识提取

chapter3/structured-knowledge-extraction/

从海量司法判例数据集中提取隐性知识，通过因子分析和重要性建模，构建判决经验模型。展示如何将数据中的隐性模式转化为 Agent 可用的结构化决策逻辑。

核心概念：知识发现、因子分析、数据驱动、判决建模

🛠️ 第 4 章 · 工具

perception-tools - 感知工具 MCP 服务器

chapter4/perception-tools/

构建全面的感知工具集，提供网络搜索、多模态理解、文件系统操作和公共数据源访问能力。大部分功能基于免费开放 API（DuckDuckGo、Open-Meteo、Yahoo Finance、OpenStreetMap 等），无需 API 密钥即可使用。

核心概念：MCP 协议、多模态解析、公共数据源、文档理解、地理信息服务

execution-tools - 执行工具 MCP 服务器

chapter4/execution-tools/

实现具备安全机制的执行工具集，包括文件操作、代码解释器、虚拟终端和外部系统集成。通过 LLM 二次审批机制防止危险操作，自动摘要复杂输出，并对代码进行语法验证。

核心概念：MCP 协议、执行安全、LLM 审批、结果摘要、自动验证

collaboration-tools - 协作工具 MCP 服务器

chapter4/collaboration-tools/

提供全面的协作能力，包括浏览器自动化（browser-use 框架）、人机协同（Human-in-the-Loop）、多渠道通知（Email、Telegram、Slack、Discord）和定时器管理。支持敏感操作的管理员审批和定时任务调度。

核心概念：MCP 协议、浏览器自动化、HITL 模式、多渠道通知、定时任务

agent-with-event-trigger - 事件触发型 Agent 与 MCP 集成

chapter4/agent-with-event-trigger/

基于 FastAPI 构建的现代化事件驱动 Agent，默认集成前三个 MCP 服务器的所有工具。采用原生异步架构实现清晰的 MCP 工具加载，通过 HTTP API 接收多源事件（Web、即时消息、GitHub、定时器等）。提供自动 API 文档（Swagger UI）和后台监控能力。

核心概念：FastAPI、原生异步、MCP 集成、事件驱动、自动 API 文档、工具编排

active-tool-selection - 主动工具选择

chapter4/active-tool-selection/

实现智能工具选择机制，让 Agent 能够根据任务需求主动选择最合适的工具组合，而非被动接受预定义的工具集。

核心概念：工具选择、动态工具加载、任务分析

async-agent - 异步 Agent 架构

chapter4/async-agent/

展示如何构建真正的异步 Agent，支持并发任务处理、非阻塞 I/O 和高效的资源利用。

核心概念：异步编程、并发处理、事件循环、非阻塞 I/O

此外，chapter4/docker-compose.yml 与 chapter4/DOCKER_DEPLOYMENT.md 提供了将上述 MCP 工具服务器容器化部署的参考方案。

💻 第 5 章 · Coding Agent 与代码生成

coding-agent - 生产级 Coding Agent

chapter5/coding-agent/

基于 Claude 构建的生产级 AI 编码助手，采用纯 Python 实现所有工具，无需命令行依赖。包含 17 个完整实现的工具，涵盖文件操作、搜索、Shell 操作和项目管理。特别实现了纯 Python 的 Grep 工具，完全兼容 ripgrep 的功能。

核心特性：

• 纯 Python 实现，无命令行依赖，特别适合 Mac 用户
• 完整的工具套件：文件读写编辑、纯 Python 正则搜索、目录列表、Shell 会话管理
• 系统提示技术：时间戳、工具调用计数、TODO 列表管理、详细错误信息
• 持久化 Shell 环境、自动 Lint 检测、流式响应支持
• 支持多个 LLM 提供商（Anthropic、OpenAI、OpenRouter）

核心概念：代码生成、文件编辑、纯 Python 工具、系统提示、Lint 检测、多提供商支持

🎯 第 6 章 · Agent 的评估

terminal-bench - 终端环境基准测试

chapter6/terminal-bench/

Terminal-Bench 是测试 AI Agent 在真实终端环境中表现的基准测试。从编译代码到训练模型、设置服务器，评估 Agent 如何处理真实的端到端任务。包含约 100 个任务的数据集和执行框架，支持多种 Agent 实现。

核心概念：终端自动化、任务评估、Docker 沙箱、基准测试

SWE-bench - 软件工程基准测试

chapter6/SWE-bench/

SWE-bench 是评估大语言模型解决真实 GitHub 问题能力的基准测试。给定代码库和问题描述，模型需要生成能够解决问题的补丁。包含 SWE-bench、SWE-bench Lite、SWE-bench Verified 和 SWE-bench Multimodal 多个版本。

核心概念：代码修复、GitHub 问题、补丁生成、Docker 评估

GAIA - 通用 AI 助手基准测试

chapter6/GAIA/

GAIA 旨在评估下一代 LLM（具有工具增强、高效提示、搜索访问等能力的 LLM）。包含 450+ 个需要不同程度工具和自主性的非平凡问题，答案明确无歧义。分为 3 个难度级别。

核心概念：工具使用、多步推理、自主性评估

OSWorld - 操作系统级 Agent 基准

chapter6/OSWorld/

评估 Agent 在完整操作系统环境中执行复杂任务的能力，包括文件管理、应用程序操作和系统配置。

核心概念：操作系统自动化、多应用协作、系统级任务

android_world / android-world - Android 环境基准

chapter6/android_world/ 和 chapter6/android-world/

评估 Agent 在 Android 移动环境中的表现，包括应用导航、UI 交互和任务完成能力。

核心概念：移动自动化、Android UI、应用交互

tau2-bench - 工具增强推理基准

chapter6/tau2-bench/

专注于评估 Agent 使用工具进行复杂推理的能力，包括计算、搜索和数据处理等场景。

核心概念：工具增强推理、多步骤任务、工具组合

elo-leaderboard - ELO 排行榜系统

chapter6/elo-leaderboard/

实现基于 ELO 评分系统的 Agent 性能排行榜，通过对战比较来评估不同 Agent 的相对能力。

核心概念：ELO 评分、相对评估、排行榜系统

🧠 第 7 章 · 模型后训练

本章包含多个模型后训练项目，涵盖监督微调（SFT）和强化学习（RL）的各种技术和应用场景。

AdaptThink - 自适应推理深度

chapter7/AdaptThink/ 和 chapter7/AdaptThink-original/

让推理模型学会根据问题难度自适应选择推理模式（Thinking vs NoThinking）。通过约束优化和重要性采样，在大幅降低推理成本（45-69%）的同时提升准确率。基于 DeepSeek-R1-Distill-Qwen 模型，使用 DAPO 算法训练。

核心概念：自适应推理、推理成本优化、约束优化、重要性采样

retool - 工具增强数学推理

chapter7/retool/

使用多轮对话和代码沙箱提升大语言模型数学推理能力。通过 SFT 和 RL 两阶段训练，让模型学会使用代码执行环境辅助数学问题求解。基于 Qwen2.5-32B-Instruct，在 AIME 2024 数据集上训练，使用 DAPO 算法和 SandboxFusion 沙箱。

核心概念：工具使用、代码执行、数学推理、多轮对话、DAPO 算法

AWorld / AWorld-train - 具身 Agent 训练

chapter7/AWorld/ 和 chapter7/AWorld-train/

基于 AWorld 框架训练具身 Agent，让 Agent 能够在虚拟环境中执行复杂任务并从经验中学习。

核心概念：具身智能、环境交互、经验学习

SFTvsRL - SFT 与 RL 对比研究

chapter7/SFTvsRL/

系统性对比监督微调（SFT）和强化学习（RL）在不同任务上的效果，分析两种方法的优劣和适用场景。

核心概念：SFT vs RL、训练方法对比、性能分析

verl - 高效 RL 训练框架

chapter7/verl/

verl 是专门为大语言模型 RLHF 训练设计的高效强化学习框架，支持 PPO、GRPO、DAPO 等多种算法。

核心概念：RLHF、PPO、分布式训练、高效优化

Intuitor - 直觉推理训练

chapter7/Intuitor/

训练模型的直觉推理能力，让模型能够快速做出合理判断而不需要详细的思考链。

核心概念：直觉推理、快速决策、思考链优化

MultilingualReasoning - 多语言推理

chapter7/MultilingualReasoning/

训练模型在多种语言环境下的推理能力，提升跨语言任务的表现。

核心概念：多语言、跨语言推理、语言泛化

SpatialReasoning - 空间推理训练

chapter7/SpatialReasoning/

专注于训练模型的空间推理能力，处理涉及位置、方向、距离等空间关系