Agent 应用开发 · 分阶段详细教程

配套 学习路线图（测试开发转型版）。每篇教程包含：知识讲解与示例代码、常见坑、练习、面试自测题。 教程中的示例代码已在以下版本上验证：Python 3.12、anthropic 2.4、langchain 1.4、langgraph 1.2、mcp 2.3、fastapi 0.16x、chromadb 1.5。框架迭代很快，遇到不一致时以官方文档为准。

使用方式

1. 按顺序学：阶段之间有依赖，每篇开头都写了"前置"；
2. 先读后写：读完一节立刻动手，练习就是验收标准；核心代码（Agent 循环、MCP Server、算法）关掉 AI 补全手写；
3. 每篇结束做自测题：能脱稿讲清楚才算过关，讲不清的记进 问题集中项.md；
4. 作品驱动：每个阶段都有作品产出，作品是简历和面试的核心素材。

模型 API：示例主要使用 Anthropic Claude（官方 SDK）。使用 DeepSeek、通义千问等 OpenAI 兼容接口的模型时，概念完全相同，差异见 Nano Agent 第 7 节；LangChain 中只需更换模型字符串和集成包。

阶段一：基础巩固 + 后端入门

在职 6～8 周 / 全职 3～4 周 · 产出：重构后的测试工具、第一个 FastAPI 服务、模式对比笔记

阶段二：框架掌握 + 后端工程化

在职 8～10 周 / 全职 5～6 周 · 产出：手写 Nano Agent、作品②测试用例生成 Agent

阶段三：RAG / MCP / 评估体系

在职 8～10 周 / 全职 5～6 周 · 产出：作品①金融文档 RAG + 评估平台、作品③测试平台 MCP Server → 可以全面投递

阶段四：生产级能力与冲刺

在职 6～8 周 / 全职 3～4 周 · 产出：生产化改造、项目叙事、简历

面试高频题 → 教程索引

完整的题目与答题框架见 面试准备 · 第 5 节。

Agent 应用开发 · 学习路线图（测试开发转型版）

面向 测试开发 → Agent / LLM 应用开发 的转型路线，基于原版 agent-learning-roadmap.md 调整。 核心思路：Python 主线不变，补齐后端工程能力，从零做出作品集，把"Agent 评估"做成个人王牌。

📚 每个阶段的详细教程见 tutorials/README.md（Python 进阶部分在 code/01-python，含练习和自动判题）。

目录

• 一、文档定位
• 二、相对原版的调整一览
• 三、路线全景
• 四、阶段一：基础巩固 + 后端入门
• 五、阶段二：框架掌握 + 后端工程化
• 六、阶段三：RAG / MCP / 评估体系
• 七、阶段四：生产级能力与冲刺
• 八、作品集规划
• 九、能力里程碑与时间预期
• 十、算法并行训练
• 十一、每日节奏
• 十二、投递策略
• 十三、简历与面试
• 十四、高频面试题对照表

一、文档定位

适用对象

• 测试开发背景，有 Python 基础，没有 Java / 后端主力开发经验；
• 没有现成的 Agent 生产项目，需要自己从零构建作品集；
• 目标是胜任 Agent 应用开发工程师：能设计、能实现、能上线、能评估。

你的优势与短板

四条核心原则

关于 AI 工具：学原理、刷算法、写核心模块时关掉；做项目工程部分时可以用 Claude Code / Cursor 等，熟练使用 AI 编程工具本身也是这个岗位的能力。

二、相对原版的调整一览

三、路线全景

┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│    阶段一    │─▶│    阶段二    │─▶│    阶段三    │─▶│    阶段四    │
│ 基础+后端入门 │  │ 框架+工程化  │  │ RAG/MCP/评估 │  │ 生产级+冲刺  │
└──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘
       │                 │                 │                 │
   Python 进阶       Nano Agent         RAG 全栈         多 Agent
   模型层认知        LangChain 1.x       MCP Server       幻觉/安全/成本
   Agent 模式        LangGraph          评估体系 ★        Context Eng.
   FastAPI 入门      DB/Redis/Docker    作品①③           面试叙事
                     作品②

四、阶段一：基础巩固 + 后端入门

目标：Python 从"写脚本"升级到"写服务"，建立模型层与 Agent 模式的认知框架。

📚 详细教程：Python 进阶 · FastAPI 入门 · 模型层认知 · Agent 架构模式

1. Python 进阶

做法

• 用 asyncio + 类型提示 重构一个自己写过的测试工具（如接口自动化框架、数据构造工具、pytest 插件）；
• 写核心代码时关闭 AI 补全。

重点能力

资料

• Python 教程 — Python 3.14 文档
• Python 教程 — 廖雪峰的官方网站
• Pydantic 文档

2. FastAPI 入门（提前到阶段一）

后端是你最大的短板，越早开始越好。阶段一只要求"能写出一个规范的服务"。

练习：把重构后的测试工具包装成 FastAPI 服务，提供 HTTP 接口并写好 pytest 接口测试（发挥老本行）。

资料

• FastAPI 官方文档（中文）

3. 模型层认知（适度即可）

资料

• 3B1B · Transformers, the tech behind LLMs
• 3B1B · Attention in transformers, step-by-step
• Andrej Karpathy · Let's build the GPT Tokenizer
• 选读：Anthropic · A Mathematical Framework for Transformer Circuits

4. Agent 架构模式系统化

产出：一份模式对比笔记，能回答"这个场景为什么选 A 不选 B"。

资料

• LLM Powered Autonomous Agents · Lil'Log
• Building Effective Agents · Anthropic

五、阶段二：框架掌握 + 后端工程化

目标：理解框架"吃掉了什么"，并能把 Agent 做成可部署的服务。

📚 详细教程：Nano Agent · LangChain · LangGraph · 后端工程化 · 作品②

0. 前置：Nano Agent（手写最小 Agent）

不使用任何框架，直接调模型 API 手写一个最小 Agent，搞清楚：

• Agent 循环的结构：调用模型 → 解析工具调用 → 执行工具 → 拼接结果 → 判断终止；
• 消息历史如何增长，Token 为什么会爆；
• 终止条件：最大步数、无工具调用、异常——为后面的"防死循环"打基础。

资料

• sanbuphy/nanoAgent
• Learn Claude Code

1. LangChain 1.x

资料

• LangChain Overview · Docs by LangChain

2. LangGraph（最重要）

概念线：StateGraph → 节点 → 边 → 条件路由 → checkpointer → store

验收：完成作品②（见第八部分）。

配套：用 LangSmith 或 Langfuse 做 trace，观察每一步输入输出、耗时与 Token。

资料

• LangGraph Overview · Docs by LangChain
• Langfuse 文档

3. 后端工程化（补短板）

练习：把作品②部署成 FastAPI 服务，支持流式输出、会话持久化，用 docker-compose 一键启动。

资料

• pgvector
• Docker 官方文档

六、阶段三：RAG / MCP / 评估体系

目标：补上 RAG 与 MCP，并建立你的王牌——评估体系。

📚 详细教程：RAG · 评估体系 · MCP · 作品①③

1. RAG 技术栈（作品①）

文档解析 ─▶ 切分 ─▶ Embedding ─▶ 向量库 ─▶ 检索 ─▶ 重排 ─▶ 生成 ─▶ 评估
   │         │         │           │         │        │        │       │
 PDF/表格   粒度/重叠  领域/维度   pgvector  向量/BM25 rerank  引用溯源 Ragas
 异构文档   语义边界   中英文     → Milvus   混合检索          防幻觉   回归测试

