> For the complete documentation index, see [llms.txt](https://gists.lanlance.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gists.lanlance.cn/cssys/agent101.md).

# Agent 101：从零开始构建智能体

> 课程地址：[hello-agents.datawhale.cc](https://hello-agents.datawhale.cc) 共 16 章，5 大部分。本笔记精简关键内容，保留面试点，便于复习。

***

## 前言：为什么要学智能体

AI 的发展经历了三个阶段：从「工具」（执行固定指令）到「助手」（理解自然语言）再到「智能体」（自主规划、执行、反思）。智能体的核心能力是「感知→规划→行动→反思」的闭环，能够自主完成复杂任务。

本课程从零构建 HelloAgents 框架，目标是让你真正理解智能体的工作原理，而不只是调用 API。

***

## 第一部分：智能体基础

### 第一章：什么是智能体

智能体（Agent）是能够感知环境、做出决策并采取行动以实现目标的系统。与普通 LLM 的区别在于：LLM 只做「一问一答」，而智能体能够「多步推理 + 工具调用 + 自主决策」。

智能体的四个核心要素：感知（Perception）、规划（Planning）、行动（Action）、记忆（Memory）。

**面试点**：智能体 vs LLM 的本质区别是「自主性」——智能体能主动调用工具、分解任务、迭代执行，而不是被动等待输入。

智能体的典型应用场景：代码生成与调试、信息检索与研究、任务自动化、多智能体协作。

***

### 第二章：智能体的核心组件

智能体由四个核心组件构成：

**LLM 大脑**：负责理解、推理和生成。是智能体的「思考中枢」，决定下一步做什么。

**工具系统（Tools）**：扩展智能体的能力边界。工具可以是搜索引擎、代码执行器、数据库查询、API 调用等。工具的本质是「函数」，LLM 决定调用哪个工具、传什么参数。

**记忆系统（Memory）**：分为短期记忆（当前对话上下文）和长期记忆（持久化存储，可检索）。短期记忆存在 context window 里，长期记忆通常用向量数据库实现。

**规划模块（Planning）**：将复杂任务分解为子任务，制定执行计划。常见范式有 ReAct、Plan-and-Solve、Tree of Thoughts 等。

**面试点**：工具调用的实现原理——LLM 输出结构化的 JSON（包含工具名和参数），框架解析后执行真实函数，将结果返回给 LLM 继续推理。这个循环叫 Tool Use Loop。

***

### 第三章：HelloAgents 框架设计

HelloAgents 是本课程自研的轻量级智能体框架，核心设计理念是「简单、可扩展、易理解」。

框架的核心抽象：

`HelloAgentsLLM` 封装 LLM 调用，支持 OpenAI、DeepSeek、Qwen 等多种模型，通过环境变量配置 `LLM_PROVIDER`、`LLM_API_KEY`、`LLM_MODEL_ID`。

`BaseTool` 是所有工具的基类，子类只需实现 `run()` 方法和定义 `name`、`description`。

`ToolRegistry` 管理工具的注册与查找，Agent 通过它获取可用工具列表。

`SimpleAgent` 是最基础的 Agent 实现，核心是一个 ReAct 循环：接收用户输入 → LLM 推理 → 判断是否调用工具 → 执行工具 → 将结果反馈给 LLM → 直到得出最终答案。

**面试点**：ReAct（Reasoning + Acting）是最经典的 Agent 范式。每一步 LLM 先输出 Thought（思考），再输出 Action（行动），执行后得到 Observation（观察），循环直到输出 Final Answer。

***

## 第二部分：智能体范式

### 第四章：ReAct 范式

ReAct 是「Reasoning + Acting」的缩写，核心思想是将推理和行动交织在一起。

执行流程：Thought → Action → Observation → Thought → ... → Final Answer。

ReAct 的优势是透明可解释，每一步的思考过程都可见，便于调试。局限是对 LLM 能力要求高，且多轮调用成本较高。

在 HelloAgents 中，SimpleAgent 默认使用 ReAct 范式。LLM 的输出格式被约束为固定模板，框架通过正则解析 Action 和 Action Input，执行对应工具后将 Observation 拼接回 prompt 继续推理。

**面试点**：ReAct 的 prompt 设计关键——需要在 system prompt 中明确告诉 LLM 输出格式（Thought/Action/Action Input/Observation/Final Answer），并提供工具列表和使用示例。

***

### 第五章：Plan-and-Solve 范式

Plan-and-Solve 将任务分为两个阶段：先规划（Plan），再执行（Solve）。

与 ReAct 的区别：ReAct 是「边想边做」，Plan-and-Solve 是「先想清楚再做」。适合任务结构清晰、步骤可预知的场景。

实现方式：第一次 LLM 调用生成完整计划（JSON 格式的步骤列表），然后按步骤逐一执行，每步可以调用工具。

**面试点**：Plan-and-Solve 的优势是减少「中途迷失」的问题，适合长任务；劣势是计划可能不准确，需要处理计划与实际执行的偏差。

***

### 第六章：LangChain 集成

本章介绍如何将 HelloAgents 与 LangChain 生态集成，复用 LangChain 的工具库（如 SerpAPI、Wikipedia、Python REPL 等）。

核心是适配器模式：将 LangChain Tool 包装成 HelloAgents 的 BaseTool，或反向包装。

LangChain 的 `AgentExecutor` 与 HelloAgents 的 `SimpleAgent` 在设计上高度相似，都是 Tool Use Loop 的实现。

**面试点**：LangChain 的核心抽象——Chain（链式调用）、Agent（自主决策）、Memory（记忆）、Tool（工具）。LCEL（LangChain Expression Language）是其声明式编排语法，用 `|` 连接各组件。

***

## 第三部分：工具与记忆

### 第七章：工具系统深度解析

工具系统是智能体能力的核心扩展点。本章深入讲解工具的设计与实现。

**工具定义**：每个工具需要 `name`（唯一标识）、`description`（告诉 LLM 何时使用）、`parameters`（输入参数的 JSON Schema）、`run()` 方法（实际执行逻辑）。description 的质量直接影响 LLM 的工具选择准确率。

**SearchTool 实现**：集成 Tavily 和 SerpApi 两个搜索引擎，支持 `structured` 模式（返回结构化结果）和 `raw` 模式（返回原始文本）。

**ToolRegistry 设计**：工具注册表负责管理所有工具，提供 `register_tool()`、`get_tool(name)`、`list_tools()` 等接口。Agent 在构建 prompt 时从 ToolRegistry 获取工具描述，注入到 system prompt 中。

**SimpleAgent 完整实现**：核心是 `run()` 方法，内部是一个 while 循环，每次迭代调用 LLM，解析输出，执行工具，直到 LLM 输出 Final Answer 或达到最大迭代次数。

**面试点**：工具描述（description）的写法至关重要。好的描述应该说明「什么时候用」「输入什么」「返回什么」，让 LLM 能准确判断是否调用。

***

### 第八章：记忆系统

记忆系统让智能体能够「记住」过去的交互，实现跨会话的连续性。

**WorkingMemory（工作记忆/短期记忆）**：存储当前会话的对话历史，容量有限（`capacity` 参数），超出后自动清理最旧的记录。TTL（Time-To-Live）机制让记忆自动过期。

**EpisodicMemory（情节记忆/长期记忆）**：持久化存储所有交互历史，使用向量数据库（Qdrant）进行语义检索。当用户提问时，先从长期记忆中检索相关历史，注入到 prompt 中。

**MemoryManager**：统一管理两种记忆，提供 `add_interaction()`、`get_context()` 等接口。Agent 在每次调用前先从 MemoryManager 获取相关记忆，构建完整上下文。

**向量检索原理**：将文本转换为向量（Embedding），通过余弦相似度找到语义最相近的历史记录。Qdrant 是一个高性能的向量数据库，支持本地部署。

**面试点**：RAG（Retrieval-Augmented Generation）与记忆系统的关系——长期记忆本质上是一种 RAG，将历史对话作为「知识库」，在需要时检索注入。

***

### 第九章：多智能体通信协议

多智能体系统中，Agent 之间需要通信和协作。本章介绍通信协议的设计。

**消息格式**：统一的消息结构包含 `sender`（发送方）、`receiver`（接收方）、`content`（内容）、`message_type`（消息类型：task/result/status）、`timestamp` 等字段。

**通信模式**：点对点（P2P）直接通信，适合简单的两个 Agent 协作；广播模式，一个 Agent 向所有 Agent 发送消息；通过中间人（Orchestrator）路由，适合复杂的多 Agent 系统。

**MessageBus（消息总线）**：集中式的消息路由组件，Agent 向 MessageBus 发送消息，MessageBus 根据 receiver 字段转发给目标 Agent。解耦了 Agent 之间的直接依赖。

**面试点**：多智能体系统的两种协作模式——「流水线」（Pipeline，Agent A 的输出是 Agent B 的输入，顺序执行）和「并行」（多个 Agent 同时处理不同子任务，最后汇总）。

***

## 第四部分：进阶技术

### 第十章：强化学习与智能体训练

本章介绍如何用强化学习（RL）训练智能体，使其在特定任务上表现更好。

**RLHF（基于人类反馈的强化学习）**：GPT-4、Claude 等模型都使用了 RLHF。核心步骤是：收集人类偏好数据 → 训练奖励模型（Reward Model）→ 用 PPO 算法优化 LLM。

**GRPO（Group Relative Policy Optimization）**：DeepSeek-R1 使用的训练方法，不需要单独的奖励模型，通过组内相对比较来计算奖励，更高效。

**在 HelloAgents 中的应用**：通过收集 Agent 的执行轨迹（trajectory），标注哪些决策是好的，用这些数据微调 LLM，使 Agent 在特定任务上的工具选择和推理更准确。

**面试点**：RL 训练 Agent 的核心挑战——奖励函数的设计（如何定义「好的」Agent 行为）、稀疏奖励问题（任务完成才有奖励，中间步骤难以评估）、探索与利用的平衡。

***

### 第十一章：智能体评估

评估是智能体开发中最容易被忽视但至关重要的环节。

**评估维度**：任务完成率（最终答案是否正确）、工具调用准确率（是否选择了正确的工具）、效率（完成任务所需的步骤数）、鲁棒性（面对异常输入的表现）。

**评估数据集构建**：需要覆盖不同难度、不同类型的任务。每个测试用例包含输入、期望输出、评分标准。

**自动评估 vs 人工评估**：对于有明确答案的任务（如数学计算、代码执行），可以自动评估；对于开放性任务（如写作、分析），需要 LLM-as-Judge 或人工评估。

**LLM-as-Judge**：用一个强大的 LLM（如 GPT-4）来评估另一个 Agent 的输出质量，给出分数和理由。成本低于人工评估，但存在偏见问题。

**面试点**：评估 Agent 的核心指标——Pass\@k（k 次尝试中至少一次成功的概率）、轨迹准确率（每一步决策是否正确）、端到端成功率。

***

### 第十二章：上下文工程

上下文工程（Context Engineering）是指精心设计输入给 LLM 的上下文，以获得最佳输出。

**Prompt 工程的局限**：传统 Prompt 工程关注单次调用的输入设计，而上下文工程关注整个 Agent 运行过程中的信息管理。

**上下文的组成**：系统提示（System Prompt，定义 Agent 角色和行为规范）、工具描述（让 LLM 知道有哪些工具可用）、历史记忆（相关的历史交互）、当前任务（用户的具体请求）、中间结果（已执行步骤的输出）。

**上下文压缩**：当上下文过长时，需要压缩。策略包括：截断（保留最近的 N 条）、摘要（用 LLM 对历史对话做摘要）、选择性保留（只保留与当前任务相关的内容）。

**动态上下文管理**：根据任务的不同阶段，动态调整注入的上下文内容。例如，在规划阶段注入更多背景信息，在执行阶段注入工具使用示例。

**面试点**：Context Window 的限制是 Agent 设计的核心约束。如何在有限的 token 预算内放入最有价值的信息，是上下文工程的核心问题。常见策略：RAG 检索相关内容、摘要压缩历史、优先级排序。

***

### 第十三章：智能旅行助手（实战项目一）

本章通过构建一个完整的旅行规划助手，综合运用前面所学的知识。

**系统架构**：前后端分离，前端用 Vue3 + TypeScript，后端用 FastAPI，智能体层用 HelloAgents。

**多智能体设计**：系统包含三个专门的 Agent——景点推荐 Agent（负责搜索和推荐景点）、行程规划 Agent（负责安排时间和路线）、预算估算 Agent（负责计算费用）。三个 Agent 通过 Orchestrator 协调，顺序执行。

**工具集成**：集成了搜索工具（获取景点信息）、地图工具（计算距离和路线）、天气工具（查询目的地天气）。

**SSE（Server-Sent Events）流式输出**：后端通过 SSE 将 Agent 的执行过程实时推送到前端，用户可以看到 Agent 的思考过程和中间结果，提升体验。

**面试点**：多 Agent 系统的 Orchestrator 模式——一个主 Agent 负责任务分解和协调，子 Agent 负责具体执行。Orchestrator 需要处理子 Agent 失败的情况（重试、降级、跳过）。

***

## 第五部分：实战项目

### 第十四章：自动化深度研究智能体（实战项目二）

本章构建一个能够自动执行深度研究任务的智能体，核心创新是「TODO 驱动的研究范式」。

**TODO 驱动研究范式**：将复杂研究主题分解为 3-5 个子任务（TODO），每个子任务包含 title（标题）、intent（研究意图）、query（搜索查询）。执行流程是「规划 → 执行 → 整合」三阶段。

**三个专门 Agent**：

TODO Planner（研究规划专家）：将研究主题分解为子任务，输出 JSON 格式的任务列表。Prompt 设计关键是包含当前日期、明确要求 JSON 格式、提供示例输出。

Task Summarizer（任务总结专家）：对每个子任务的搜索结果进行总结，提取核心观点、关键数据，并为每个观点添加来源引用。

Report Writer（报告撰写专家）：整合所有子任务的总结，生成结构化的 Markdown 报告，包含标题、概述、详细分析、总结、参考文献。

**ToolAwareSimpleAgent**：在 SimpleAgent 基础上增加 `tool_call_listener` 回调，每次工具调用时触发，用于记录日志和实时推送进度到前端。

**SearchTool 扩展**：新增 DuckDuckGo、Perplexity、SearXNG 等搜索引擎，支持 Advanced 模式（组合多个搜索引擎）。搜索结果需要去重（按 URL 去重）。

**面试点**：深度研究 Agent 的核心挑战——信息去重（多个搜索结果可能包含相同内容）、来源可信度评估、知识空白识别（当前搜索结果不足以回答问题时，需要继续搜索）。

***

### 第十五章：构建赛博小镇（实战项目三）

本章将智能体技术与游戏引擎结合，构建一个 AI 驱动的 2D 像素风格小镇。

**技术架构**：Godot 4.5 游戏引擎（前端）+ FastAPI（后端）+ HelloAgents（智能体层）+ Qdrant（向量数据库）+ SQLite（关系数据库）。

**NPC 智能体系统**：每个 NPC 是一个独立的 SimpleAgent 实例，拥有独特的系统提示词（定义角色、职业、性格）和独立的记忆系统。三个 NPC 分别是张三（Python 工程师，严谨专业）、李四（产品经理，外向善于沟通）、王五（UI 设计师，温和富有创意）。

**记忆系统**：WorkingMemory（短期记忆，容量 10 条，TTL 120 分钟）+ EpisodicMemory（长期记忆，SQLite + Qdrant 向量检索）。对话时先从短期记忆获取最近对话，再从长期记忆检索相关历史，一起注入 LLM。

**好感度系统**：五级好感度（陌生 0-20、熟悉 21-40、友好 41-60、亲密 61-80、挚友 81-100）。每次对话后，用 LLM 分析玩家态度（友好 +5、中立 +2、不友好 -3），动态更新好感度。好感度影响 NPC 的系统提示词，从而改变回复风格。

**批量对话生成（轻负载模式）**：将多个 NPC 的背景对话合并为一次 LLM 调用，要求 LLM 以 JSON 格式一次性返回所有 NPC 的对话，成本降低到原来的 1/3。适用于 NPC 背景对话、定时更新、场景氛围营造。

**混合模式**：后台定期批量生成 NPC 背景对话（缓存），玩家主动交互时切换为即时响应模式（调用专属 Agent）。

**面试点**：AI NPC 的核心挑战——成本控制（每次对话调用 LLM API）、延迟（LLM 推理时间）、内容可控性（LLM 输出不完全可控，需要 Prompt 约束和内容过滤）。批量生成是降低成本的有效手段。

***

### 第十六章：毕业设计

本章指导学习者构建属于自己的多智能体应用，并通过 GitHub PR 提交到 Hello-Agents 的共创项目仓库（`Co-creation-projects` 目录）。

**项目要求**：可运行的 Jupyter Notebook 或 Python 脚本、`requirements.txt`、`README.md`。项目命名格式为 `{GitHub用户名}-{项目名称}`。

**推荐选题方向**：生产力工具（代码审查、文档生成、会议助手）、学习辅助（学习伙伴、论文助手、编程导师）、创意娱乐（故事生成、游戏 NPC、菜谱助手）、数据分析（数据分析师、舆情监控、竞品分析）、生活服务（健康助手、理财助手、购物助手）。

**提交流程**：Fork 仓库 → 创建开发分支 → 在 `Co-creation-projects` 目录下创建项目文件夹 → 开发完成后提交 PR → 响应 Review 意见 → 合并。

**PR 标题格式**：`[毕业设计] 项目名称 - 简短描述`。

***

## 核心概念速查

**ReAct**：Reasoning + Acting，最经典的 Agent 范式。Thought → Action → Observation 循环，直到 Final Answer。

**Tool Use Loop**：LLM 输出结构化 JSON（工具名 + 参数）→ 框架执行工具 → 结果返回 LLM → 继续推理。

**RAG**：Retrieval-Augmented Generation，检索增强生成。将外部知识库的相关内容检索出来，注入 LLM 的上下文。

**Orchestrator 模式**：主 Agent 负责任务分解和协调，子 Agent 负责具体执行。适合复杂的多 Agent 系统。

**TODO 驱动研究**：将复杂研究主题分解为 3-5 个子任务，「规划 → 执行 → 整合」三阶段。

**上下文工程**：在有限的 Context Window 内，精心管理注入 LLM 的信息，包括系统提示、工具描述、历史记忆、当前任务。

**批量生成**：将多个 Agent 的请求合并为一次 LLM 调用，降低成本和延迟。

**好感度系统**：用 LLM 分析对话情感，动态调整 NPC 状态，影响后续交互风格。