datawhalechina/Agent-Learning-Hub

A curated AI Agent learning roadmap for people who want to build useful, reliable agents instead of collecting random links.

这个仓库只维护一个核心展示面：README。目标是把社区里优秀分享、官方博客、论文、开源项目和真实工程经验，整理成一份可以照着执行的 AI Agent 学习 todo list。

Curated by 陈思州 (Datawhale 成员)

• 如果你是新手：按「Learning Todo List」从上到下做，每完成一项就打勾。
• 如果你已经会 LLM 应用：从 Stage 2 或 Stage 3 开始，重点补 Agent loop、工具调用、评测和工程化。
• 如果你想做项目：直接看「Project Ladder」，每一档做一个可运行作品。
• 如果你只想找资料：看「Curated Resources」，优先读官方文档和经典论文。

Agent 领域变化很快。当前更值得投入的不是老式“角色扮演多 agent 框架”，而是这些更贴近真实生产力的方向：

不建议把精力重押在已经泛化成模板的老式 crew/role-play 框架上。它们可以了解，但不应成为主线。

• 区分 chatbot、workflow、agent、multi-agent。
• 理解 agent 的基本循环：observe -> think -> act -> observe。
• 明白什么时候不该用 agent：任务可预测、流程稳定、普通脚本能解决时，agent 反而增加不确定性。
• 读完 Anthropic: Building effective agents。
• 读完 OpenAI: A practical guide to building agents。

产出：写一页短笔记，回答「我的场景为什么需要 agent，而不是普通 workflow？」

• 会用一个 LLM API 完成普通对话。
• 会让模型输出结构化 JSON。
• 会定义一个工具函数，例如 search、calculator、read_file。
• 会解析模型的 tool call / function call。
• 会执行工具，并把工具结果喂回模型。
• 会给 agent loop 加最大步数、超时和错误处理。

推荐阅读：

• OpenAI Function Calling
• Gemini API Function Calling
• Claude Tool Use

产出：一个 50-150 行的最小 agent，可以选择工具、执行工具、返回最终答案。

• 会做检索增强生成：chunk、embed、retrieve、answer with citations。
• 会把搜索、数据库、文件、浏览器、代码执行接成工具。
• 会区分短期上下文、会话记忆、长期记忆。
• 会处理工具失败、空结果、重复调用、幻觉引用。
• 会让 agent 在回答里给出来源或证据。

推荐阅读：

• LlamaIndex Agents
• LangChain Docs
• Gemini API Code Execution
• Model Context Protocol

开源项目参考：

产出：一个资料研究助手，输入主题后自动搜索、筛选、总结并输出引用链接。

先选一个现代 agent 系统学深。这里的重点不是“框架 API 怎么调”，而是它如何组织工具、上下文、权限、状态、日志、子任务和反馈。

• 读懂一个 agent harness 的目录结构。
• 找出它的 agent loop、tool registry、permission gate、session store、context compaction。
• 跑通它的最小示例，并加一个你自己的工具。
• 观察一次完整 trace，解释每一步为什么发生。
• 把同一个任务分别用「裸 agent loop」和「harness」实现，对比差异。

产出：一个可调试的 agent harness demo，包含 README、运行步骤、示例输入输出和失败记录。

• 理解 planner / executor / reviewer / critic / router 等常见角色。
• 学会用 supervisor 或 graph 管理多 agent，而不是让 agent 随便聊天。
• 会定义每个 agent 的职责边界、输入输出 schema、停止条件。
• 会处理循环、争论、任务漂移、上下文膨胀。
• 会判断什么时候单 agent 更好。

推荐阅读：

• Claude Code Subagents
• Claude Code Hooks
• Google Agent Development Kit
• Agent2Agent Protocol
• Agent Client Protocol

产出：一个小型多 agent 系统，例如 research -> write -> review -> revise。

现代 agent 的能力不只来自模型和工具，也来自可复用的 skills。一个好的 skill 像一份小型操作手册：告诉 agent 什么时候使用、怎么使用、需要哪些脚本/资源、如何验证结果。