资料

• All-in-RAG · 大模型应用开发实战：RAG 技术全栈指南
• Advanced RAG Cheat Sheet · LlamaIndex
• HNSW · Pinecone
• IVF_FLAT · Milvus / IVF_PQ · Milvus

2. 评估体系 ★（个人王牌）

面试中 10 场有 8 场问评估。这是测试开发经验可以直接迁移的地方，要做到比其他候选人讲得都深。

练习：给作品①和作品②各建一个评测集，接入 CI（如 GitHub Actions），每次改动自动产出指标对比报告。

资料

• Ragas 文档
• LangSmith Evaluation
• Langfuse 文档

3. MCP（作品③）

关键练习：关闭 AI，手写一个 MCP Server。

资料

• MCP 中文站
• mcp-for-beginners（中文版）
• MCP 终极指南

七、阶段四：生产级能力与冲刺

目标：从"能跑"升级到"能上线、能取舍、能讲清楚"。

📚 详细教程：多 Agent · 幻觉抑制 · Context Engineering 与记忆 · 安全、成本与延迟 · 面试准备

1. 多 Agent 设计

资料

• Multi-agent · Docs by LangChain

2. 幻觉抑制（面试高频，原版缺失）

3. Context Engineering 与记忆

资料

• Context Engineering for AI Agents · Manus
• Agent Skills Overview
• 体系化阅读：bojieli/ai-agent-book

4. 安全与成本

5. 面试准备

• 项目叙事：每个作品按 STAR 拆出 2–3 个难点，必须带数字；
• 模拟面试：用第十四部分的高频题自测，每题追问三层；
• 复盘：每场面试后记录卡壳点，针对性补齐。

八、作品集规划

你没有公司里的 Agent 项目，作品集就是你的项目经历。三个作品分别覆盖 RAG、Agent 编排、协议层，并且都带评估。

作品要求

• GitHub 开源，README 写清架构图、技术选型理由、评估结果；
• docker-compose 一键启动；
• 每个项目准备一份"优化决策记录"：试过什么、为什么放弃、数据如何。

作品②最能讲好转型故事："我用测试开发的领域知识 + Agent 技术，解决了测试领域的真实问题。"

九、能力里程碑与时间预期

总时长预估：在职学习约 8–12 个月，全职学习约 4–6 个月。后端基础补得越扎实，后期越轻松。

十、算法并行训练

策略：每天 2 题，全部用 Python，同时练算法与 Python 手感。目标约 110 题，Medium 稳定 AC。

资源：LeetCode Hot 100 · 代码随想录 · NeetCode 150

十一、每日节奏

在职版（工作日约 3 小时）

全职版

精力配比：Agent 主线约 50% · 后端工程约 20% · 算法约 15% · 复盘约 15%

在职转型的额外机会：主动在当前团队推动"AI 辅助测试"或"大模型应用测试"，把学习成果变成真实工作经历。

十二、投递策略

节奏：小厂 → 中厂 → 大厂；准备到 ~75% 就开面；一天最多 3 场；练手避开最想去的公司。

十三、简历与面试

简历怎么写

• 定位一句话：如"测试开发出身的 Agent 应用工程师，擅长 Agent 评估与质量体系建设"；
• 项目用 STAR，每条带数字（准确率、Token 成本、耗时、通过率）；
• 关键词对齐岗位：LangGraph、RAG、MCP、FastAPI、向量数据库、Agent 评估、LLM-as-Judge 等；
• 保留测试开发经历，强调可迁移部分：自动化框架设计、CI/CD、质量度量、平台开发。

常见坑

十四、高频面试题对照表

来自 问题集中项.md，标注本路线中对应的学习位置。

附：一句话总结

Python 打底，补齐后端，从零做出三个带评估的作品，再把"测试开发的质量思维"变成 Agent 评估这张王牌。

• 后端侧有什么 AI 相关的实践，怎么验证的效果
• 多 Agent 怎么防止死循环
• 多 Agent 怎么设计有哪些模式
• Agent 范式怎么选
• Agent 评估思路和方案（10 场有 8 场问）
• RAG 的检索策略选择、异构文档怎么切分（几乎必问）
• 幻觉怎么抑制（10 场有 4 场问）

阶段一 · Python 进阶（含基础回顾）

对应 新版路线图 的「四、阶段一 → 1. Python 进阶」。 适合长期 vibe coding、基础已经生疏的状态：先把基础捡回来，再进阶到 Agent 开发天天要用的 typing、Pydantic、asyncio。

一、学完之后你能做到什么

• 不靠 AI，独立写出 200 行左右、结构清晰的 Python 模块；
• 看懂 LangChain / LangGraph / FastAPI 源码和文档里的写法：类型提示、装饰器、Pydantic 模型、async/await；
• 独立完成一个异步并发的接口测试执行器（综合项目），带超时、重试、并发控制和报告。

二、课程安排（共 9 课，在职约 4 周）

全职学习可压缩到 2 周。第 1 周如果觉得基础还在，可以直接做练习，全部通过就跳到下一课。

三、目录结构

01-python/
├── README.md            ← 你正在看的文件
├── lessons/             ← 9 课教程（先读）
├── exercises/           ← 练习题（你在这里写代码）
│   └── apitester/       ← 综合项目
├── solutions/           ← 参考答案（做完再看！）
├── tests/               ← 自动判题（pytest）
└── data/                ← 示例数据

四、环境准备

本目录已经是一个 uv 项目，Python 3.12+。

uv sync

跑某一课的测试（你的答案）：

uv run pytest tests/test_ex01_basics.py

只跑某一道题：

uv run pytest tests/test_ex01_basics.py -k word_count

对照参考答案跑一遍（确认测试本身没问题）：

uv run pytest --target=solutions

打开交互式解释器（REPL，读教程时边看边敲）：

uv run python

五、学习方法（专门针对 vibe coding 后遗症）

1. 关掉 AI 补全

做练习时关闭 Copilot / Cursor Tab / 通义灵码等补全。VS Code 可以在右下角的 Copilot 图标里临时禁用。 这一步不做，后面全白做——你的问题不是"不知道"，而是"手没写过"。

2. 每课的固定流程

读教程 ──▶ REPL 里"先猜后跑" ──▶ 合上教程做练习 ──▶ pytest 判题 ──▶ 对照参考答案 ──▶ 回答自测题

• 先猜后跑：教程里每段代码，先在心里预测输出，再到 REPL 里运行。猜错的地方就是要记的地方。
• 合上教程做练习：卡住超过 15 分钟，再回去翻教程，而不是直接问 AI。
• 对照参考答案：通过后再看 solutions/，比较写法差异。答案不唯一，测试通过即可。
• 自测题：每课末尾有几道"面试式"问题，能口头讲清楚才算过关。

3. 允许查的东西

• 官方文档（Python 文档、Pydantic 文档）；
• help(xxx)、dir(xxx)，这是 Python 自带的"文档"，面试现场也能用。

4. 记一份"踩坑笔记"

每次猜错、测试失败、卡住，都用一句话记下来。这份笔记就是面试前的复习材料。

六、阶段验收

• [ ] uv run pytest 全部通过（不看答案完成）；
• [ ] 每课自测题都能口头回答；
• [ ] 综合项目 apitester 能跑通 demo：uv run python -m exercises.apitester；
• [ ] 能向别人解释：协程是什么、为什么 Agent 服务要用 async、Pydantic 在 Agent 里用在哪。

