📋 AI Agent 学习路线验收标准文档

本文档详细说明每个练习项目的验收标准、验证方法和预期结果。

📅 Day 1：异步编程核心

练习项目：异步批量调用多个 API（模拟 Agent 多工具并发调用）

✅ 验收标准（6 条）

总分：100 分 - 80-100 分：✅ 验收通过，继续 Day 2 - 60-79 分：⚠️ 基本通过，但有改进空间 - 60 分以下：❌ 未通过，需要重做

🔍 验收方式

# 方式 1：自动验收脚本（推荐）
python day01_practice_validator.py

# 方式 2：手动运行你的练习代码
python your_file.py
# 观察输出：异步总耗时应明显小于同步总耗时

📊 预期性能指标

💡 完整标准答案

参考文件 tutorial_02_async.py（运行它跟着学）

📅 Day 2：类型系统与装饰器进阶

练习项目：用 Pydantic 定义 Tool Schema，并用装饰器实现工具注册机制

✅ 验收标准（8 条）

总分：100 分 - 80-100 分：✅ 验收通过 - 60-79 分：⚠️ 基本通过 - 60 分以下：❌ 未通过

🔍 验收方式

# 自动验收脚本
python day02_practice_validator.py

# 指定文件
python day02_practice_validator.py --file my_practice.py

💡 关键检查点

# ✅ 正确的装饰器写法
def 工具(名称, 描述):
    def 装饰器(func):
        @functools.wraps(func)   # ← 必须有！
        def 包装(**kwargs):
            # 输入验证
            输入 = 输入模型(**kwargs)
            # 调用原函数
            结果 = func(**输入.model_dump())
            # 输出验证
            return 输出模型(**结果)
        # 注册
        工具注册表[名称] = {"函数": 包装, "描述": 描述}
        return 包装
    return 装饰器

💡 完整标准答案

参考文件 tutorial_01_decorators.py（第 8 步：AI Agent 实战）

📅 Day 3：生成器、迭代器与上下文管理器

练习项目：实现一个流式 LLM 响应的异步生成器包装器

✅ 验收标准（8 条）

总分：100 分

🔍 验收方式

python day03_practice_validator.py

💡 关键代码示例

# 异步生成器（核心）
async def 流式输出(提示词: str) -> AsyncGenerator[str, None]:
    for chunk in ["我", "喜欢", "写代码"]:
        await asyncio.sleep(0.2)   # 模拟延迟
        yield chunk                     # ← 多次 yield

# 使用
async for chunk in 流式输出("Hello"):
    print(chunk, end="")

📅 Day 4：LLM API 调用与 Prompt 工程

练习项目：实现支持 Function Calling 的 LLM 客户端

✅ 验收标准

🔍 验收方式

# 需要有 API Key 才能完整测试
# 可以先用 mock 模式测试逻辑

python your_day04_practice.py
# 预期：LLM 会选择调用工具 → 执行工具 → LLM 根据结果生成最终回答

💡 关键流程

用户提问
  ↓
构造 messages + tools，调用 LLM API
  ↓
LLM 返回 tool_calls？（是/否）
  ├─ 是 → 解析 tool_calls → 执行对应函数 → 结果追加到 messages → 再次调用 LLM
  └─ 否 → 返回最终回答

📅 Day 5：阶段一实战——命令行 AI 助手

练习项目：综合练习，集成异步 + Pydantic + Function Calling + 流式输出

✅ 验收标准（手动检查清单）

• [ ] 用户在命令行输入自然语言，程序能理解意图
• [ ] 支持至少 2 个工具调用（如：计算器、天气查询）
• [ ] 工具调用使用 Function Calling 机制（不是关键词匹配）
• [ ] 异步并发处理多个工具调用（asyncio.gather）
• [ ] LLM 响应支持流式输出（yield chunk by chunk）
• [ ] 所有数据结构用 Pydantic 定义
• [ ] 有基本的错误处理（API 失败、工具执行失败）
• [ ] 代码有类型注解

🔍 验收方式

# 运行命令行助手
python your_cli_agent.py

# 测试对话
> 帮我计算 3 + 5 * 2
# 预期：Agent 调用计算器工具，返回 13

> 北京今天天气怎么样？
# 预期：Agent 调用天气查询工具，返回天气信息

📅 Day 6：Agent 架构原理（核心！）

练习项目：不依赖框架，纯 Python 手写一个 ReAct Agent 循环

✅ 验收标准（8 条）

总分：100 分

🔍 验收方式

python day06_practice_validator.py

💡 ReAct 循环伪代码

async def react_agent(user_input: str, max_steps: int = 10):
    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
    messages.append({"role": "user", "content": user_input})

    for step in range(max_steps):
        # 1. 调用 LLM
        response = await llm_chat(messages)

        # 2. 解析响应
        thought, action, action_input = parse_react_response(response)

        # 3. 如果是 Final Answer，返回
        if not action:
            return action_input  # 最终答案

        # 4. 执行工具
        observation = await execute_tool(action, action_input)

        # 5. 把结果加入 messages
        messages.append({"role": "assistant", "content": response})
        messages.append({"role": "user", "content": f"Observation: {observation}"})

    return "达到最大步数限制"

📅 Day 7：LangGraph 入门

练习项目：用 LangGraph 实现带条件分支的 ReAct Agent

✅ 验收标准（手动检查清单）

