我开源了一本 AI Agent 实战手册，附 340+ 可运行代码

GitHub 地址：https://github.com/swf2020/AI-Agent-in-Practice
文档 CC BY-NC-SA 4.0，代码 MIT，完全免费

---

这些痛点，你可能也遇到过

去年开始接触 AI Agent 的时候，我也和很多人一样，跟着教程跑通了 LangChain 的 Hello World。一行 from langchain import ... 把聊天机器人搭好了，觉得"Agent 不过如此"。

但真正动手做项目时，问题一个接一个冒出来。

第一个坎是知识库问答。 接到"给公司搭一个内部知识问答系统"的需求后，我发现自己不知道该用什么向量数据库——Chroma、Milvus、Qdrant 到底选哪个？文档分块大小怎么调？混合检索（BM25 + 向量）怎么做？重排序模型选哪个？效果怎么评估？网上的教程大多讲单点知识，很少有把整条流水线——分块、嵌入、检索、重排、生成、评估——完整串起来的。

第二个坎是 Multi-Agent。 看完了 ReAct 的原理文章，但 Multi-Agent 之间怎么通信？AutoGen 和 CrewAI 各适合什么场景？怎么防止两个 Agent 互相刷屏陷入死循环？这些问题只有在真正动手做的时候才会暴露出来。

第三个坎是 MCP 协议。 想学 Model Context Protocol，官方文档是英文的，社区教程比较基础，停在"让 Claude 读本地文件"的 demo。想自己写一个数据库查询的 MCP Server，不知道怎么设计安全边界、怎么做 Tool 注册、怎么处理错误。

第四个坎是面试准备。 想准备 AI 岗位的面试，发现网上的题目东一个西一个，好不容易找到几道真题，也没有参考答案，更不知道面试官到底想听什么。

这些都是我在学习和开发 Agent 过程中真实踩过、也反复琢磨过的问题。也是我开始整理这份开源手册的原因——把自己踩过的坑、走过的路、学到的经验，系统地记录下来。

---

这本书是什么

《AI Agent In Practice》是一份开源的 AI Agent 工程实践学习手册，放在 GitHub 上，任何人都可以免费阅读、运行书中所有代码、参与贡献。

维度	数据
文档	63+ 篇 Markdown，10 章 + 附录，支持本地 MkDocs 离线阅读
代码	340+ Python 文件，21 个独立项目，每个项目可独立运行
测试	372 条测试全部通过
面试题	200+ 真题（原理 / 工程 / 设计 / 视野 / 开放），附参考回答
协议	文档 CC BY-NC-SA 4.0，代码 MIT
费用	零付费门槛

---

这本书能帮你解决什么问题

按照从入门到实战的学习阶段来组织，内容覆盖：

入门阶段

• LLM 核心概念：Token / Temperature / Context Window / 注意力机制
• Prompt Engineering 实战：从基础提示词到 CoT 思维链
• 统一多模型调用层：一个封装层同时支持 GPT-4o、Claude、DeepSeek、Qwen

进阶阶段

• 微调技术：LoRA / QLoRA / Unsloth 完整微调流水线，附可运行代码
• RAG 完整链路：分块 → 嵌入 → 向量库 → 检索 → 重排 → 生成 → 评估
• MCP 协议与工具系统：三个 MCP Server 实战，从安全边界设计讲起

Agent 阶段

• ReAct 范式：推理与行动的交替循环
• LangGraph 状态机：有状态 Agent + Checkpoint 断点续跑
• AutoGen / CrewAI Multi-Agent 实战：从两个 Agent 到多角色协作团队

生产阶段

• FastAPI + Redis + ARQ 异步任务队列
• 成本控制与 Token 优化
• 缓存策略：Prompt Cache + Semantic Cache
• 安全防御：Prompt Injection 防护
• 可观测性：LangSmith / LangFuse 链路追踪

垂直场景实战

• 项目一：AI 选股分析师（基于 TradingAgents）
• 项目二：企业知识库智能问答
• 项目三：数据分析 Agent（Text-to-SQL）
• 项目四：自动化工作流 Agent

面试准备

• 200+ 真题，按原理 / 工程 / 设计 / 视野 / 开放五大类别分类
• 每道题附带考察点、解答思路、参考答案

---

内容预览：这本书里到底写了什么

MCP 协议实战

MCP Server 的教程如果只教"读文件"和"写文件"，那离生产环境还有很远的距离。

这本书里的 MCP Server 教程从安全边界设计开始讲起。一个文件系统 Server 需要考虑路径白名单——如果不做路径校验，等于给 LLM 开了一个无限制的本地文件访问权限，这在生产环境是不可接受的。

书中展示了 _validate_path 的实现：