完成后进入路线图的下一节：FastAPI 入门。

01 · 基础回顾：数据类型与控制流

目标：把最常用的数据类型和控制流重新"写进手里"。 练习：exercises/ex01_basics.py · 测试：uv run pytest tests/test_ex01_basics.py 建议用时：3–4 小时

打开 REPL 跟着敲：

uv run python

1. 变量与基本类型

Python 是动态类型：变量本身没有类型，它指向的对象有类型。

x = 10          # int
x = "ten"       # 现在指向 str，合法
type(x)         # <class 'str'>
isinstance(x, str)   # True —— 判断类型用 isinstance，不要用 type(x) == str

真值判断

以下值在 if 里都是 假：False、None、0、0.0、""、[]、{}、set()。

items = []
if not items:          # 推荐写法
    print("空列表")

⚠️ 坑：if value: 会把 0 和 "" 也当成"没有"。如果 0 是合法值，写 if value is not None:。

2. 字符串

name = "Agent"
f"Hello, {name}!"                 # f-string，最常用
f"{3.14159:.2f}"                  # '3.14'  保留两位小数
f"{42:>6}"                        # '    42' 右对齐宽度 6
f"{name=}"                        # "name='Agent'"  调试神器

s = "  Hello, World  "
s.strip()                         # 'Hello, World'   去两端空白
s.strip().lower()                 # 'hello, world'
"a,b,,c".split(",")               # ['a', 'b', '', 'c']
"a b   c".split()                 # ['a', 'b', 'c']   不传参数按任意空白切，并去掉空串
"-".join(["2026", "10", "22"])    # '2026-10-22'
"hello".replace("l", "L")         # 'heLLo'
"report.json".endswith(".json")   # True
"key=value=x".partition("=")      # ('key', '=', 'value=x')   只切第一个
"py" in "python"                  # True

切片（列表、元组同样适用）

s = "13812345678"
s[0]       # '1'
s[-1]      # '8'
s[:3]      # '138'      前 3 个
s[-4:]     # '5678'     后 4 个
s[3:7]     # '1234'     [3, 7) 左闭右开
s[::-1]    # 反转

字符串不可变：s[0] = "x" 会报 TypeError。所有"修改"方法都返回新字符串。

3. 列表 list

nums = [3, 1, 2]
nums.append(4)          # [3, 1, 2, 4]
nums.extend([5, 6])     # [3, 1, 2, 4, 5, 6]
nums.insert(0, 0)       # 在下标 0 插入
nums.pop()              # 弹出最后一个并返回
nums.remove(3)          # 删除第一个值为 3 的元素（不存在会报错）
len(nums)
3 in nums               # 成员判断，O(n)

nums.sort()                    # 原地排序，返回 None！
new = sorted(nums, reverse=True)   # 返回新列表

⚠️ 坑：nums = nums.sort() 会把 nums 变成 None。

按规则排序：key

cases = [{"name": "pay", "priority": 2}, {"name": "login", "priority": 1}]
sorted(cases, key=lambda c: c["priority"])

# 多级排序：先按次数降序，再按名字升序 —— 用元组 + 负号
counts = {"b": 2, "a": 2, "c": 5}
sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
# [('c', 5), ('a', 2), ('b', 2)]

4. 元组 tuple 与解包

元组是不可变的列表，常用于"一组固定含义的值"。

point = (3, 4)
x, y = point                # 解包
a, b = b, a                 # 交换变量
first, *rest = [1, 2, 3, 4] # first=1, rest=[2, 3, 4]

for name, score in [("a", 90), ("b", 80)]:   # 遍历时解包
    print(name, score)

单元素元组要加逗号：(1,)。(1) 只是整数 1。

5. 字典 dict（Agent 开发里用得最多）

LLM 的消息、工具调用参数、API 返回值，本质上都是字典。

msg = {"role": "user", "content": "你好"}
msg["role"]                     # 'user'
msg["name"]                     # KeyError！
msg.get("name")                 # None
msg.get("name", "匿名")          # '匿名'
msg["content"] = "hi"           # 修改 / 新增
"role" in msg                   # 判断 key 是否存在
del msg["content"]

for key, value in msg.items():  # 同时拿 key 和 value
    print(key, value)

list(msg.keys()), list(msg.values())

# 合并（3.9+）
defaults = {"timeout": 5, "retries": 1}
override = {"timeout": 10}
config = defaults | override    # {'timeout': 10, 'retries': 1}

计数与分组的三种写法

words = ["a", "b", "a"]

# 写法 1：get
counts = {}
for w in words:
    counts[w] = counts.get(w, 0) + 1

# 写法 2：setdefault —— 分组时最顺手
groups = {}
for name, status in [("login", "passed"), ("pay", "failed")]:
    groups.setdefault(status, []).append(name)

# 写法 3：标准库（第 03 课会讲）
from collections import Counter, defaultdict
Counter(words)                  # Counter({'a': 2, 'b': 1})

Python 3.7+ 字典保持插入顺序，这一点常被用来"有序去重"：list(dict.fromkeys(items))。

6. 集合 set

s = {1, 2, 3}
s.add(4)
2 in s                     # O(1)，比列表快得多
{1, 2} | {2, 3}            # 并集 {1, 2, 3}
{1, 2} & {2, 3}            # 交集 {2}
{1, 2} - {2, 3}            # 差集 {1}
set([3, 1, 3])             # 去重，但不保证顺序
empty = set()              # 注意：{} 是空字典，不是空集合

7. 控制流

# for + enumerate：同时要下标和值
for i, name in enumerate(["a", "b"], start=1):
    print(i, name)

# zip：并行遍历多个序列
for name, status in zip(["login", "pay"], [200, 500]):
    print(name, status)

# range
list(range(5))         # [0, 1, 2, 3, 4]
list(range(1, 10, 3))  # [1, 4, 7]

# while + break / continue
n = 0
while True:
    n += 1
    if n % 2 == 0:
        continue
    if n > 7:
        break

# 三元表达式
label = "PASS" if passed else "FAIL"

match（3.10+，结构化匹配）

处理不同类型的 LLM 消息时很好用：

def handle(event: dict) -> str:
    match event:
        case {"type": "text", "content": content}:
            return f"文本: {content}"
        case {"type": "tool_call", "name": name}:
            return f"调用工具 {name}"
        case _:
            return "未知事件"

8. 推导式

把"循环 + append"压成一行，但只在逻辑简单时用。

squares = [x * x for x in range(5)]                  # [0, 1, 4, 9, 16]
evens = [x for x in range(10) if x % 2 == 0]         # 带过滤
flat = [x for row in [[1, 2], [3]] for x in row]     # 嵌套：顺序和 for 循环写法一致
name_len = {name: len(name) for name in ["ab", "c"]} # 字典推导
unique = {x % 3 for x in range(10)}                  # 集合推导
total = sum(x * x for x in range(5))                 # 生成器表达式，不建列表

嵌套推导式怎么读：把它还原成普通 for 循环，从左到右就是从外到内。

9. 可变与不可变：最容易出 bug 的地方

变量是"标签"，赋值不复制对象：

a = [1, 2]
b = a           # b 和 a 指向同一个列表
b.append(3)
a               # [1, 2, 3]  ← a 也变了！

