🚀 100 天搞定 Agent 开发

一条从理解 LLM 本质，到构建可控 Agent 系统的工程化学习路径

2025 年，是 Agent 真正开始爆发的一年。它不再只是 Demo、Prompt 技巧或能力展示，而是被放进真实业务系统中，开始承担明确职责，也开始暴露真实问题。

我从 2024 年 开始做 LLM 和 Agent 相关项目，有过几次真正落地的，也有不少因为方向判断失误、工程复杂度失控而中途终止的项目。

过程中踩过不少坑，有一些比较简单，比如

阿里云百炼接口处理用参数 temperature 控制输出，最好再加上seed参数以便于结果复现。
部分推理模型调用时要加 extra_body 传参{"enable_thinking": true}才能真正让它进行推理。
langchain_openai 默认会吞掉 reasoning_content，导致收不到推理过程的内容，可以通过猴子补丁的方式修复。

还有一些比较复杂，是架构设计和能力边界的问题，比如

把 Prompt 当成逻辑层使用 一开始为了省事，把判断条件、分支选择、状态切换全写进 Prompt。 Prompt 越写越长，也越来越“聪明”，但问题也随之出现：很难调试、很难复现，任何一句话的微调，都可能引发完全不同的行为。到后面你会发现，系统不是坏在模型能力上，而是坏在逻辑藏在自然语言里，没人能真正控制它。
工具列表失控，模型不知道该用什么 工具越加越多，却缺少清晰的边界和分工。对模型来说，这不是“能力增强”，而是决策负担：相似功能的工具混在一起，调用条件模糊，有时选错工具，有时干脆不用工具，行为看起来像“随机发挥”。问题不在模型，而在于你并没有真正告诉它：什么时候该用、什么时候不该用。
没有给 Agent 设定清晰的能力上限 一些本就不适合模型判断的问题，被强行交给模型处理；一些本该由人介入兜底的灰色区间，被乐观地当成“可以自动化”。在小规模测试时，这类问题很难暴露，但一旦进入真实场景，失败会成批出现，而且往往是系统性失败，不是修几个 Prompt 就能解决的。

在不断失败、复盘、修正的过程中，我开始系统性地整理这些经验，并借助 AI 一起校对认知与表达，逐步沉淀出了这份 《100 天搞定 Agent 开发》。

它一方面是我自己的工程笔记和认知复盘，另一方面，也希望能为正在或准备进入 Agent 开发的工程师，少走一些我已经走过的弯路。

整个路径中，大量内容基于真实工程实践，配合主流开源框架的实战，包括但不限于：LangChain、LangGraph、Gradio、Agno、Mem0、Vanna、Langfuse 等。整个学习路径结构大致如下：

Week 1–2：先从 LLM 的底层原理出发，随后通过一个完整的实战项目，开发一个带 UI、支持多模态和深度思考的英语学习 Agent，建立对 Agent 的整体认知。
Week 3–7：深入学习 Agent 的各个关键组成， Prompt 工程、工具调用、RAG、上下文工程、记忆系统。
Week 8–11：关注 Agent 开发与传统软件开发真正不同的地方，以及常见的 Agent 模式。
Week 12–15：通过多个综合项目，把前面的模块与模式串起来，从“能写 Demo”，走向“能支撑复杂系统”。

👥 适合谁

有编程基础，想系统性进入 Agent / AI 工程 的开发者
用过 LLM / LangChain，但感觉「越写越乱」的人
关心 可维护、可演进 Agent 架构 的工程师 / 架构师

🤝 开源共建

这是一个持续演进的项目，结论来自真实实践，也欢迎被修正。

👉 欢迎 Issue / Fork / PR / Contribute

如果你也准备在 2026 年做 Agent，希望这个 repo 能对你有帮助。

🛠️ 环境配置

本教程文档，默认运行在 Python + Jupyter Notebook 环境中

1. 安装依赖并配置环境变量

a.安装 uv

pip install uv

b.在项目根目录执行按照依赖：

uv sync

c.环境变量配置

cp .env.example .env

在 .env 文件中配置自己的 API Key

2.启动 Jupyter Notebook

uv run jupyter notebook

成功启动后打开浏览器进行访问即可，默认地址为 http://localhost:8888

