# 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 状态，影响后续交互风格。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://gists.lanlance.cn/cssys/agent101.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.