c = a.copy()    # 浅拷贝：新列表
c.append(4)
a               # [1, 2, 3]

nested = [[1], [2]]
shallow = nested.copy()
shallow[0].append(99)
nested          # [[1, 99], [2]]  ← 浅拷贝只复制一层

import copy
deep = copy.deepcopy(nested)   # 深拷贝

Agent 关联：在 LangGraph 里直接修改传进来的 state 字典，而不是返回新值，是常见 bug 来源之一。

is 与 ==：== 比较值，is 比较是否同一个对象。除了 None，几乎都用 ==。

10. 练习

打开 exercises/ex01_basics.py，实现 7 个函数：

uv run pytest tests/test_ex01_basics.py

11. 自测题

1. sorted(x) 和 x.sort() 有什么区别？
2. 为什么 {} 不是空集合？怎么创建空集合？
3. 下面代码输出什么？为什么？

   a = {"tags": ["x"]}
   b = a.copy()
   b["tags"].append("y")
   print(a)
   

4. 如何对一个列表去重并保持原顺序？说出两种写法。
5. if value: 和 if value is not None: 分别在什么场景下用？

02 · 函数

目标：彻底搞懂参数传递、作用域和闭包——这是后面装饰器、回调、工具注册的地基。 练习：exercises/ex02_functions.py · 测试：uv run pytest tests/test_ex02_functions.py 建议用时：3 小时

1. 定义与返回

def add(a, b):
    """返回 a + b。"""      # docstring：help(add) 能看到；LangChain 用它做工具描述
    return a + b

def divmod_(a, b):
    return a // b, a % b    # 返回多个值，本质是返回一个元组

q, r = divmod_(7, 2)        # 解包

def nothing():
    pass
nothing()                   # 没有 return 时返回 None

2. 参数的五种形态

def f(a, b=2, *args, c, d=4, **kwargs):
    print(a, b, args, c, d, kwargs)

f(1, c=3)                   # 1 2 () 3 4 {}
f(1, 5, 6, 7, c=3, e=9)     # 1 5 (6, 7) 3 4 {'e': 9}

仅关键字参数：让调用更清晰

def call_llm(prompt, *, model="claude-sonnet", temperature=0.0):
    ...

call_llm("hi", temperature=0.7)   # 正确
call_llm("hi", "gpt", 0.7)        # TypeError —— 防止参数顺序传错

框架 API 大量使用这种写法，比如 ChatAnthropic(model=..., temperature=...)。

仅位置参数 /（了解即可）

def pow_(base, exp, /):   # base 和 exp 只能按位置传
    return base ** exp

调用时解包

args = (1, 2)
kwargs = {"c": 3}
f(*args, **kwargs)   # 等价于 f(1, 2, c=3)

# Agent 关联：LLM 返回的工具参数是字典，执行工具就是这一行
tool_args = {"city": "北京", "days": 3}
get_weather(**tool_args)

3. 经典坑：可变默认参数

def append_bad(item, items=[]):
    items.append(item)
    return items

append_bad(1)   # [1]
append_bad(2)   # [1, 2]   ← 什么？！

原因：默认值在函数定义时只求值一次，所有调用共享同一个列表。

正确写法：

def append_ok(item, items=None):
    if items is None:
        items = []
    items.append(item)
    return items

面试常考。默认值只用不可变对象（None、数字、字符串、元组）。

4. 函数是"一等公民"

函数本身就是对象：可以赋值、放进容器、作为参数传递、作为返回值。

def shout(s): return s.upper()
def whisper(s): return s.lower()

speak = shout
speak("hi")                     # 'HI'

# 放进字典 —— 这就是最朴素的"工具注册表"
tools = {"shout": shout, "whisper": whisper}
tools["whisper"]("HELLO")       # 'hello'

# 作为参数传递
def apply(func, value):
    return func(value)
apply(shout, "x")

# lambda：一行的匿名函数，只适合简单表达式
sorted(["bb", "a", "ccc"], key=lambda s: len(s))

Agent 关联：Agent 的核心循环就是"LLM 给出工具名 + 参数 → 从注册表找到函数 → func(**args)"。

5. 作用域：LEGB

查找变量的顺序：Local → Enclosing（外层函数）→ Global（模块）→ Builtin。

x = "global"

def outer():
    x = "enclosing"
    def inner():
        print(x)        # 找到 enclosing
    inner()

outer()

赋值会创建局部变量：

count = 0
def inc():
    count += 1      # UnboundLocalError！因为赋值让 count 变成了局部变量

修改外层变量需要声明：

6. 闭包

内层函数"记住"了外层函数的变量，即使外层函数已经返回。

def make_counter():
    count = 0
    def counter():
        nonlocal count
        count += 1
        return count
    return counter

c1 = make_counter()
c1(), c1()       # (1, 2)
c2 = make_counter()
c2()             # 1   —— 各自独立

闭包的用途：带状态的函数、工厂函数、装饰器（第 05 课）。

闭包延迟绑定坑（面试常考）

funcs = [lambda x: x * i for i in range(3)]
[f(10) for f in funcs]     # [20, 20, 20]  而不是 [0, 10, 20]

原因：lambda 记住的是变量 i 本身，调用时才去查值，此时循环已结束，i == 2。

修复：用默认参数在定义时"捕获"当前值：

funcs = [lambda x, i=i: x * i for i in range(3)]
[f(10) for f in funcs]     # [0, 10, 20]

7. 高阶函数常用工具

from functools import partial, reduce

nums = [1, 2, 3, 4]
list(map(lambda x: x * 2, nums))         # [2, 4, 6, 8]   推导式通常更清晰
list(filter(lambda x: x % 2, nums))      # [1, 3]
reduce(lambda a, b: a + b, nums)         # 10
any(x > 3 for x in nums)                 # True
all(x > 0 for x in nums)                 # True
max(["a", "ccc", "bb"], key=len)         # 'ccc'

# partial：固定部分参数，生成新函数
def request(method, url, timeout):
    ...
get = partial(request, "GET", timeout=5)
get("https://example.com")

8. 练习

uv run pytest tests/test_ex02_functions.py

9. 自测题

1. *args 和 **kwargs 分别收集成什么类型？调用时 f(*a, **kw) 是什么意思？
2. 为什么默认参数不能用 []？默认值是什么时候求值的？
3. global 和 nonlocal 的区别？
4. 解释闭包延迟绑定的原因，以及两种修复方法。
5. 如果让你实现一个"根据工具名调用函数"的最小注册表，你会怎么写？

03 · 异常、文件与模块

目标：写出"出错时行为可预期"的代码；能读写文件和 JSON；搞懂 import 为什么会报错。 练习：exercises/ex03_errors_io.py · 测试：uv run pytest tests/test_ex03_errors_io.py 建议用时：3 小时

1. 异常处理全貌

try:
    result = risky()
except (ConnectionError, TimeoutError) as e:   # 可以一次捕获多种
    print(f"网络问题: {e}")
except ValueError:
    print("值错误")
else:
    print("没出错时执行")      # 只有 try 没抛异常才执行
finally:
    print("无论如何都执行")     # 清理资源：关连接、删临时文件

原则

主动抛异常

def set_temperature(t: float):
    if not 0 <= t <= 1:
        raise ValueError(f"temperature 必须在 0~1 之间，收到 {t}")

异常链：raise ... from ...

把底层异常包装成业务异常，同时保留原始原因：

import json

try:
    data = json.loads(text)
