面向小白，从零到能独立开发一个可用 Agent 的完整路线。预计 8-12 周。

---

一、先搞清楚：什么是 AI Agent

一句话定义：AI Agent（智能体）是一个能自主感知环境、做出决策、执行行动来完成目标的 AI 系统。

和普通 LLM 聊天机器人的关键区别：

	普通 ChatBot	AI Agent
交互方式	一问一答，被动响应	自主规划，主动执行
能力边界	只生成文本	调用工具、操作外部系统
记忆	单次对话上下文	短期 + 长期记忆
任务复杂度	单步任务	多步推理、拆解、执行

核心公式：Agent = LLM + 规划能力 + 工具使用 + 记忆系统

这四块拼图会在第三章逐一展开。

---

二、前置知识（第 1-2 周）

2.1 Python 基础

你需要能无痛读懂和编写以下代码：

# 异步编程 —— Agent 框架几乎全是 async
import asyncio
from typing import TypedDict, Literal, Annotated
​
async def call_llm(prompt: str) -> str:
    await asyncio.sleep(1)  # 模拟 API 调用
    return f"Response to: {prompt}"
​
# Pydantic 模型 —— 定义工具参数、结构化输出的标配
from pydantic import BaseModel, Field
​
class SearchToolInput(BaseModel):
    query: str = Field(description="搜索关键词")
    max_results: int = Field(default=5, description="最多返回条数")

建议花两天过一遍 Python 官方教程 的 async/await 和类型注解部分，然后读一下 Pydantic 文档 的 quickstart。

2.2 LLM 基础概念

你必须用自己的话解释清楚这些词，否则看任何 Agent 文档都会有盲区：

概念	一句话解释	为什么重要
Token	LLM 的计价和上下文计量单位	决定成本和能塞多少信息
Context Window	单次请求能容纳的最大 token 数	太大的任务要拆分，太小记不住
Temperature	0=每次输出一致，1=发散有创造	Agent 推理用低温，创意任务用高温
System Prompt	给 LLM 的角色设定和规则	Agent 的"人设"和约束都在这
Function Calling	LLM 不生成文本，而是返回"调用哪个函数+什么参数"	这是 Agent 的"手"
RAG	检索外部知识 → 塞进 prompt → 增强回答	Agent 不能只靠训练数据

动手：花一个下午跑通 OpenAI 或 Anthropic 官方 quickstart，感受一下 API 调用的基本流程。

2.3 Prompt Engineering 入门

Agent 开发中，优化 prompt 的性价比远高于改代码。

三个你必须掌握的技巧：

# 1. 结构化 Prompt —— 不要让 LLM 猜你的意图
SYSTEM_PROMPT = """你是一个技术调研助手。
## 规则
- 每次搜索前先说明搜索意图
- 搜索结果为空时，换关键词重试，最多 3 次
- 最终输出使用 Markdown 格式，包含引用来源
## 输出格式
1. 概述（≤200字）
2. 核心发现（3-5 条）
3. 详细分析
4. 参考链接
"""
​
# 2. Few-shot —— 给示例，LLM 照着学
FEW_SHOT_EXAMPLE = """
用户：帮我查一下 Python 3.13 的新特性
正确流程：
1. 先搜索 "Python 3.13 new features 2025"
2. 找到官方文档和权威博客
3. 按类别整理（语法、性能、标准库）
4. 每个特性附上代码示例
"""
​
# 3. Chain of Thought —— 让 LLM 把思考过程写出来
COT_PROMPT = "解决这个问题。先写出你的分析步骤，再逐步执行，最后给出答案。"

推荐阅读：Anthropic Prompt Engineering Guide

---

三、Agent 核心概念深入（第 3-4 周）

这是整个学习路线最重要的部分。框架会变，这四块不变。

3.1 规划（Planning）—— Agent 的"大脑"

ReAct 模式（必学）

最经典的 Agent 模式，核心循环：

用户输入 → Thought(思考) → Action(行动) → Observation(观察结果) → Thought → ... → Final Answer

用纯 Python 手写一个 ReAct 循环，这是理解 Agent 本质最快的方式——不需要任何框架：