🧭 教程目录

Week 1 ｜ LLM 基础入门

本周目标

建立对大语言模型的“第一性理解”：

模型在“算什么”，而不是“看起来会什么”

为什么它能表现出类智能行为

为什么它天然不稳定、不可控、但又非常有用

Day 1 ｜大语言模型到底在干什么

学习内容

什么是 LLM（大语言模型）
「预测下一个 token」的真实含义
为什么一个“预测器”能产生看起来像智能的行为

Day 2 ｜ Token、Embedding 与向量空间

学习内容

什么是 Token，为什么 LLM 的基本单位是 Token
Embedding 是什么，它解决了什么问题
相似性、类比、联想在向量空间中如何体现

Day 3 ｜ Transformer：模型的计算引擎

学习内容

为什么 RNN 不够用，Transformer 出现的背景
Self-Attention 在“算什么”
Layer 在模型中承担的角色

Day 4 ｜从训练到推理：模型是怎么“学会语言”的

学习内容

预训练阶段模型在做什么
训练过程是怎样的
训练阶段 vs 推理阶段

Day 5 ｜概率、随机性与不稳定性

学习内容

为什么同一个问题多次询问会得到不同答案
temperature 等参数
LLM 擅长什么，不擅长什么

Day 6 ｜一次 LLM API 调用，到底发生了什么？

学习内容

核心要素
一次完整调用过程说明
一次调用中的“可控点”与“不可控点”

Day 7 ｜思考 & 补充学习资料

反思问题

LLM 在回答问题时，它真的“理解”了吗？
模型输出的一句话，本质上是什么？
为什么模型“会在常识问题上犯低级错误”？

Week 2 ｜基于 LangChain + Gradio 的对话 Agent 实战

本周目标

基于 Langchain 和 Gradio 动手实现一个英语学习 Agent

Day 8 ｜用 LLM 生成英文学习内容

学习内容

了解 LangChain
调用 LLM 生成英语文本，如简单句子、段落、词汇解释

Day 9 ｜前端交互

学习内容

了解 Gradio
基于 Gradio 实现英语学习界面
通过界面与 Agent 进行交互

Day 10 ｜多轮对话

学习内容

构建对话型 Agent，可连续辅导用户写作
保存上下文，逐轮提供修改建议

Day 11 ｜流式生成

学习内容

支持流式生成英语内容
提升交互体验

Day 12 ｜多模态

学习内容

支持语音输入和图片输入
实现英语听力、阅读辅助

Day 13 ｜深度思考

学习内容

实现作文评分、复杂阅读理解分析
引导模型进行 chain-of-thought 生成

Day 14 ｜思考 & 补充学习资料

反思问题

LangChain 在这里解决了什么？
“模式切换”本质是什么？
流式输出到底发生在什么层？
一次对话，真正“不可控”的部分是哪一步？

Week 3 ｜提示词工程（Prompt Engineering）

本周目标

学习提示词工程的底层逻辑、通用技巧、和优化迭代技巧

Day 15 ｜提示词工程的底层逻辑

学习内容

Prompt 是什么，不是什么
Prompt 的真实作用
Prompt 适合做什么,不适合做什么

Day 16 ｜ Prompt 的通用技巧

学习内容

编写 Prompt 的通用技巧
编写 Prompt 需要注意什么

Day 17 ｜零样本提示与少样本提示

学习内容

零样本与少样本
示例数量为什么“少而精”
何时不该用少样本

Day 18 ｜思维链

学习内容

单 Prompt 的天然局限
思维链的基本思想
CoT vs 一次性长 Prompt
思维链的延伸

Day 19 ｜结构化输出

学习内容

为什么自然语言输出不可控
常见结构化方式
结构化输出的技巧

Day 20 ｜提示词的优化与迭代

学习内容

为什么一次写好 Prompt 几乎不可能
常见失败模式
Prompt 迭代的基本流程

Day 21 ｜思考 & 补充学习资料

反思问题

Prompt 本质上在做什么？
Prompt 在系统中的位置, 以及能解决的上限
Prompt 如何配合工程能力

Week 4 ｜工具使用

本周目标