def _validate_path(requested: str) -> Path:
    """确保请求的路径始终在允许的根目录下"""
    resolved = (ALLOWED_ROOT / requested).resolve()
    if not str(resolved).startswith(str(ALLED_ROOT)):
        raise PermissionError(f"Path escapes allowed root: {requested}")
    return resolved

三个 MCP Server 实战（文件系统操作、数据库查询、代码执行沙箱），每个都覆盖了安全边界设计、Tool 注册机制和错误处理。

Multi-Agent 协作的工程细节

书中不是只画一张"Agent A 和 Agent B 对话"的概念图，而是手把手教你用 AutoGen 搭建一个真实的分析团队：

UserProxy → GroupChatManager → AnalystAgent → CoderAgent → ReviewerAgent

同时讲解最关键的工程问题：

• 发言权管理：auto 模式灵活但不可预测，生产环境建议用自定义选择器函数，把状态机逻辑显式写出来
• 死循环防护：is_termination_msg 是正常退出，max_consecutive_auto_reply 是紧急熔断，两个必须同时设置
• 代码执行安全：生产环境必须使用 Docker executor，不能直接在宿主机运行 LLM 生成的代码

生产级落地

第六章完整覆盖了 Agent 上线前需要考虑的六个问题：流式输出、成本控制、缓存策略、安全防御、可观测性、Docker 容器化。

用一张架构图展示完整的服务链路：

客户端 → FastAPI 网关 → Redis 任务队列 → ARQ Worker → LLM + 工具层
                                        ↓
                                Prometheus + Grafana
                                        ↓
                                LangFuse 链路追踪

HTTP 网关只负责接收请求、返回 task_id，实际的 Agent 执行由 ARQ Worker 异步完成。这样即使 Agent 跑了 2 分钟，HTTP 连接也不会超时。

200+ 面试题

附录收录了 200+ 面试真题，来源包括牛客、知乎、Datawhale、各大厂面经。每道题都标注了来源和日期，附带考察点、解答思路和参考答案。

举几道真题：

原理题：Transformer 的自注意力机制是如何工作的？为什么比 RNN 更适合处理长序列？

设计题：为一个法律文书润色场景，设计从数据收集到上线的完整微调方案。

开放题：如果让你给 AutoGen 的 GroupChat 加入"局部可见性"（某些 Agent 不应该看到其他 Agent 的全部消息），你会怎么设计？

---

两条学习路线，你选

工程路线（6-8 周）

适合想快速做出产品的工程师。

Week 1-2: 大模型 API 调用 + Prompt Engineering + 多模型统一封装
Week 3-4: RAG 完整流水线 + Advanced RAG + 本地知识库
Week 5:   Function Calling + MCP 协议 + 工具系统
Week 6-7: ReAct + LangGraph + Multi-Agent 系统
Week 8:   生产级落地 + 4 个垂直场景实战项目

面试路线（10-12 周）

适合准备跳槽 AI 岗位的同学。

Week 1-2: 原理基础（Transformer / LoRA / Tokenization / 位置编码）
Week 3-4: 框架掌握（LangChain / LangGraph / AutoGen / CrewAI）
Week 5-6: 架构设计（RAG 架构 / Agent 记忆系统 / Multi-Agent 协作模式）
Week 7-8: 技术演进（LLM 发展史 / Agent 演进 / 关键技术趋势预判）
Week 9-12: 200+ 真题刷题 + STAR 答题法练习

---

快速开始

# 1. Clone
git clone https://github.com/swf2020/AI-Agent-in-Practice
cd AI-Agent-in-Practice

# 2. 选一个项目，装依赖（以 RAG 为例）
cd "libs/AI Agent In Practice/02_RAG（检索增强生成）/2.4 _动手_从零搭建本地知识库问答系统"
pip install -r requirements.txt

# 3. 配置 .env，运行
cp .env.example .env
# 编辑 .env 填入你的 API Key
python main.py

或者直接用 MkDocs 本地阅读文档：

pip install mkdocs-material
mkdocs serve
# 浏览器打开 http://localhost:8000

---

写在最后

Agent 时代，不缺概念，缺能落地的工程实践。

这本书是我个人在学习和实践过程中的经验总结，肯定还有很多不足之处。把它开源出来，一方面是做个记录，方便自己回顾；另一方面是希望能帮到其他也在学 Agent 的同学。

如果你觉得这份手册对你有帮助，欢迎去 GitHub 点个 Star：

https://github.com/swf2020/AI-Agent-in-Practice

更欢迎提 Issue、PR、参与共建——无论是补充内容、修正错误、还是分享你的实践经验，任何贡献都会被认真对待。

希望通过这个项目，能和大家一起少走弯路，早日做出能上线的 Agent 系统。