import json
from openai import OpenAI
​
client = OpenAI()
​
# 定义工具
def search(query: str) -> str:
    """模拟搜索引擎"""
    return f'搜索结果：关于"{query}"找到 3 条相关内容...'
​
def calculate(expression: str) -> str:
    """计算器"""
    return str(eval(expression))
​
TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "search",
            "description": "搜索互联网获取信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "搜索关键词"}
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "计算数学表达式",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string", "description": "数学表达式，如 '3*15'"}
                },
                "required": ["expression"]
            }
        }
    }
]
​
TOOL_MAP = {"search": search, "calculate": calculate}
​
def run_agent(user_query: str, max_steps: int = 10) -> str:
    messages = [{"role": "user", "content": user_query}]
​
    for step in range(max_steps):
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            tools=TOOLS,
            tool_choice="auto",
        )
        msg = response.choices[0].message
​
        # 没有工具调用 → 最终回答
        if not msg.tool_calls:
            return msg.content
​
        # 执行工具调用
        for tool_call in msg.tool_calls:
            name = tool_call.function.name
            args = json.loads(tool_call.function.arguments)
            result = TOOL_MAP[name](**args)
​
            messages.append({"role": "assistant", "tool_calls": [tool_call]})
            messages.append({"role": "tool", "tool_call_id": tool_call.id, "content": result})
​
    return "达到最大步数限制"
​
# 运行
print(run_agent("2024年诺贝尔物理学奖得主是谁？用中文回答"))

写这个 50 行的循环，比看 500 页框架文档更有用。 你写完就明白：Agent 不是什么魔法，就是一个 while 循环里 LLM 决定下一步干什么。

Plan-and-Execute（了解）

先出完整计划，再逐步执行。适合任务步骤可预见、不需要动态调整的场景。LangGraph 有内置实现。

Reflection（进阶）

让 Agent 在执行后自我审视："我刚才的搜索关键词对吗？结果够全面吗？要不要再搜一轮？" 这是提升 Agent 质量最有效的手段之一。

3.2 工具使用（Tool Use）—— Agent 的"手"

几个关键认知：

1. 工具的描述是给 LLM 看的，不是给你看的

# ❌ 差 —— LLM 不知道该什么时候用
def query_db(sql: str): ...
​
# ✅ 好 —— LLM 知道用途、知道参数含义、知道什么场景调用
def query_database(
    sql: str = Field(description="要执行的 SELECT 语句，仅支持只读查询")
) -> list[dict]:
    """查询 MySQL 数据库。用于获取订单、用户、库存等业务数据。
    仅支持 SELECT，不支持 INSERT/UPDATE/DELETE。"""

2. 工具设计原则

• 单一职责：一个工具做好一件事

• 返回自然语言：别把数据库原始错误堆栈抛给 LLM，它会开始"幻觉"

• 设定边界：文件操作限制目录，网络请求限制域名，数据库操作限制只读

3. 常见工具类型

• 知识获取：搜索 API、数据库查询、RAG 检索

• 执行操作：发送邮件、创建工单、调用 API

• 代码执行：Python REPL、Shell（一定要沙箱化）

• 文件操作：读写本地/远程文件

3.3 记忆系统（Memory）

短期记忆（上下文窗口） → 长期记忆（向量数据库） → 工作记忆（任务状态）
     128K tokens               百万级文档                  Redis/DB

类型	存储	用途	示例
短期记忆	对话历史 list	当前任务上下文	"你刚才说的是哪个客户？"
长期记忆	向量数据库（Chroma/Pinecone）	跨会话知识	"我记得你喜欢简洁的回答风格"
工作记忆	Redis / 数据库	长任务状态追踪	多步任务做到第几步了

3.4 多 Agent 协作

单 Agent 能搞定的事，不要上多 Agent。 多加一个 Agent 就多一层延迟、多一层出错可能、多一倍 token 消耗。

但以下场景多 Agent 有真实价值：

• 角色分离：安全审查 ≠ 性能审查，用不同的 system prompt 和工具

• 并行加速：多个 Agent 同时干互不依赖的子任务

• 交叉验证：两个 Agent 独立分析，取共识（投票、辩论）

常见模式：Router → [Researcher, Analyst, Coder] → Aggregator