except json.JSONDecodeError as e:
    raise ConfigError("配置文件格式错误") from e

报错时会显示两段 traceback，中间是 The above exception was the direct cause of...。原始异常保存在 err.__cause__ 里。

不想暴露底层异常时用 raise ... from None。

自定义异常

class AgentError(Exception):
    """项目所有异常的基类。"""

class ToolNotFoundError(AgentError):
    def __init__(self, tool_name: str):
        self.tool_name = tool_name                    # 带上结构化信息，方便上层处理
        super().__init__(f"工具不存在: {tool_name}")

try:
    raise ToolNotFoundError("search")
except AgentError as e:                               # 用基类统一捕获
    print(e, e.tool_name)

EAFP vs LBYL

Python 风格偏向 EAFP（先做，出错再处理）：

# LBYL：先检查
if key in d:
    value = d[key]

# EAFP：直接做
try:
    value = d[key]
except KeyError:
    value = None

2. 文件读写

# 永远用 with，自动关闭文件；永远写 encoding，Windows 默认编码不是 UTF-8！
with open("note.txt", "w", encoding="utf-8") as f:
    f.write("第一行\n")

with open("note.txt", encoding="utf-8") as f:
    content = f.read()           # 全部读入

with open("note.txt", encoding="utf-8") as f:
    for line in f:               # 逐行读，大文件也不怕
        print(line.rstrip("\n"))

⚠️ Windows 上不写 encoding="utf-8"，读中文文件经常 UnicodeDecodeError。

3. pathlib：现代的路径操作

from pathlib import Path

p = Path("data") / "cases" / "login.json"   # 用 / 拼路径，跨平台
p.name          # 'login.json'
p.stem          # 'login'
p.suffix        # '.json'
p.parent        # Path('data/cases')
p.exists()
p.is_file()

p.parent.mkdir(parents=True, exist_ok=True)       # 递归建目录，已存在不报错
p.write_text('{"a": 1}', encoding="utf-8")
p.read_text(encoding="utf-8")

for f in Path("data").rglob("*.json"):            # 递归查找
    print(f.relative_to("data").as_posix())       # 相对路径，统一用 / 分隔

Path.cwd()                  # 当前工作目录
Path(__file__).parent       # 当前脚本所在目录 —— 读同目录资源文件的标准写法

4. JSON

Agent 开发里 JSON 无处不在：LLM 的工具参数、API 请求响应、配置、评测集。

import json

data = {"name": "登录", "tags": ["smoke"], "ok": True, "x": None}

text = json.dumps(data)                                 # dict → str
text = json.dumps(data, ensure_ascii=False, indent=2)   # 中文不转义 + 缩进
obj = json.loads(text)                                  # str → dict

