导读：如何从零构建一个 AI 智能体？

你是否曾被‘Agent框架’的黑盒搞得晕头转向？是否在看了一堆理论后，依然不知道一个ReAct循环到底如何落地？我们相信，征服复杂概念的最好方法，不是仰望它，而是亲手拆解、重构它。欢迎来到Tiny Agent的世界，这里没有魔法，只有源码。

本教程的核心理念只有一句话：最好的学习方式是亲手构建。整个演进过程被精心拆解为迭代的版本（Git Tag），每个版本都聚焦于一个核心能力的从无到有，可以随时切换到任意阶段独立运行和研读源码。

为了让这套“渐进式”开发和学习真正高效，每个章节都被设计为统一的七段式结构。它既不是干瘪的源码注释，也不是纯理论的白皮书，而是一条从问题到方案的完整思考路径。

每个章节的结构

当你打开任何一个版本对应的章节时，都会看到以下七个部分，它们承担着不同的角色：

1. 概念引入 本章不会一上来就丢出代码或术语，而是从一个真实场景中的棘手问题出发：为什么单轮问答不够用？为什么大模型需要借助搜索引擎？为什么 Agent 会陷入死循环？通过还原这些痛点，你会清楚地知道这一章要解决什么，以及我们为什么非得引入一套新机制不可。

2. 整体方案 在动手之前，先用一张架构图把整章的设计思路“鸟瞰”一遍。这里会梳理系统由哪些模块组成，数据如何流转，新增的组件如何与已有部分协作。读完这一节，你应该能够明白“请求从哪进来，经过哪些步骤，最后从哪出去”。

3. 核心概念 这是最重要的原理层。我们会把本章的关键知识点拆解成若干个小概念逐一讲解，比如“什么是 SSE 协议”、“Message Protocol 中的角色分工”、“ReAct 循环的 Thought → Action → Observation 三态是怎样推导的”。这一节的目标是让你不仅会做，而且真正懂原理。

4. 工程实现 开始接触项目代码，但绝不是把几百行源码直接贴出来让你硬读。我们会围绕本章新增或修改的关键文件，说明每个模块的职责、核心类的关系以及最重要的运行时流程。你将被引导去关注“数据在哪里被转换”“控制权在哪里被交接”这类结构性问题，而非在细节里迷失。

5. Git Diff 导读 因为整个项目被切分到了不同的 Git Tag 中，所以这一节会像一份精炼的代码对比报告：相比上一版本，我们新增了哪些文件、修改了哪些模块、重构了哪些部分，每一项变化分别是为了解决上一版本的什么具体问题。你甚至可以把这一节当作检查清单，用来核对自己的理解是否到位。

6. 架构思考 到此我们并不满足于“跑通了”。这一节会追问三个问题：

   • 为什么这样设计？（方案的合理性）
   • 有没有其他实现方式？（替代方案及其利弊权衡）
   • 当前的局限是什么？（工程落地的优化方向）

7. 本章小结 简短回顾本章交付的能力，然后自然而然地引出下一个版本将要面对的挑战。你会发现，每个版本的终点，恰好就是下一版本的起点。

整个演进路线一览

全书共分五个部分，恰好对应了 Tiny Agent 渐进式演进路线的关键版本。每一部分都承担着明确的使命：

• 第一部分：模型基础与全栈通信（基础篇）
  从终端里的第一次 LLM 调用开始，搭建流式 Web 前后端通信，实现多轮连续对话，并通过 Prompt Template、System Prompt 与结构化输出让模型“按规矩办事”。这一部分将为你打下不可或缺的全栈基础。
  里程碑：构建一个 AI 聊天助手。

• 第二部分：外部知识与规划行动（连接篇）
  引入 RAG 打通文档切片、向量检索与引用回复的完整链路，用 Function Calling 为 Agent 装上调用外部工具的双手，最后手写 ReAct 核心循环，让 Agent 从被动调用工具走向自主思考、感知与行动。完成这一部分后，你的 Agent 将不再困于训练数据之内。
  里程碑：构建一个能够检索知识并自主调用工具的智能体。

• 第三部分：能力拓展与流程编排（拓展篇）
  通过 MCP 协议统一工具接入标准，以 Skills 实现能力的模块化封装与动态加载，再用 Workflow 将单次调用编排为可复用的多步骤任务流。由此，Agent 的能力边界变得开放、可组合且可持续扩展。
  里程碑：构建一个支持标准工具协议、技能可插拔的智能体工作流平台。

• 第四部分：工程强化与生产就绪（强化篇）
  为 Agent 加入上下文管理与 Token 熔断，构建长期记忆漏斗实现跨会话知识留存；引入混合检索、重排序与向量数据库提升检索精度；通过评估指标与全链路追踪让效果可验证；并建立工具权限分级与确认机制，构筑安全边界，使 Agent 走向可靠、可观测、可审计。
  里程碑：构建一个记忆持久、检索精准、行为可审计的高可靠 Agent 系统。

• 第五部分：多模交互与群智协同（前沿篇）
  突破纯文本界面，赋予 Agent 语音与视觉能力，最终探索多智能体协作模式，让多个不同角色的 Agent 共同完成复杂任务。这是迈向生产级智能体的最后一站。 里程碑：构建一个能听会说、看懂世界并协同工作的多模态多智能体系统。

无论是想深入理解 Agent 底层原理的工程师，还是正做技术选型的架构师，这份教程都会是一张清晰、可动手验证的地图。

技术栈与前置技能

在开始之前，让我们先对齐一下“装备库”。为了保持轻量与纯粹，我们尽量避免了笨重的框架，选择了一套最符合现代 AI 开发直觉的轻量级技术栈。

我们的技术栈

• 核心语言：Python 3.12+（主打简洁与生态，零门槛上手）
• Web 框架：FastAPI（用于构建高性能的 Agent 后端 API）
• 前端交互：原生 HTML + CSS + JavaScript （用于构建极简 Web 页面）
• 版本控制：Git（我们唯一的“时光机”，用于切换版本代码）

你需要具备的基础

• Python 基本功：熟悉基础语法、异步编程及基本的数据结构。
• Git 基础操作：知道如何 git clone 和 git checkout（我们会带你完成其余操作）。
• 无需大模型开发经验：你不必提前了解其他 Agent概念，我们将从最底层的 API 调用开始，带你手写属于自己的控制流。

现在，让我们从第一部分开始——你只需要一个 LLM 的 API Key 和一个终端。

→ 进入第一章：Hello LLM（你好，大模型）