---

四、框架实战（第 5-7 周）

4.1 框架选型决策树

你现在的需求是什么？
│
├─ 学核心概念，做 Demo        → LangChain（生态最大，教程最多）
├─ 构建复杂多步 Agent          → LangGraph（状态图，循环+分支+人工介入）
├─ 快速搭多 Agent 协作         → CrewAI（角色扮演，开箱即用）
├─ 微软技术栈 / 企业复杂协作   → AutoGen
├─ 做 SaaS 产品                → Agno（原 phidata，Agent+DB+UI 一站式）
└─ 比框架好的轻量需求         → 纯 OpenAI SDK + 手写循环

4.2 LangChain + LangGraph（主学，2-3 周）

LangChain 是 Agent 界的"Spring Boot"。LangGraph 是 LangChain 生态里做复杂 Agent 的标准方案。

学习路径（按顺序，不要跳）：

步骤	内容	产出
1	LangChain ChatModel + PromptTemplate + Chain	跑通一条简单链
2	Tool 定义 + AgentExecutor	一个 ReAct Agent
3	转 LangGraph：StateGraph + Node + Edge	理解状态图编程
4	LangGraph 加入条件分支 + 循环	Agent 能根据结果决定下一步
5	Checkpointer 持久化	对话断点续跑
6	Human-in-the-loop（中断 + 人工审批）	危险操作需要确认

# LangGraph 核心概念速览
from langgraph.graph import StateGraph, END
from typing import TypedDict
​
class AgentState(TypedDict):
    messages: list
    next_step: str
​
graph = StateGraph(AgentState)
​
# 添加节点
graph.add_node("think", think_node)      # LLM 推理
graph.add_node("act", act_node)          # 执行工具
graph.add_node("reflect", reflect_node)  # 自我反思
​
# 添加边（控制流）
graph.add_edge("think", "act")
graph.add_conditional_edges("act", decide_next, {
    "continue": "think",   # 继续推理
    "reflect": "reflect",  # 先反思
    "finish": END          # 结束
})

4.3 至少上手一个其他框架（1 周）

用一个相同的项目（比如"技术调研助手"）在不同框架实现一遍，对比 DX：

框架	上手难度	适用场景	一句话评价
CrewAI	⭐	角色分工明确的多 Agent 协作	最像写剧本，define role → task → crew
AutoGen	⭐⭐	微软生态、复杂 Agent 对话	强大的多 Agent 对话，学习曲线抖
Agno	⭐	SaaS 快速搭建	Agent + RAG + UI 一站式，适合创业验证
OpenAI Agents SDK	⭐	深度绑定 OpenAI	原生支持 Swarm、Tracing、Guardrails

4.4 MCP（Model Context Protocol）—— 工具调用的 USB-C（3-5 天）

MCP 是 Anthropic 提出的开放协议，解决 Agent → 工具之间的连接标准。一次编写 MCP Server，所有支持 MCP 的 Agent 都能用。

架构：Agent(Client) ←→ MCP Server ←→ 外部系统（数据库、API、文件）

# 搭建一个最简单的 MCP Server
from mcp.server import Server, stdio_server
from mcp.types import Tool, TextContent
​
server = Server("my-tools")
​
@server.tool()
async def get_weather(city: str) -> str:
    """获取城市天气"""
    return f"{city}：晴，25°C"
​
async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write)

练习步骤：

1. 用 MCP SDK 写一个 Server，暴露 2-3 个工具

2. 在 Claude Desktop 或自己写的 Agent 中接入

3. 浏览 MCP 官方 Hub，看社区已有的 Server 是怎么写的

---

五、渐进式动手项目（第 8-12 周）

核心原则：每个项目先跑通最简 MVP，再逐步加功能。不要一开始就追求完美。

项目 1：命令行 Todo Agent（3-5 天）

目标：手写 ReAct 循环，理解 Agent 本质。

# 验收标准：以下输入都能正确处理
"明天下午3点提醒我开会"                    → add_todo("开会", "2026-06-20 15:00")
"我有哪些没完成的待办？"                   → list_todos(status="pending")
"把'买水果'标记为完成"                     → complete_todo("买水果")
"帮我看看下周有哪些事，按优先级排个序"      → list_todos + 排序逻辑