学习基于 LLM 工具调用的原理，基于 langchain 的工具调用实现和 MCP 的设计开发

Day 22 ｜为什么 LLM 一定需要工具

学习内容

LLM 的三大天然缺陷
工具在系统中的角色
工具 / 技能 / 智能体的层级关系

Day 23 ｜工具调用的基本机制

学习内容

什么是工具调用(Tool / Function Calling)
Tool Schema 的本质（能力描述）
模型在 Tool Calling 中做了什么

Day 24 ｜基于 Langchain 的工具调用

学习内容

LangChain 在工具调用里做了什么？
一个最小可用示例
LangChain 工具调用流程拆解

Day 25 ｜ MCP 介绍

学习内容

工具调用的问题
什么是 MCP

Day 26 ｜ MCP 实战

学习内容

基于 fastmap 实现一个 MCP Server
基于 cherry studio 连接 MCP Server

Day 27 ｜从工具到技能

学习内容

什么是技能
技能实战

Day 28 ｜思考 & 补充学习资料

反思问题

如果不使用工具，LLM 的能力上限在哪里？
当工具越来越多时，会发生什么？
如果把模型换掉（更弱 / 更强），你当前的工具系统还能正常工作吗？

Week 5 ｜ RAG

本周目标

了解 RAG 的基本原理，学习 RAG 完整链路

Day 29 ｜RAG 是怎么工作的

学习内容

RAG 核心链路拆解：理解从“用户提问”到“检索上下文”再到“LLM 合成答案”的完整闭环（Indexing -> Retrieval -> Generation）。
向量化（Embedding）原理：学习如何将非结构化的文本转化为数学向量，以及余弦相似度如何度量语义相关性。
RAG vs 微调（Fine-tuning）：对比两种技术在实时性、成本和准确度上的优劣，明确 RAG 在处理私有、易变数据时的优势。

Day 30 ｜文档处理与数据加载

学习内容

多格式解析（Loaders）：学习使用工具（如 mineru, marker）解析 PDF、Image 和 Excel 等格式。
数据清洗（ETL）规范：处理文档中的乱码、无意义空格及特殊符号，提升后续 Embedding 的信号质量。
元数据（Metadata）管理：学习在加载时保留页码、作者、日期等关键信息，为后续的精准过滤做准备。

Day 31 ｜文本分块 (Chunking)

学习内容

分块策略的选择：对比“固定长度切分”与“语义切分（如递归字符切分）”，寻找语义完整性与模型上下文窗口的平衡点。
重叠窗口（Overlap）设计：学习如何通过设置重复字符来保持上下文的连续性，防止核心信息在切分点丢失。
分块粒度对检索的影响：探讨“颗粒度过粗”导致的冗余噪音与“颗粒度过细”导致的上下文缺失问题。

Day 32 ｜检索技术 (Retrieval)

学习内容

向量库（Vector Store）选型：了解常用的向量数据库（如 Pinecone, Milvus, FAISS），并实现基础的增删改查。
混合检索（Hybrid Search）：结合“语义向量检索”与“关键词 BM25 检索”，解决专有名词和缩写匹配不准的问题。
多向量检索方案：学习针对同一分块生成多个概括性问题（Multi-vector）以提升复杂提问的匹配率。

Day 33 ｜重排序 (Rerank)

学习内容

Rerank 的必要性：理解初筛（Retrieval）虽然快但不够准，学习如何利用 Cross-Encoder 对 Top-K 结果进行精细化打分。
主流重排序模型应用：实操如何调用 BGE-Reranker 或 Cohere Rerank API 提升检索精度。
上下文压缩（Context Compression）：在重排后剔除低分块，仅保留最有价值的段落以减少 Token 消耗并降低干扰。

Day 34 ｜问题改写与答案生成

学习内容

Query Transformation 技术：学习利用 LLM 将模糊的用户提问改写为更专业的“检索词”（如 Hyde 假设性回答或 Multi-query）。
Prompt 工程实践：设计结构化的 System Prompt，要求模型必须基于检索内容回答，并处理“搜不到相关内容”时的拒答逻辑。
引用归属（Citations）实现：学习如何让模型在回答中自动标注出处（如 [1]），增强 RAG 答案的可信度和可追溯性。