• [ ] 使用 StateGraph 定义 Agent 状态
• [ ] 定义了至少 2 个 Node（如：call_model、call_tool）
• [ ] 定义了 Edge（如：call_model → call_tool 或 END）
• [ ] 使用了 add_conditional_edges（条件路由）
• [ ] State 类型用 TypedDict 或 Pydantic 模型定义
• [ ] Agent 能完成多步推理（和 Day 6 功能相同，但用 LangGraph 实现）
• [ ] 代码可运行

🔍 验收方式

python your_day07_practice.py

# 预期输出类似 Day 6，但内部是用 LangGraph 驱动的

💡 关键代码框架

from langgraph.graph import StateGraph, END

class AgentState(TypedDict):
    messages: list
    # 其他状态字段

graph = StateGraph(AgentState)
graph.add_node("call_model", call_model)
graph.add_node("call_tool", call_tool)
graph.add_conditional_edges("call_model", should_continue)
graph.add_edge("call_tool", "call_model")

📅 Day 8：工具系统与 MCP 协议

练习项目：写一个简单的 MCP Server，在 Agent 中调用

✅ 验收标准（手动检查清单）

• [ ] 使用 mcp Python SDK 创建 MCP Server
• [ ] 定义了至少 2 个 Tool（用 @server.tool() 装饰器）
• [ ] Tool 有清晰的 name、description、inputSchema
• [ ] MCP Server 能独立启动（用 mcp run 或代码启动）
• [ ] Agent 能连接到 MCP Server 并列出工具
• [ ] Agent 能调用 MCP 工具并获取结果
• [ ] 工具函数有超时控制

🔍 验收方式

# 终端 1：启动 MCP Server
mcp run your_mcp_server.py

# 终端 2：运行 Agent（连接到 MCP Server）
python your_day08_agent.py

📅 Day 9：记忆系统与 RAG

练习项目：实现能记住对话历史、并能从文档库检索知识的 Agent

✅ 验收标准（手动检查清单）

• [ ] 实现了短期记忆（最近 N 轮对话历史）
• [ ] 对话历史超出限制时，有裁剪/压缩策略（滑动窗口或摘要）
• [ ] 实现了长期记忆（向量存储，如 ChromaDB/FAISS）
• [ ] 能对新输入做向量检索，找到相关历史记忆
• [ ] RAG：能从文档库检索相关知识，注入到 Prompt
• [ ] Embedding 使用合理（中文用 bge-large-zh 或 OpenAI embedding）
• [ ] 多轮对话测试：Agent 能"记住"之前说过的话

🔍 验收方式

python your_day09_agent.py

# 测试多轮对话
> 我叫张三
✅ Agent：你好张三！

> 我叫什么名字？
✅ Agent：你叫张三。（从对话历史检索到）

📅 Day 10：阶段二实战——多工具 Agent

练习项目：用 LangGraph 构建多工具 Agent

✅ 验收标准（手动检查清单）

• [ ] 集成了至少 4 个工具（计算器、网页搜索、文件读写、代码执行）
• [ ] 使用 LangGraph 的 ToolNode 或手写的工具执行节点
• [ ] ReAct 循环 + 条件路由（继续推理 or 调用工具 or 结束）
• [ ] 对话记忆：短期（最近 10 轮）+ 长期（向量存储）
• [ ] 流式输出（用 astream_events() 或类似方法）
• [ ] 错误恢复：工具调用失败自动重试或降级
• [ ] Token 消耗有记录（每次 LLM 调用记录 token 数）

📅 Day 11-15：完整项目实战

项目：智能开发助手 Agent

✅ 验收标准（项目交付清单）

Day 11-12：核心开发 - [ ] 项目有清晰的目录结构 - [ ] FastAPI 后端框架搭建完成 - [ ] Agent 核心循环实现（ReAct 或 LangGraph） - [ ] 工具系统：至少 4 个可用工具

Day 13：Web UI - [ ] FastAPI + SSE（Server-sent Events）实现流式 API - [ ] 简单 Web 前端（Streamlit / Gradio / 纯 HTML+JS） - [ ] Agent 思考过程可视化（显示 Thought、Action、Observation）

Day 14：测试与部署 - [ ] 单元测试（pytest + pytest-asyncio） - [ ] Token 消耗统计与优化 - [ ] Docker 容器化（Dockerfile + docker-compose.yml） - [ ] 部署到云服务器或本地运行

Day 15：文档 - [ ] README.md：项目介绍、安装步骤、使用方法 - [ ] 架构图（可以用 Markdown 画图或贴图） - [ ] 示例代码

📊 综合评分标准

🔧 使用验收脚本

使用方法：

# 先用模板创建你的练习代码
# （模板文件：day01_practice_template.py 等）

# 编辑模板，完成所有 TODO

# 运行验收脚本
python day01_practice_validator.py
python day01_practice_validator.py --file my_code.py  # 指定文件

💡 常见问题

Q1：验收脚本报错了，怎么办？

A：仔细阅读脚本输出的"改进建议"部分，逐项修改你的代码，然后重新运行验收脚本。

Q2：我的代码能运行，但验收脚本不给满分？

A：验收脚本不仅检查"能运行"，还检查"最佳实践"（类型注解、错误处理、代码规范等）。根据建议改进即可。

Q3：Day 8/9/10 没有自动验收脚本？

A：这些天的练习更综合，难以完全自动化验收。请按照文档中的"手动检查清单"逐项自查。

Q4：我可以参考标准答案吗？

A：可以！每个 Day 的 tutorial_xx.py 或 ACCEPTANCE_CRITERIA.md 里都有标准答案。但建议先自己尝试，卡住了再看。

祝你学习顺利！遇到任何问题，随时问我！ 🚀