• 技术：纯 Python + OpenAI/Anthropic SDK，不用任何 Agent 框架

• 工具：add_todo, list_todos, complete_todo, delete_todo

• 关键：自己写 Tool Call 的解析和调度逻辑

项目 2：个人知识库问答 Agent（1 周）

目标：掌握 RAG 全流程。

文档上传 → PDF/Word/Markdown 解析 → 智能切片 → 
文本向量化（Embedding）→ 存入向量数据库 → 
用户提问 → 检索相关片段 → 拼入 Prompt → LLM 生成回答（附引用来源）

• 技术：LangChain + ChromaDB + OpenAI Embeddings

• 关键决策点：

  • 切片大小（chunk_size）和重叠（overlap）：太大检索不准，太小丢失上下文，512-1024 tokens 是常见起点

  • 用什么解析文档：PyPDF/Unstructured/Marker，中文文档注意编码

• 验收：上传 10 份技术文档，能准确回答并指出引用来源

项目 3：自动化技术调研 Agent（1-2 周）

目标：多步规划 + 工具编排 + 结构化输出。

用户输入主题
  → Planner: 制定搜索计划（3-5 个维度）
  → Searcher: 依次搜索每个维度
  → Analyzer: 分析搜索结果，提取关键信息
  → Writer: 生成结构化 Markdown 报告
  → Reflector: 自检（信息全不全？逻辑通不通？）→ 补充搜索或直接输出

• 技术：LangGraph + Tavily Search API / SerpAPI

• 关键实现：

  • 每个节点独立的状态管理

  • 条件边：搜索结果为空 → 换关键词重试；相关性低 → 调整搜索策略

  • 最终输出包含：概述、核心发现、详细分析、对比表格、参考链接

• 验收：输入"Python 异步编程最佳实践 2025"，产出一份像人写的调研报告

项目 4：代码审查 Agent（2-3 周）

目标：多 Agent 协作 + 外部 API 集成。

GitHub PR
  → Security Agent（检查 SQL 注入、XSS、密钥泄露）
  → Performance Agent（检查 N+1 查询、不必要的循环、阻塞操作）
  → Style Agent（检查命名、函数长度、复杂度）
  → Aggregator（汇总、去重、排序、生成 Review 报告）

• 技术：CrewAI + GitHub API + AST 分析（ast 模块）

• 关键设计：每个 Agent 用不同的 system prompt 和专用工具

• 验收：对真实开源项目 PR 输出有参考价值的审查意见

项目 5（进阶）：你自己的 Agent 产品

选一个日常真实痛点，完整经历：需求分析 → 架构设计 → 选框架 → 实现 → 评估 → 优化。这是从"学 Agent"到"做 Agent"的关键跨越。

---

六、Agent 评估与调试

开发 Agent 最痛苦的不是写代码，而是你不知道它为什么做错了。

6.1 评估维度

维度	衡量方式	工具
任务完成率	端到端测试集，统计成功率	手写 eval + pytest
工具选择准确率	单步工具调用是否选对了	LangSmith / LangFuse trace 分析
Token 消耗	每次任务的 token 用量和费用	框架内置 tracing + 自建看板
延迟	端到端耗时 + 各环节耗时分布	LangFuse / 自建埋点
幻觉率	输出中事实性错误的比例	RAGAS 框架 / 人工抽查

6.2 调试技巧

1. 打 trace，别打 print。LangSmith / LangFuse 让你看到每一步 LLM 的输入输出、工具调用、状态变化

2. 降低 temperature 先跑通逻辑。temperature=0 时行为是确定性的，方便复现和调试

3. 从最简单的 case 开始。比如 Todo Agent 先测单步命令，再测多步对话

4. tool 返回加前缀。如 [工具返回] 搜索成功，找到 3 条结果：... 而不是直接把 JSON dump 给 LLM

5. 如果 Agent 反复调同一个工具，检查你的 stop condition 和工具返回信息是否足够让 LLM 判断"够了"

---

七、进阶方向

7.1 Agent 安全

• Prompt 注入防护（用户输入"忽略之前的指令..."）