• 理解 Skill 和 Tool 的区别：tool 是可调用接口，skill 是可复用流程知识。
• 理解 Skill 和 Prompt 的区别：prompt 通常是一次性指令，skill 是可发现、可版本化、可分发的能力包。
• 理解 Skill 和 MCP 的区别：MCP 接入外部工具/数据源，skill 告诉 agent 如何完成一类任务。
• 阅读 Claude Code Skills 的文件结构和触发机制。
• 阅读 OpenClaw Skills 的加载、作用域和安全边界。
• 写一个最小 SKILL.md，包含 name、description、何时使用、步骤、验收标准。
• 给 skill 加一个脚本或模板文件，并说明 agent 什么时候才需要加载它。
• 给 skill 写一个 smoke test，验证它是否真的提升任务成功率。

推荐阅读：

• Claude Code Skills
• Claude Agent Skills
• Claude Code Agent SDK Skills
• OpenClaw Skills
• Model Context Protocol
• Agent2Agent Protocol
• Agent Client Protocol

产出：一个可复用 skill，例如 code-review、research-report、migration-helper、pdf-extraction 或 release-note-writer。

• 理解 browser agent 和普通 API tool 的区别。
• 会用 Playwright 或 browser-use 做网页观察和点击。
• 会给浏览器操作加安全限制：不登录敏感账号、不越权、不绕过平台规则。
• 会处理页面变化、弹窗、加载失败、元素定位失败。
• 会记录截图、DOM、动作日志，方便复盘。

推荐阅读：

• Claude Computer Use
• browser-use
• WebArena
• VisualWebArena

产出：一个只操作公开网页的 browser agent，例如打开网页、提取信息、生成摘要。

• 为 agent 准备固定测试集，而不是只看 demo。
• 记录成功率、失败原因、工具调用次数、成本、延迟。
• 会看 trace，知道失败发生在 prompt、工具、检索、模型还是状态管理。
• 给危险工具加人工确认，例如发邮件、删文件、付款、发布内容。
• 了解 prompt injection、data exfiltration、tool abuse 等风险。
• 会用回归测试防止 prompt 或工具改动后能力退化。

推荐阅读：

• OpenAI Evals
• OpenAI Agent platform
• LangSmith
• AgentBench
• SWE-bench

产出：一个 agent eval 表格，至少包含 20 个任务、期望结果、实际结果、失败分类。

• 有明确用户、明确任务、明确成功标准。
• 有日志、trace、错误重试、超时、成本上限。
• 有权限边界和人工确认机制。
• 有部署方式：CLI、Web app、Slack bot、GitHub Action 或后台任务。
• 有 README：怎么运行、怎么配置 key、怎么扩展工具、有哪些限制。

产出：一个别人能 clone 下来跑的 agent 项目。

项目不要按 star 数乱读，建议按学习目的分层：

这些项目仍有参考价值，但不建议作为当前学习主线。

Claude Code 是当前最值得拆解的 coding agent 产品之一。推荐按“官方文档 -> 复刻项目 -> 架构解析 -> 工程对照”的顺序学习：

• 读官方文档，理解 hooks、subagents、MCP、GitHub Actions、permissions。
• 读公开分析论文，抽象出 agent harness 的设计空间。
• 跟随 learn-claude-code 从零复刻核心机制。
• 对照 hello-agents、OpenClaw、Hermes Agent 这些开源项目，学习工程化实现。

• Build first, then read deeper.
• Prefer small reliable agents over impressive demos.
• Use tools with strict schemas.
• Add evals before you add more agents.
• Trace every important run.
• Treat multi-agent as a coordination problem.
• Keep humans in the loop for risky actions.
• Respect platform rules, copyrights, and data access boundaries.

Good contributions are welcome. Please prefer:

• official docs and official engineering blogs;
• high-quality papers and benchmarks;
• open-source repositories with runnable code;
• serious technical blogs with original insight;
• small projects that help learners practice one specific skill.

Please avoid:

• copied platform posts;
• course ads without substantial content;
• private or paywalled material;
• scraping-oriented content that bypasses platform rules.