datawhalechina/Agent-Learning-Hub

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。

Maintainer

Curated by 陈思州 (Datawhale 成员)

How To Use

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

What To Learn Now

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

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

Learning Todo List

Stage 0: Understand What An Agent Is

• 区分 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？」

Stage 1: Build A Minimal Agent Loop

• 会用一个 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，可以选择工具、执行工具、返回最终答案。

Stage 2: Learn Tool Use, RAG, And Memory

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

推荐阅读：

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

开源项目参考：

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

Stage 3: Study One Modern Agent Harness

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

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

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

Stage 4: Multi-Agent Is Coordination, Not Magic

• 理解 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。

Stage 5: Learn Skills, Protocols, And Capability Packaging

现代 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。

Stage 6: Browser And Computer-Use Agents

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

推荐阅读：

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

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

Stage 7: Evaluation, Observability, And Safety

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

推荐阅读：

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

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

Stage 8: Ship A Real Agent

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

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

Project Ladder

Curated Resources

Official Guides And Blogs

Project Map

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

Skills, Protocols, And Tooling

Modern Agent Systems

Legacy Or Optional Frameworks

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

Papers

GitHub Repositories

Thoughtful Blogs

Claude Code Study Path

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

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

Learning Principles

• 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.

Contributing

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.