• 工具最小权限原则（文件读写限制目录、SQL 限制只读、Shell 沙箱化）

• 人工审批节点（花钱、发邮件、删除数据等操作必须 Human-in-the-loop）

7.2 生产化架构

• SSE/WebSocket 流式推送 Agent 实时进度（用户等不了 30 秒无响应）

• Agent 状态存入数据库（服务重启不丢长任务）

• 队列 + Worker 处理并发 Agent 任务（Celery / ARQ）

• Token 用量监控 + 费用预警

7.3 前沿方向

• Computer Use：Agent 操控浏览器/桌面（Claude Computer Use、Browserbase）

• Coding Agent：写代码 → 执行 → 看报错 → 修复的闭环（Claude Code、Cline）

• MCP 生态：把你的 Agent 接入 MCP 网络，复用社区成百上千的工具

• Agent 工作流引擎：Temporal / Prefect 编排长时间运行的 Agent 任务

---

八、学习资源

必读（按优先级）

1. Anthropic - Building Effective Agents —— Agent 设计圣经，讲的是理念而不是框架

2. Lilian Weng - LLM Powered Autonomous Agents —— 经典综述，把 Planning/Memory/Tool Use 讲透了

3. LangGraph 官方教程 —— 最好的 Agent 框架入门材料

4. MCP 官方文档 —— 工具调用标准协议

框架仓库

• LangGraph + CrewAI + AutoGen

• Agno + OpenAI Agents SDK

追踪/评估

• LangSmith + LangFuse（开源）

社区

• LangChain Discord、Anthropic Discord

• X(Twitter) 关注 @hwchase17 (LangChain 创始人)、@_akhaliq（AI 论文速递）

---

九、避坑指南

1. 不要一上来就学框架。先用纯 API 手写一个 ReAct 循环。你写的那 50 行代码，比 500 页框架文档更有价值。

2. Agent 不总是答案。能用 if-else / 正则 / 固定脚本解决的，别上 Agent。Agent 贵、慢、不稳定。

3. Prompt 是第一武器。很多时候加一堆复杂逻辑不如优化一段 prompt。先改 prompt，再改代码。

4. 设硬上限：最大步数 + 总超时。Agent 最常见的问题是无止境地"再搜一次"，必须双重保护。

5. 工具异常要吞掉。把数据库报错堆栈直接扔给 LLM，它会开始"幻觉"编数据。catch 所有异常，返回干净的描述。

6. 从最简 MVP 开始。不要第一次就设计一个带 5 个 Agent、20 个工具的"通用平台"。做一个能做一件事的 Agent，跑通了再加。

7. 关注 token 成本。Agent 循环会让成本指数放大。一个"技术调研"任务跑掉 $2-5 很正常。用便宜模型做简单步骤，用强模型做关键推理。

---

十、学习节奏总表

周	阶段	核心内容	产出
1	LLM 基础	Python 异步 + Token/Prompt 概念 + API quickstart	跑通第一次 API 调用
2	Prompt 工程	结构化 Prompt + Few-shot + CoT	能写出高质量的 system prompt
3	核心概念	ReAct + Tool Use + 手写 Agent 循环	不依赖框架的纯 Python Agent
4	核心概念	Memory + 多 Agent 概念 + MCP 初识	理解完整 Agent 架构
5-6	LangGraph	StateGraph → Tool → Checkpointer → HITL	能用 LangGraph 构建复杂 Agent
7	框架拓展	任选 1 个其他框架对比 + MCP 实践	建立框架选型判断力
8-9	项目 1+2	Todo Agent + 知识库 RAG	两个完整可运行的项目
10-11	项目 3+4	技术调研 Agent + 代码审查 Agent	多步规划和多 Agent 协作实战
12	自主项目	选自己的真实痛点，从零做一个 Agent	跨越"学"到"做"的鸿沟

---

最后的话：Agent 开发处在 2024-2026 的爆发期，框架和最佳实践每周都在变。这篇文档的核心不是让你记住框架 API，而是理解 ReAct 循环 + Tool Use + Memory 这三个元概念。

掌握这三个，你能在半天内上手任何一个新框架。追逐框架不如追逐原理。