Stage 3 — 工具使用与第一个 Agent（Tool Use & Hello Agent）⭐¶
⏱ 时间估算：2-3 周（约 10-20 小时）
💡 用语密集（agent / tool use / function calling / ReAct / structured output⋯）→ 翻
resources/glossary.md2。 🗺️ 进 Track A（CLI Power User）还是 Track B（Agent Builder）前，先看resources/agent-paradigms.md— 5 种 agent 型态的全景图，帮你选轨。📋 本章组成：〔开场框景：AI/LLM/Agent 三者关系〕→ 学习目标 → 进入条件 → 必修阅读 →〔可选 · 概念地图〕→ 动手练习 → 反思（概念 + 路由）→ 精选 Projects → 自我检查 🔑 关键名词：见
resources/glossary.md2
🤖 开始前：AI / LLM / Agent — 三者怎么分？¶
本节是“开场框景”（由大到小 pedagogy）：先把学习者脑中的 mental hierarchy 建好，再进 学习目标、练习。这节只做简短说明 + 对照，深度入门读物已经是中英文圈各自的 canonical reference（即“最公认的标准参考”、见下方资源）。不是重写 hello-agents Ch1。
一张阶层图先建立认知¶
→ “Agent”不是“比 LLM 更厉害的模型”，也不是 LLM 树状分类底下的一个分支。Agent 是个跨层抽象的系统，把 LLM 当作其中一个组件来用。Cursor / Claude Code / Hermes Agent 内部都还是同一批 LLM（Claude / GPT / Gemini）—— 差别是怎么把 LLM 包进工具调用循环里。
三行对照（最快版）¶
| 词 | 是什么 | 你给它什么、它回什么 | 例子 |
|---|---|---|---|
| AI | 整个学科 | 太抽象、不能直接“用” | ML、DL、LLM、RL 都是 AI 子领域 |
| LLM | 把文字映射到文字的单一模型 | 给 prompt → 回字 | GPT-5、Claude、Llama 3、Qwen |
| Agent | LLM + 工具 + loop 的系统 | 给任务 → 自己跑多步骤达成 | Cursor、Claude Code、Hermes Agent |
一句话：LLM 像一个理解并生成文字的大脑；Agent 则是把这个大脑接上工具、工作流与反馈回路后，能够作为系统完成多步骤任务的东西。
Agent 的 3 个最小必要部件（这就是 agent vs LLM 的核心差别）¶
| 部件 | 角色 | 在哪学 |
|---|---|---|
| 🧠 LLM（brain） | 推理 / 决策 / 自然语言 | Stage 1 已学 |
| 🔧 Tools（hands） | 对世界做事（call API、跑 code、查数据） | 本 stage |
| 🔁 Loop（heartbeat） | 想 → 做 → 看结果 → 再想（ReAct） | 本 stage 练习 3 |
→ 这 3 个合在一起就是 agent 的最低定义。没有 tools / loop，那只是“LLM + 你写 retry”，不算 agent。
Agent 的经典范式（thinking patterns）¶
学完最小 3 部件后、下一层是“LLM 怎么想”。hello-agents Ch4“智能体经典范式构建”整章在讲这个。简短对照：
| 范式 | 是什么 | 在哪学 |
|---|---|---|
| CoT（Chain-of-Thought、思维链） | LLM 写出推理过程再给答案、不只给结论——是个 prompting 技巧、不是 agent 结构 | Stage 2 学习目标 + 动手练习（推理任务 CoT） |
| ReAct（Reasoning + Acting） | 在 Loop 里套 CoT：Thought（想）→ Action（调用 tool）→ Observation（看结果）→ Thought ...，是 Loop 部件最常见的实现 | 本 stage 练习 3 + ReAct paper (Yao 2022) |
| Reflection | 跑完一轮后让 LLM 批改自己、根据 feedback 重答 | 本 stage 反思（concept + 路由） |
| Planning（任务分解） | 把大任务拆成子任务、可分给多个 agent 各做 | Stage 4 什么是 multi-agent framework |
→ 这些范式都是“LLM 自我引导”的不同变化、堆叠在 3 部件（LLM + Tools + Loop）之上。“Agent 是什么”用 3 部件就讲完了；“Agent 怎么想”需要这 4 个范式才讲得完整。
💡 延伸组件（agent 变强的 infrastructure、但不是“是不是 agent”的判准）： - 记忆 / RAG（agent 能跨对话记住东西）→ Stage 6 完整教 - 反思 / self-critique（agent 看自己答案、发现问题、回头改）→ 基本版见 本 stage 反思（concept + paper routing）；带持久 memory 的进阶版见 Stage 6 Reflexion with Memory - Production harness（telemetry / safety / retry / orchestration）→ Stage 5 5.6
这些都是 advanced pattern——Stage 3 教最小可行 agent、后面 stage 教怎么变强。
📚 深度入门资源（中英文 / 影片优先）¶
🀄 中文： 1. 李宏毅 — 生成式 AI 导论（2024 春台大课程） ⭐⭐⭐ — 中文圈最高质量的 AI / LLM / agent 学术级导论。每集 30-60 分钟、台大授课、官方页含投影片 + YouTube 链接。LLM / agent 概念都涵盖。最新整合版见 GenAI-ML 2025 秋、YouTube 主频道 @HungyiLeeNTU 2. datawhalechina/hello-agents Ch1“初识智能体” ⭐ — 文字版最完整中文 agent 导论 3. datawhalechina/hello-agents Ch2“智能体发展史” — BabyAGI → AutoGPT → Claude Code 演化脉络 4. 3Blue1Brown 中文配音版 — LLM / Transformer 视觉化解说（中文配音）
🇺🇸 English： 1. Andrej Karpathy — "Intro to Large Language Models" ⭐⭐⭐（1hr）— LLM 从零开始 visual intro（ex-OpenAI / ex-Tesla AI Director、英文圈最重视的 LLM 入门影片） 2. Andrej Karpathy — "Let's build GPT from scratch" ⭐⭐（2hr）— 想看 LLM 内部到代码级的人 3. 3Blue1Brown — "But what is a Transformer?" ⭐⭐⭐ — visual 解释 LLM，英文圈最被推荐的视觉化教材 4. Lilian Weng — "LLM Powered Autonomous Agents" ⭐⭐⭐ — canonical 1-page agent anatomy（Planning / Memory / Tool use / Action）、英文圈被引用最多的 agent 解剖文 5. Anthropic — "Building Effective Agents" ⭐ — Anthropic 观点：何时该用 agent、何时 workflow 就够 6. Chip Huyen — "Agents" — practitioner 视角，full chapter 级深度
选读 / 进阶补充： - Simon Willison — "I think 'agent' may finally have a widely enough agreed upon definition" — working definition：“agent runs tools in a loop to achieve a goal”、含对照 OpenAI 等不同定义的争议（给已有基础的人） - DeepLearning.AI Short Courses：“AI Agents in LangGraph”/“Multi AI Agent Systems with crewAI”/“Functions, Tools and Agents with LangChain”（API 多数是 2023-2024 旧版、看概念为主、写 code 对照官方最新 docs） - microsoft/ai-agents-for-beginners — 微软官方 12 课 build-agent 入门（MIT、★ 64k+）。结构化、英文、含 code；适合想要一条平行入门课对照的人，不是本 stage 动手练习的替代 - liyupi/ai-guide — 中文圈最大 AI 资源聚合型 repo（不是原创教材、适合广度延伸）
📌 资源清单上限规则：本 section 是 router 不是 tutorial。主清单合计上限 10 条（中 4 + 英 6），要加新资源前必须先移除一条。选读区不计入主清单上限。
💡 推荐学习路径：先看 1-2 个影片（中：李宏毅、英：Karpathy / 3Blue1Brown）建立 visual mental model → 再读 1-2 个 blog（Lilian Weng / Anthropic）拿到 working definition → 再回本 stage 动手练习。不必全部看完，这是 reference library 不是 reading list。
这是整个学习路线最关键的一站。你建过一个 agent 才算真懂 agent——本 stage 的基础练习建议至少实际手写一次、再依需求往 hello-agents 或本 stage 精选 projects 找深度教材。
📌 学习目标¶
完成这个 stage 后你会： - 讲得出为什么 LLM 需要 tools（它不是万能的，而且文字以外的事它都做不了） - 定义一个 tool schema，并让 LLM 调用它 - 从零（不靠任何 framework）写出一个单步 ReAct agent - 写出多步 ReAct agent，并让它自己判断何时该停 - 分得出哪种问题该用 tool use、哪种纯 prompt 就够
🚪 进入条件¶
你应该已经： - 有可以跑的 Claude / OpenAI / Gemini API 权限（Stage 1） - 对 prompt engineering 基础已经上手（Stage 2） - 能写一个吃 JSON 进、吐 JSON 出的 Python 函数
📚 必修阅读¶
- Anthropic — Tool Use — 官方指南
- anthropics/courses — Tool Use ⭐⭐⭐⭐⭐ ★ 21k+ — Anthropic 官方 5 course umbrella、module 5“Tool Use”对应本 stage。Jupyter notebook 互动式练习、含 multimodal prompts / streaming / tool 实作 walk-through。
- ReAct: Synergizing Reasoning and Acting in Language Models — Yao et al. 2022，奠基论文。至少读 abstract 跟 Section 3。
- OpenAI — Function Calling — function calling 格式参考
- Build an agent from scratch — 从零打造 agent 的故事式导览
🛠 动手练习（基础 illustrative 练习）¶
🦙 本 stage 默认用 Ollama qwen2.5:3b（成本考量、tool-use 支持稳定）。Stage 3 进到 tool calling / ReAct loop、
gemma4:e4b不够、改用qwen2.5:3b（1.9 GB、ollama pull qwen2.5:3b即装）。每个练习都有 Path A（Ollama、默认）+ Path B（Anthropic、选择性、想看 cloud 高质量 tool-use 时用）。💰 Stage 3 预算估算（全 6 练习、tool use 较重）：全本机 = $0、全 haiku ≈ $0.50、全 sonnet ≈ $1.50。ReAct loop 练习单次 4-6 tool calls × 5 练习 × 5 reps ≈ $0.80 haiku。完整预算见
examples/README.md#推荐-llm-清单。完整 3 路 trade-off 见
examples/README.md。🆘 卡住了？ Tool calling 是整个 curriculum 最陡的学习曲线。装
examples/stage-5/tool-calling-tutor/skill——当你 prompt Claude Code“为什么 LLM 不调用我的 tool”、“我这 schema 哪里写坏”会自动加载、走 4-symptom 诊断流程。🪜 本 stage 是 single-agent 起点：一个 LLM + ReAct loop。Multi-agent 概念（多个 agent 协作）入门看 Stage 4 什么是 multi-agent framework、Claude 原生 subagent 机制（
.claude/agents/+ Task tool、不需 framework）看 Stage 5.5。
练习 1：Function Calling（一个工具、一次调用）¶
给 Claude 一个工具（假的天气 API）跟一个问题（“台北现在有下雨吗？”）。看 Claude 怎么调用工具、拿到结果、再回答你。
📋 起手码 — Path A（本机 Ollama qwen2.5:3b、默认）（复制到 practice_1.py）
# 需要：pip install openai
# 前置：ollama pull qwen2.5:3b && ollama serve
# Note: Stage 3+ 用 qwen2.5:3b（tool-use 稳定）、不是 gemma4:e4b
import sys, json
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
# Step 1: 定义 tool schema — OpenAI-compatible 格式包一层 {"type":"function", "function":{...}}
weather_tool = {
"type": "function",
"function": {
"name": "get_weather",
"description": "查询城市目前天气（晴/雨/阴），回传一个短字符串。",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称（如「台北」）"},
},
"required": ["city"],
},
},
}
# Step 2: 问问题、让 LLM 自己决定要不要调用 tool
resp = client.chat.completions.create(
model="qwen2.5:3b",
max_tokens=512,
tools=[weather_tool],
messages=[{"role": "user", "content": "台北现在有下雨吗？"}],
)
# === 自我验证 ===
msg = resp.choices[0].message
print("finish_reason:", resp.choices[0].finish_reason)
print("tool_calls:", msg.tool_calls)
assert msg.tool_calls, "预期 LLM 会选择调用 tool（而非直接回答）"
tc = msg.tool_calls[0]
assert tc.function.name == "get_weather", f"预期调用 get_weather、实际 {tc.function.name}"
args = json.loads(tc.function.arguments)
assert args.get("city"), "预期 city 参数有值"
print(f"✅ 练习 1 通过 — qwen2.5:3b 正确选了 get_weather、带 city='{args['city']}' 参数")
finish_reason: tool_calls
tool_calls: [ChatCompletionMessageToolCall(id='call_xxx', function=Function(name='get_weather', arguments='{"city": "台北"}'), type='function')]
✅ 练习 1 通过 — qwen2.5:3b 正确选了 get_weather、带 city='台北' 参数
📋 起手码 — Path B（Anthropic API、选择性）（复制到 practice_1_anthropic.py）
# 需要：pip install anthropic
# 环境变量：export ANTHROPIC_API_KEY=sk-ant-...
import anthropic
client = anthropic.Anthropic()
# Anthropic native tool schema — 不用包 wrapper
weather_tool = {
"name": "get_weather",
"description": "查询城市目前天气（晴/雨/阴），回传一个短字符串。",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称（如「台北」）"},
},
"required": ["city"],
},
}
resp = client.messages.create(
model="claude-haiku-4-5",
max_tokens=512,
tools=[weather_tool],
messages=[{"role": "user", "content": "台北现在有下雨吗？"}],
)
# === 自我验证 ===
assert resp.stop_reason == "tool_use", f"非预期 stop_reason: {resp.stop_reason}"
tool_calls = [b for b in resp.content if b.type == "tool_use"]
assert tool_calls[0].name == "get_weather"
assert tool_calls[0].input.get("city")
print(f"✅ 练习 1 通过（Anthropic）— Claude 选了 get_weather、city='{tool_calls[0].input['city']}'")
练习 2：多工具选择¶
给 Claude 三个工具（搜索、计算器、日历）跟一个任务。看 Claude 怎么挑工具，顺便注意它什么时候会挑错。
📋 简化版核心观念 — Path A (Ollama)
**NEW vs 练习 1**：tools 从 1 个变 3 个。LLM 看 `description` 边界决定挑哪个——`description` 写得越像“给人读的 docstring”、越容易挑错。from openai import OpenAI
import json
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
TOOLS = [
{"type": "function", "function": {"name": "web_search",
"description": "Search current or external info not in the prompt.",
"parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}},
{"type": "function", "function": {"name": "calculator",
"description": "Evaluate basic arithmetic with +, -, *, /, parentheses.",
"parameters": {"type": "object", "properties": {"expression": {"type": "string"}}, "required": ["expression"]}}},
{"type": "function", "function": {"name": "calendar_lookup",
"description": "Look up events for a specific date.",
"parameters": {"type": "object", "properties": {"date": {"type": "string"}}, "required": ["date"]}}},
]
resp = client.chat.completions.create(model="qwen2.5:3b", tools=TOOLS,
messages=[{"role": "user", "content": "What is (19 * 42) - 8?"}])
tc = resp.choices[0].message.tool_calls[0]
print(f"LLM 挑了: {tc.function.name}, args: {json.loads(tc.function.arguments)}")
# 预期：calculator, {"expression": "(19 * 42) - 8"}
→ 基础 starter 范本 → examples/stage-3/02-multi-tool-selection/（starter.py 含 stub + 简单 test，illustrative，不是 chapter-length 完整教程；深度章节见 stage 开头 📚 hello-agents callout）
练习 3：从零实现 ReAct（不用 framework）¶
用 50-80 行 Python 把 Thought → Action → Observation 循环写出来。不要 LangChain、不要 LangGraph，就是纯 while not done: thought; action; observation; ...。
📋 简化版核心观念 — Path A (Ollama)、ReAct loop 的全部就在这 13 行
**NEW vs 练习 2**：把单次 call 包进循环、`messages` 一直长、看 `tool_calls` 在不在来决定收尾。# 假设 TOOLS + TOOL_IMPL（dict: name → callable）已经像练习 2 一样定义好
messages = [{"role": "user", "content": "台北人口除以纽约人口？"}]
for step in range(5): # max_iter safety net
r = client.chat.completions.create(model="qwen2.5:3b", tools=TOOLS, messages=messages)
msg = r.choices[0].message
# 把 assistant response 接回 messages（重要！下轮 LLM 才看得到自己上轮讲什么）
messages.append({"role": "assistant", "content": msg.content, "tool_calls": msg.tool_calls})
if not msg.tool_calls:
print(f"✅ 收尾：{msg.content}"); break
for tc in msg.tool_calls:
args = json.loads(tc.function.arguments)
obs = TOOL_IMPL[tc.function.name](args) # 本地执行
# observation 接回 messages（用 role="tool"、配 tool_call_id）
messages.append({"role": "tool", "tool_call_id": tc.id, "content": obs})
→ 基础 starter 范本 → examples/stage-3/03-react-from-scratch/（含 mock-based test.py、不花 API 钱也能验；illustrative，不是 chapter-length 完整教程——深度章节见 stage 开头 📚 hello-agents callout）
练习 4：多步骤推理任务¶
一个需要连续调用 3-5 次 tool 的任务。例如：“找出台北人口，除以纽约人口，再把比例换成百分比。”每一步用不同的工具。
📋 简化版核心观念 — 跟练习 3 同一个 loop、跑久一点而已
**NEW vs 练习 3**：**完全同一个 loop**——只是 `TOOLS` 换成 4 个（`lookup_population` / `divide` / `to_percentage` / `round_int`）、题目自然走完 4 轮 tool call 才收尾。# 没有新 code、纯粹是 TOOLS / TOOL_IMPL 换内容
TOOL_IMPL = {
"lookup_population": lambda i: lookup_population(i["city"]),
"divide": lambda i: divide(i["a"], i["b"]),
"to_percentage": lambda i: to_percentage(i["ratio"]),
"round_int": lambda i: round_int(i["x"]),
}
# loop 完全照 练习 3，只是 max_iter 拉大到 8
→ 基础 starter 范本 → examples/stage-3/04-multi-step-reasoning/（starter.py 含 stub + 简单 test，illustrative，不是 chapter-length 完整教程；深度章节见 stage 开头 📚 hello-agents callout）
练习 5：错误处理¶
让某个工具失败（网络错误、输入无效）。看看 agent 会怎么处理错误、能不能恢复，再加上 retry 机制。
📋 简化版核心观念 — tool error 是 data、不是 exception
**NEW vs 练习 4**：tool error 回传**结构化 dict**、不要 `raise`。loop 把 dict 接回 LLM、模型自己决定 retry / 改 query / 放弃。def fetch_weather(city: str) -> dict:
if network_failed():
return {"error": "network timeout", "retry_hint": "try again in 1s"}
return {"city": city, "forecast": "rain", "temperature_c": 24}
# loop 里：
obs = fetch_weather(args["city"])
messages.append({"role": "tool", "tool_call_id": tc.id,
"content": json.dumps(obs, ensure_ascii=False)}) # error dict 也是 string 化接回去
# 下一轮 LLM 看到 retry_hint、可能会 retry、可能会放弃、可能会改 query
→ 基础 starter 范本 → examples/stage-3/05-error-handling/（starter.py 含 stub + 简单 test，illustrative，不是 chapter-length 完整教程；深度章节见 stage 开头 📚 hello-agents callout）
练习 6：Function schema 设计（坏 schema 修到好）¶
先给 LLM 一份故意写烂的 schema——description 模糊（“处理数据”）、参数全用 type: string、没分 required / optional、enum 该用没用。观察 LLM 怎么选错 tool、传错参数。然后逐项修：
- description 写到 LLM 一眼就懂这个 tool 适用情境（不是写给人读的 docstring）
- parameters 用对 type（number / boolean / enum / array），required 列清楚
- 模糊边界用 enum 强制收敛（例如 unit: "celsius" | "fahrenheit" 而不是 unit: string）
- error 回传要包 {"error": "...", "retry_hint": "..."} 让 LLM 能恢复
💡 详细 cheatsheet 看
resources/schema-design-cheatsheet.md——5 条黄金规则 + 5 个常见 anti-pattern。
📋 简化版核心观念 — bad vs good schema 对照
**NEW vs 练习 5**：同一个工具（温度转换）、两种 schema 写法。看 4 个差别。# ❌ BAD — qwen2.5:3b 几乎必错（Claude haiku 还能猜对、但几率明显下降）
{"name": "convert", "description": "Convert a value.",
"parameters": {"type": "object", "properties": {
"value": {"type": "string"}, "unit": {"type": "string"}}}}
# ✅ GOOD — qwen 也能稳定挑对
{"name": "convert_temperature",
"description": "Use when user asks to convert temperatures between Fahrenheit and Celsius.",
"parameters": {"type": "object", "properties": {
"value": {"type": "number", "description": "Temperature value"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}},
"required": ["value", "unit"]}}
→ 基础 starter 范本 → examples/stage-3/06-schema-design/（含 bad schema vs good schema 两个版本对照；illustrative，不是 chapter-length 完整教程——深度章节见 stage 开头 📚 hello-agents callout）
🪞 反思（Reflexion / Self-Refine）— 概念 + 路由¶
本节是 concept + routing、不是练习。没有 verified working solution、不挂“练习 N”label、不给 success criteria——遵守本 repo“没验证答案不写练习、顶多 routing”原则。想动手做？直接读下方 paper / project。
反思是什么：练习 5 的 error handling 是“LLM 出错 → 你（外部）catch + retry”；反思是“LLM 观察自己出错 → 自己改”。差别是 agency 在哪一边——这是 production agent（Cursor / Cline / Claude Code）每天都在跑的循环。
为什么这节在 Stage 3 而不是 Stage 6：反思在学术（Reflexion paper Shinn 2023、Self-Refine Madaan 2023）跟 production（Cursor / Claude Code）上都被归类在 planning / reasoning loop 机制——是 ReAct（练习 3）的 sibling pattern，不是 memory pattern。同样是 LLM 自我引导的多轮循环，只是“下一轮要做什么”从“调用 tool”换成“批改自己”。
进阶版（带 persistent memory 的 Reflexion 完整版）→ Stage 6 进阶：带持久记忆的 Reflexion 完整版——当反思要跨 session、把过去失败存起来当下一轮 context，这个版本才真的需要 memory 层。
一张对照图¶
| Pattern | 形式 | 需要 memory？ | 在哪学 |
|---|---|---|---|
| Error handling（练习 5） | 外部 catch + retry | 不需 | 本 stage 练习 5 |
| ReAct loop（练习 3） | LLM → tool → 结果 → LLM | 不需 | 本 stage 练习 3 |
| 基本反思 / Self-Refine | Actor → Critic → Actor，single session | 不需 | 本节 routing（下方） |
| 完整 Reflexion（含 episodic memory） | 上面 + 把失败反思存起来、跨 session 累积 | 需要 | Stage 6 进阶：Reflexion with Memory |
📚 想动手 / 想深入？直接读这些¶
Paper： - Reflexion (Shinn et al. 2023) ⭐ — 原 paper，定义“verbal reinforcement learning” - Self-Refine (Madaan et al. 2023) — single-agent self-critique，是“基本反思”的学术定义
Reference 实现： - arunpshankar/react-from-scratch — 已在本 stage 精选 Projects 列出，含 Reflection 实现可直接读 - LangChain — Reflection Agents（blog） — framework 实现参考 + 完整 working notebook - datawhalechina/hello-agents — 对应章节（自我反思 / Self-Refine 段落、中文完整教学）
💡 想看反思怎么长进 production agent：Stage 5 5.6 Harness Internals 解剖 Claude Code source 时可以看到——agent 跑完 tool call 后自我评估 patch、有问题回头改、修正后再 commit。这是现代 production agent 的核心 building block 之一。
🎯 精选 Projects¶
按用途分 4 类、12 个项目一张表搞定。挑入口看“适合谁”、想深入点链接看 repo README。
| 分类 | Project | ⭐ | 适合谁 | 为什么推荐 / 备注 |
|---|---|---|---|---|
| 官方 cookbook （先看这个） |
Anthropic — Tool Use Cookbook | ⭐⭐⭐⭐⭐ | 练习 1 / 练习 2 入手 | 单工具 → 多工具 → parallel → structured output 全部 notebook（重点看 tool_use/customer_service_agent.ipynb） |
| Anthropic — Quickstarts | ⭐⭐⭐⭐⭐ | 练习 1/2 跑完想看“真的应用长什么样” | 3 个 deploy-ready 范本（financial / customer-support / computer-use）、★ 16k+。比社群实现更 canonical | |
| Anthropic — Building Effective Agents | ⭐⭐⭐⭐⭐ | 练习 3 写完、进 Stage 4 之前必读 | 部落格文章：何时用 agent vs workflow / 常见 pattern / 容易踩的坑——Anthropic 官方观念框架 | |
| 从零实现 ReAct （理解原理） |
pguso/ai-agents-from-scratch | ⭐⭐⭐⭐⭐ | 练习 3（从零写 ReAct） | 用本机 Ollama 从零打造、zero framework、章节结构好。最干净的“不靠 framework”参考实现 |
| arunpshankar/react-from-scratch | ⭐⭐⭐⭐ | 练习 3 替代（偏好 Gemini）+ 想看反思变体 | ReAct + Reflection + Self-consistency、Gemini 最佳化（⚠️ 2025-05 后更新放缓、Apache-2.0） | |
| mattambrogi/agent-implementation | ⭐⭐⭐ | 练习 3 卡住时逐行对照 | ~150 行最精简 ReAct（⚠️ 已停滞 2024-01、留作教学玩具参考） | |
| lsdefine/GenericAgent | ⭐⭐⭐⭐ | 练习 3/4，想看“精简但完整”framework | 自我演化 framework、~3K 行、★ 11k+、支持 Claude / Gemini / Kimi / MiniMax。介于玩具版与 LangGraph 之间 | |
| CodeAct 路线 （agent 写代码当 action） |
HuggingFace Smolagents | ⭐⭐⭐⭐ | 练习 5 替代方案、本地 LLM 实验 | ≤1000 LOC、CodeAct pattern 代表、★ 27k+。HF 立场：agent 应该要小 |
| QuantaLogic/quantalogic | ⭐⭐⭐ | 练习 3 后想比较 CodeAct vs JSON-tool | 另一条 CodeAct 路线、agent 直接写 Python 代码当 action、Apache-2.0 | |
| 中文章节式深度教材 （chapter-length） |
datawhalechina/hello-agents ⭐ 本 stage 推荐 | ⭐⭐⭐⭐⭐ | 中文读者想要结构化教学 + 完整覆盖 | 16 种能力含 tool use / ReAct / context engineering / sub-agents / circuit breaker / observability。中文圈最完整章节式（CC BY-NC-SA、非商用） |
| HelloAgents (jjyaoao) | ⭐⭐⭐⭐⭐ | 中文读者、想跑上面教材的 code | 上面教材 code repo、请切 learn_version 分支对齐章节（pip install hello-agents、CC BY-NC-SA） |
|
| Framework 对照 （看 framework 怎么藏掉 ReAct loop） |
LangChain — ReAct Agent Template | ⭐⭐⭐ | 练习 3 自己写完后在来 | LangGraph Studio 范本、framework 怎么把 ReAct 抽象化 |
💡 建议阅读路径：练习 1-2 跑 Anthropic Cookbook → 练习 3 跑 pguso/ai-agents-from-scratch → 练习 3 后读 Building Effective Agents → 中文章节式教材就 hello-agents + jjyaoao 配对 → 进 Stage 4 前看 LangChain ReAct template 对照 framework 抽象。
✅ 进 Stage 4 前的自我检查¶
你能不能： - [ ] 定义一个 tool schema（name + description + JSON schema 输入/输出） - [ ] 用不到 100 行 Python、不靠任何 framework，把 ReAct 循环写出来 - [ ] 解释为什么 agent 需要一个“我做完了”的退出条件 - [ ] 比较 CodeAct（代码即 action）跟 JSON-tool 两种路线 - [ ] 看出哪些问题其实不需要 agent
如果可以 → 进 Stage 4 — Agent Frameworks。
如果不行 → 把 练习 3 再跑一次，不要跳过。如果你不懂 framework 在帮你抽象什么，Stage 4 的那些东西看起来会像黑魔法。