with open("a.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=2)    # 直接写文件
with open("a.json", encoding="utf-8") as f:
    obj = json.load(f)

解析失败抛 json.JSONDecodeError（ValueError 的子类），带 lineno、colno。LLM 输出的 JSON 经常不合法，这个异常你会天天见。

5. 模块与包

• 模块：一个 .py 文件；
• 包：一个包含 __init__.py 的目录。

myproject/
├── main.py
└── agent/
    ├── __init__.py
    ├── tools.py
    └── llm.py

import json                       # 导入整个模块
from pathlib import Path          # 导入模块里的名字
from agent.tools import search    # 从包里导入
from agent import tools as t      # 起别名

# agent/llm.py 里导入同包的模块
from .tools import search         # 相对导入（只能在包内部用）

if __name__ == "__main__":

# tools.py
def search(q): ...

if __name__ == "__main__":
    print(search("test"))   # 直接运行这个文件时才执行，被 import 时不执行

ModuleNotFoundError 排查思路

Python 按 sys.path 列表的顺序找模块。

import sys
print(sys.path)   # 第一个通常是"被运行脚本所在的目录"

1. 包没装？→ uv add xxx；
2. 装在别的虚拟环境里？→ 用 uv run python 而不是系统 python；
3. 自己的模块找不到？→ 看运行位置。推荐用 python -m package.module 从项目根目录运行；
4. 文件名和标准库重名？→ 自己写了个 json.py、random.py，会遮蔽标准库。

6. 常用标准库速览

from collections import Counter, defaultdict, deque
Counter("hello").most_common(2)    # [('l', 2), ('h', 1)]
d = defaultdict(list); d["k"].append(1)     # 不存在的 key 自动建空列表
q = deque(maxlen=3)                # 固定长度队列 —— "保留最近 N 轮对话"

from datetime import datetime, timedelta
datetime.now().strftime("%Y-%m-%d %H:%M:%S")
datetime.now() + timedelta(days=1)

import time
start = time.perf_counter(); ...; elapsed = time.perf_counter() - start   # 计时用这个

import os
os.environ.get("ANTHROPIC_API_KEY")      # 读环境变量 —— 密钥永远不要写在代码里

import logging
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
logging.info("开始调用 %s", "search")    # 用 logging 代替 print（第 09 课细讲）

7. 练习

测试里用了 pytest 的 tmp_path fixture（自动创建临时目录），你作为测试开发应该很熟。

uv run pytest tests/test_ex03_errors_io.py

8. 自测题

1. else 和 finally 分别什么时候执行？
2. 为什么不要写裸 except:？
3. raise X from e 和直接 raise X 有什么区别？
4. 为什么读写文件一定要指定 encoding="utf-8"？
5. 遇到 ModuleNotFoundError，你的排查步骤是什么？

04 · 面向对象与 dataclass

目标：能设计清晰的类；看懂框架里的魔术方法、@property、classmethod、抽象基类。 练习：exercises/ex04_oop.py · 测试：uv run pytest tests/test_ex04_oop.py 建议用时：4 小时

1. 类的基本结构

class LLMClient:
    default_model = "claude-sonnet"          # 类属性：所有实例共享

    def __init__(self, api_key: str, model: str | None = None):
        self.api_key = api_key               # 实例属性：每个实例独有
        self.model = model or self.default_model
        self._call_count = 0                 # 单下划线：约定为"内部使用"

    def chat(self, prompt: str) -> str:      # 实例方法，第一个参数是 self
        self._call_count += 1
        return f"[{self.model}] echo: {prompt}"

client = LLMClient("sk-xxx")
client.chat("hi")

⚠️ 类属性如果是可变对象（如 tags = []），所有实例会共享同一个列表——和可变默认参数是同一类坑。

2. 三种方法

class Config:
    def __init__(self, data: dict):
        self.data = data

    def get(self, key):                  # 实例方法：需要访问实例数据
        return self.data.get(key)

    @classmethod
    def from_json(cls, text: str):       # 类方法：第一个参数是类本身，常用作"备选构造器"
        import json
        return cls(json.loads(text))

    @staticmethod
    def is_valid_key(key: str) -> bool:  # 静态方法：和类相关，但不需要 self / cls
        return key.isidentifier()

cfg = Config.from_json('{"model": "x"}')

框架中常见的 XXX.from_template(...)、XXX.from_documents(...)、Model.model_validate(...) 都是 classmethod。

3. @property：像属性一样访问的方法

class Conversation:
    def __init__(self):
        self.messages: list[dict] = []

    @property
    def turns(self) -> int:              # 计算属性，只读
        return sum(1 for m in self.messages if m["role"] == "user")

    @property
    def max_tokens(self) -> int:
        return self._max_tokens

    @max_tokens.setter
    def max_tokens(self, value: int):    # 赋值时做校验
        if value <= 0:
            raise ValueError("max_tokens 必须大于 0")
        self._max_tokens = value

c = Conversation()
c.turns              # 不加括号
c.max_tokens = 1000

4. 继承与 super()

class BaseTool:
    def __init__(self, name: str, description: str):
        self.name = name
        self.description = description

    def run(self, **kwargs) -> str:
        raise NotImplementedError

class SearchTool(BaseTool):
    def __init__(self, top_k: int = 3):
        super().__init__("search", "搜索网页")    # 调用父类初始化
        self.top_k = top_k

    def run(self, query: str) -> str:            # 重写父类方法
        return f"搜索 {query}，返回前 {self.top_k} 条"

tool = SearchTool()
isinstance(tool, BaseTool)    # True

组合优于继承：继承层级不要超过 2–3 层。很多时候"持有一个对象"比"继承一个类"更灵活。

5. 魔术方法（dunder methods）

让自定义对象支持 Python 的内置语法：

class ToolRegistry:
    def __init__(self):
        self._tools = {}

    def register(self, tool):
        self._tools[tool.name] = tool

    def __len__(self):
        return len(self._tools)

    def __contains__(self, name):
        return name in self._tools

    def __getitem__(self, name):
        return self._tools[name]

    def __iter__(self):
        return iter(self._tools.values())

    def __repr__(self):
        return f"ToolRegistry(tools={list(self._tools)})"

reg = ToolRegistry()
reg.register(SearchTool())
"search" in reg, len(reg), reg["search"]

Agent 关联：LangChain 的 Runnable 能用 | 串起来（prompt | model | parser），就是靠实现了 __or__。

6. dataclass：少写样板代码

只是"装数据"的类，用 @dataclass 自动生成 __init__、__repr__、__eq__：

from dataclasses import dataclass, field, asdict

@dataclass
class Message:
    role: str
    content: str
    tokens: int = 0
    metadata: dict = field(default_factory=dict)   # 可变默认值必须用 default_factory

    def __post_init__(self):                       # 自动生成的 __init__ 执行完后调用
        if self.role not in {"system", "user", "assistant", "tool"}:
            raise ValueError(f"非法 role: {self.role}")

m = Message("user", "你好")
m                           # Message(role='user', content='你好', tokens=0, metadata={})
m == Message("user", "你好") # True
asdict(m)                   # 转字典

@dataclass(frozen=True)     # 不可变：赋值会报错，而且可以作为字典的 key
class ModelName:
    provider: str
    name: str

7. 抽象基类 ABC 与 Protocol

ABC：强制子类实现某些方法

from abc import ABC, abstractmethod

class BaseLLM(ABC):
    @abstractmethod
    def generate(self, prompt: str) -> str: ...

    def __call__(self, prompt: str) -> str:   # 普通方法可以有实现
        return self.generate(prompt)

class FakeLLM(BaseLLM):
    def generate(self, prompt: str) -> str:
        return "fake"

BaseLLM()      # TypeError: Can't instantiate abstract class
FakeLLM()("hi")

Protocol：鸭子类型 + 类型检查

不要求继承，只要"长得像"就行：

from typing import Protocol

class SupportsGenerate(Protocol):
    def generate(self, prompt: str) -> str: ...

def run(llm: SupportsGenerate):   # 任何有 generate 方法的对象都能传进来
    return llm.generate("hi")

写测试时的 Fake / Mock 对象不需要继承真实类，Protocol 正适合这种场景。

8. 练习

uv run pytest tests/test_ex04_oop.py

9. 自测题

1. 类属性和实例属性有什么区别？类属性用可变对象会有什么问题？
2. classmethod 和 staticmethod 的区别？各举一个使用场景。
3. __repr__ 和 __str__ 的区别？
4. dataclass 里为什么不能写 tags: list = []？
5. 什么时候用 dataclass，什么时候用 Pydantic？
6. ABC 和 Protocol 的区别？

05 · 迭代器、生成器、装饰器、上下文管理器

目标：掌握 Python 最有特色的三个机制。框架源码里到处都是它们：@tool、@app.get、with 管理连接、yield 实现流式输出。 练习：exercises/ex05_iter_deco_ctx.py · 测试：uv run pytest tests/test_ex05_iter_deco_ctx.py 建议用时：5 小时（装饰器值得多花时间）

1. 可迭代对象与迭代器

nums = [1, 2, 3]          # 可迭代对象（iterable）：能被 for 遍历
it = iter(nums)           # 迭代器（iterator）：记住"当前走到哪"
next(it)                  # 1
next(it)                  # 2
next(it)                  # 3
next(it)                  # StopIteration —— for 循环就是靠捕获它来结束的

for x in obj 的本质：

it = iter(obj)
while True:
    try:
        x = next(it)
    except StopIteration:
        break
    ...

自己实现一个迭代器：实现 __iter__（返回自己）和 __next__。

class Countdown:
    def __init__(self, start):
        self.current = start
    def __iter__(self):
        return self
    def __next__(self):
        if self.current <= 0:
            raise StopIteration
        value = self.current
        self.current -= 1
        return value

c = Countdown(3)
list(c)    # [3, 2, 1]
list(c)    # []  ← 迭代器是一次性的！

⚠️ 迭代器只能消费一次。生成器、文件对象、map()、zip() 的结果都是迭代器。

2. 生成器：写迭代器的简便方法

函数里出现 yield，它就变成生成器函数。调用它不会执行函数体，而是返回一个生成器对象。

def countdown(n):
    print("开始")
    while n > 0:
        yield n          # 产出一个值，然后"暂停"在这里
        n -= 1
    print("结束")

g = countdown(2)         # 什么都没打印！
next(g)                  # 打印"开始"，返回 2
next(g)                  # 返回 1
next(g)                  # 打印"结束"，抛 StopIteration

为什么要用生成器：惰性 + 省内存

def read_large_log(path):
    with open(path, encoding="utf-8") as f:
        for line in f:
            if "ERROR" in line:
                yield line.strip()

for err in read_large_log("app.log"):    # 10GB 的文件也只占一行的内存
    ...

# 生成器表达式：圆括号版的推导式
total = sum(len(line) for line in open("a.txt", encoding="utf-8"))

无限序列 + itertools

import itertools

def ids():
    n = 0
    while True:
        yield n
        n += 1

list(itertools.islice(ids(), 5))           # [0, 1, 2, 3, 4]
list(itertools.chain([1, 2], [3]))          # [1, 2, 3]
list(itertools.batched(range(5), 2))        # [(0, 1), (2, 3), (4,)]   3.12+

yield from：委托给另一个可迭代对象

def walk(nested):
    for item in nested:
        if isinstance(item, list):
            yield from walk(item)    # 递归展开
        else:
            yield item

list(walk([1, [2, [3]], 4]))   # [1, 2, 3, 4]

Agent 关联：LLM 流式输出就是一个"逐 token 产出"的生成器（异步版本见第 08 课）。LangGraph 的 graph.stream(...) 也是在 for 里逐步拿到每个节点的输出。

3. 装饰器

3.1 本质：函数替换

def log_calls(func):
    def wrapper(*args, **kwargs):
        print(f"调用 {func.__name__}，参数 {args} {kwargs}")
        result = func(*args, **kwargs)
        print(f"返回 {result!r}")
        return result
    return wrapper

@log_calls
def add(a, b):
    return a + b

# @log_calls 完全等价于：
# add = log_calls(add)

add(1, 2)

拆成三步理解：

1. log_calls 接收原函数 func；
2. 定义一个新函数 wrapper，在里面调用 func，前后加料；
3. 返回 wrapper，替换掉原来的 add。

wrapper(*args, **kwargs) 是"原样转发所有参数"的标准写法。

3.2 functools.wraps：保留原函数信息

add.__name__     # 'wrapper'  ← 原函数名丢了！docstring 也丢了

LangChain 的 @tool 正是读取函数名和 docstring 来生成工具描述的，丢了就出问题。所以永远加上 @wraps：

from functools import wraps

def log_calls(func):
    @wraps(func)                 # 把 func 的 __name__、__doc__ 等复制给 wrapper
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

3.3 带参数的装饰器：再包一层

def retry(times=3):                    # 第 1 层：接收装饰器参数
    def decorator(func):               # 第 2 层：接收被装饰的函数
        @wraps(func)
        def wrapper(*args, **kwargs):  # 第 3 层：真正执行
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except Exception:
                    if attempt == times:
                        raise
        return wrapper
    return decorator

@retry(times=5)          # 等价于 call_api = retry(times=5)(call_api)
def call_api(): ...

判断方法：@xxx 后面有括号，就是带参数的装饰器，需要三层。

3.4 装饰器给函数加属性

函数也是对象，可以挂属性：

def count_calls(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        wrapper.calls += 1
        return func(*args, **kwargs)
    wrapper.calls = 0
    return wrapper

3.5 多个装饰器的顺序

@a
@b
def f(): ...
# 等价于 f = a(b(f))：离函数近的先装饰，调用时最外层的 a 先执行

3.6 常见用途

4. 上下文管理器：with 语句

保证"进入时做准备，退出时一定清理"，即使中间出了异常。

4.1 类写法

import time

class Timer:
    def __enter__(self):
        self.start = time.perf_counter()
        return self                       # as 后面拿到的就是这个返回值

    def __exit__(self, exc_type, exc, tb):
        self.elapsed = time.perf_counter() - self.start
        return False                      # False：异常继续向外抛；True：吞掉异常

with Timer() as t:
    sum(range(1_000_000))
print(t.elapsed)

__exit__ 的三个参数：没有异常时都是 None；有异常时是异常类型、异常对象、traceback。

4.2 contextlib.contextmanager：生成器写法（更常用）

from contextlib import contextmanager

@contextmanager
def timer(label):
    start = time.perf_counter()
    try:
        yield                              # yield 之前 = __enter__；之后 = __exit__
    finally:                               # 用 finally 确保异常时也能执行清理
        print(f"{label}: {time.perf_counter() - start:.3f}s")

with timer("检索"):
    ...

⚠️ 不写 try/finally，with 块里出异常时清理代码就不会执行。

4.3 常见用途

5. 练习

uv run pytest tests/test_ex05_iter_deco_ctx.py

6. 自测题

1. 可迭代对象和迭代器的区别？为什么迭代器只能遍历一次？
2. 调用生成器函数时，函数体执行了吗？
3. 写一个装饰器需要几层函数？带参数的呢？
4. 不加 functools.wraps 会有什么问题？举一个会出 bug 的场景。
5. @contextmanager 里为什么要用 try/finally 包住 yield？
6. __exit__ 返回 True 意味着什么？

06 · 类型提示（typing）

目标：看懂并写出现代 Python 类型提示。在 Agent 开发里，类型提示会在运行时被读取：FastAPI 靠它解析请求，LangChain 靠它生成工具 schema，LangGraph 靠它定义状态。 练习：exercises/ex06_typing.py · 测试：uv run pytest tests/test_ex06_typing.py 建议用时：4 小时

1. 为什么要写类型提示

def call_tool(name, args):          # args 是什么？返回什么？
    ...

def call_tool(name: str, args: dict[str, object]) -> str:   # 一目了然
    ...

类型提示本身不会在运行时做检查：def f(x: int) 传入字符串照样能跑。要做校验得靠 Pydantic（第 07 课）。

2. 基础语法（3.10+ 写法）

name: str = "agent"
count: int = 0
ratio: float = 0.5
enabled: bool = True

tags: list[str] = []
scores: dict[str, float] = {}
point: tuple[int, int] = (1, 2)
values: tuple[int, ...] = (1, 2, 3)   # 任意长度
unique: set[str] = set()

maybe: str | None = None              # 可能为 None（旧写法 Optional[str]）
id_: int | str = 1                    # 多种类型之一（旧写法 Union[int, str]）

def greet(name: str, times: int = 1) -> str: ...
def log(msg: str) -> None: ...        # 无返回值

老代码里会看到 from typing import List, Dict, Optional, Union，在 3.9+ 都可以用内置的 list、dict、X | None 替代。

抽象容器类型：参数尽量宽，返回尽量窄

from collections.abc import Iterable, Sequence, Mapping, Callable, Iterator

def total(nums: Iterable[int]) -> int:      # 接受 list、tuple、set、生成器……
    return sum(nums)

def first(items: Sequence[str]) -> str:     # 需要下标访问时用 Sequence
    return items[0]

3. Any、object 与类型别名

from typing import Any

def dump(data: Any) -> str: ...      # Any：放弃检查，什么都行
def show(data: object) -> str: ...   # object：什么都能传，但使用前要先判断类型

type JSON = dict[str, Any]           # 类型别名（3.12+ 语法）
type Messages = list[dict[str, str]]

4. Literal：限定取值

from typing import Literal, get_args

Role = Literal["system", "user", "assistant", "tool"]

def add_message(role: Role, content: str) -> None: ...

add_message("user", "hi")       # OK
add_message("admin", "hi")      # mypy 报错（运行时不会）

get_args(Role)                  # ('system', 'user', 'assistant', 'tool') 运行时取出所有值

5. TypedDict：给字典定结构

LLM 的消息、API 的 JSON 本质都是字典，TypedDict 给它们加上字段类型：

from typing import TypedDict, NotRequired

class Message(TypedDict):
    role: Literal["system", "user", "assistant", "tool"]
    content: str
    name: NotRequired[str]        # 可选字段

msg: Message = {"role": "user", "content": "hi"}   # 运行时就是普通 dict

Agent 关联：LangGraph 的状态最常见的定义方式就是 TypedDict：

from typing import Annotated
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]   # Annotated 附加"合并规则"
    intent: str

Annotated[类型, 额外信息] 给类型附加元数据，框架在运行时读取。FastAPI 的 Annotated[str, Query(max_length=50)] 也是同一个机制。

6. Callable：函数类型

from collections.abc import Callable

Handler = Callable[[str, int], bool]          # 接收 (str, int)，返回 bool
AnyTool = Callable[..., str]                  # 任意参数，返回 str

def register(name: str, func: Callable[..., str]) -> None: ...

7. 泛型：让类型"可以填空"

需求：first(items) 传入 list[int] 返回 int，传入 list[str] 返回 str。

# 3.12+ 新语法：方括号里声明类型变量
def first[T](items: Sequence[T]) -> T:
    return items[0]

first([1, 2])      # 类型检查器知道结果是 int
first(["a"])       # 知道结果是 str

class Box[T]:
    def __init__(self, item: T):
        self.item = item
    def get(self) -> T:
        return self.item

Box[int](1)

旧写法（老代码里大量出现，要能看懂）：

from typing import TypeVar, Generic

T = TypeVar("T")

def first(items: Sequence[T]) -> T: ...

class Box(Generic[T]): ...

8. Protocol：结构化类型（鸭子类型）

上一课讲过：不需要继承，只要有对应的方法就符合类型。

from typing import Protocol

class ChatModel(Protocol):
    def invoke(self, prompt: str) -> str: ...

class FakeModel:                     # 没有继承 ChatModel
    def invoke(self, prompt: str) -> str:
        return "fake"

def run(model: ChatModel) -> str:
    return model.invoke("hi")

run(FakeModel())                     # 类型检查通过

9. 运行时读取类型：框架是怎么做的

这一节是本课的重点。LangChain 的 @tool 能把一个普通函数变成 LLM 可调用的工具，核心就是读函数签名和类型提示，生成 JSON Schema。

import inspect
from typing import get_type_hints

def get_weather(city: str, days: int = 1) -> str:
    """查询城市天气。"""
    ...

sig = inspect.signature(get_weather)
for name, param in sig.parameters.items():
    print(name, param.default is inspect.Parameter.empty)
# city True     ← 没有默认值 = 必填
# days False

get_type_hints(get_weather)
# {'city': <class 'str'>, 'days': <class 'int'>, 'return': <class 'str'>}

inspect.getdoc(get_weather)   # '查询城市天气。'

把这些信息拼起来，就得到 LLM 工具调用需要的 schema：

{
  "name": "get_weather",
  "description": "查询城市天气。",
  "parameters": {
    "type": "object",
    "properties": {"city": {"type": "string"}, "days": {"type": "integer"}},
    "required": ["city"]
  }
}

练习里你会亲手实现这个转换，以及一个简化版的工具箱 ToolBox。

泛型类型的运行时拆解

from typing import get_origin, get_args

get_origin(list[str])         # <class 'list'>
get_args(list[str])           # (<class 'str'>,)
get_origin(dict[str, int])    # <class 'dict'>
get_origin(str)               # None

10. 用 mypy 做静态检查

uv run mypy exercises/ex06_typing.py

常见报错及含义：

不必追求 100% 类型覆盖。函数签名必写，局部变量能推断出来的就不写。

11. 练习

ToolBox 就是一个微缩版的 Agent 工具层：注册工具 → 导出 schema 给 LLM → 根据 LLM 返回的工具名和参数执行。

uv run pytest tests/test_ex06_typing.py
uv run mypy exercises/ex06_typing.py

12. 自测题

1. 类型提示会在运行时检查参数类型吗？哪些库会在运行时用到类型提示？
2. Optional[str] 和 str | None 是什么关系？
3. TypedDict 和 dataclass 的区别？
4. 泛型解决了什么问题？
5. 描述一下"函数 → 工具 schema"的转换过程。为什么函数的 docstring 对 Agent 很重要？

07 · Pydantic

目标：用 Pydantic 校验一切"外部输入"。在 Agent 开发里，它负责 FastAPI 的请求/响应、工具参数 schema、LLM 结构化输出、配置管理。 练习：exercises/ex07_pydantic.py · 测试：uv run pytest tests/test_ex07_pydantic.py 建议用时：4 小时 文档：docs.pydantic.dev（本课基于 Pydantic v2）

1. 为什么需要 Pydantic

类型提示在运行时不做检查；dataclass 也不检查。但外部数据（HTTP 请求、LLM 输出、配置文件）随时可能是错的。

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    email: str | None = None

User(id="42", name="张三")          # id="42" 被自动转换成 42
User(id="abc", name="张三")         # ValidationError: id 不是合法整数

2. 定义模型

from typing import Literal
from pydantic import BaseModel, Field

class ChatRequest(BaseModel):
    message: str = Field(min_length=1, max_length=4000)
    model: Literal["claude-sonnet", "claude-haiku"] = "claude-sonnet"
    temperature: float = Field(default=0.7, ge=0, le=1)        # ge: >=, le: <=
    max_tokens: int = Field(default=1024, gt=0)                # gt: >
    tags: list[str] = Field(default_factory=list)              # 可变默认值用 default_factory
    session_id: str | None = None

常用 Field 参数：

嵌套模型

class ToolCall(BaseModel):
    name: str
    arguments: dict[str, object]

class AssistantMessage(BaseModel):
    content: str
    tool_calls: list[ToolCall] = Field(default_factory=list)

AssistantMessage.model_validate({
    "content": "",
    "tool_calls": [{"name": "search", "arguments": {"q": "天气"}}],   # 自动转成 ToolCall 对象
})

3. 创建、校验与导出

# 创建
req = ChatRequest(message="hi")
req = ChatRequest.model_validate({"message": "hi"})            # 从 dict
req = ChatRequest.model_validate_json('{"message": "hi"}')     # 从 JSON 字符串（更快）

# 导出
req.model_dump()                       # → dict
req.model_dump(exclude_none=True)      # 去掉值为 None 的字段
req.model_dump(include={"message"})    # 只要部分字段
req.model_dump_json()                  # → JSON 字符串

# 复制并修改
req2 = req.model_copy(update={"temperature": 0})

4. 处理校验错误

from pydantic import ValidationError

try:
    ChatRequest(message="", temperature=2)
except ValidationError as e:
    print(e.error_count())    # 2
    for err in e.errors():
        print(err["loc"], err["msg"], err["type"])
    # ('message',) String should have at least 1 character string_too_short
    # ('temperature',) Input should be less than or equal to 1 less_than_equal

loc 是出错字段的路径，嵌套时是多段，比如 ('tool_calls', 0, 'name')。

Agent 关联：LLM 生成的结构化输出不合法时，常见做法是把 e.errors() 整理成文字喂回给 LLM 让它重试。练习里的 collect_errors 就是干这个的。

5. 自定义校验器

字段校验 field_validator

from pydantic import field_validator

class ApiCase(BaseModel):
    method: str
    url: str

    @field_validator("method", mode="before")   # before：在类型转换之前运行，拿到原始输入
    @classmethod
    def upper_method(cls, v):
        return v.upper() if isinstance(v, str) else v

    @field_validator("url")                     # 默认 after：类型转换之后运行
    @classmethod
    def check_url(cls, v: str) -> str:
        if not v.startswith(("http://", "https://")):
            raise ValueError("url 必须以 http:// 或 https:// 开头")   # 抛 ValueError 即可
        return v                                                    # 必须返回值！

模型校验 model_validator：字段之间的约束

from pydantic import model_validator

class DateRange(BaseModel):
    start: int
    end: int

    @model_validator(mode="after")
    def check_order(self):
        if self.end < self.start:
            raise ValueError("end 不能早于 start")
        return self          # after 模式返回 self

⚠️ 忘记 return 是最常见的错误——字段会变成 None。

6. JSON Schema：给 LLM 看的"说明书"

class WeatherArgs(BaseModel):
    """查询天气"""
    city: str = Field(description="城市名，如 北京")
    days: int = Field(default=1, ge=1, le=7, description="预报天数")

WeatherArgs.model_json_schema()

{
  "title": "WeatherArgs",
  "description": "查询天气",
  "type": "object",
  "properties": {
    "city": {"title": "City", "description": "城市名，如 北京", "type": "string"},
    "days": {"title": "Days", "description": "预报天数", "type": "integer",
             "default": 1, "minimum": 1, "maximum": 7}
  },
  "required": ["city"]
}