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 框架”，而是这些更贴近真实生产力的方向：

| Priority | Learn | Why | | --- | --- | --- | | 1 | Claude Code / Codex-style coding agents | 真实代码库、shell、文件编辑、测试、权限、上下文压缩，是最好的 agent 工程样本。 | | 2 | Agent harness engineering | agent 的能力很大一部分来自 harness：工具协议、权限、状态、反馈、回放、CI、评测。 | | 3 | OpenClaw / Hermes-style personal agents | 长运行、本地优先、跨应用、记忆、skills、消息入口，更像“个人操作系统”。 | | 4 | Skills / MCP / A2A / ACP | skills 负责能力复用，MCP 连接工具，A2A 连接 agent，ACP 连接宿主应用。 | | 5 | Evaluation and safety | 没有 eval、trace、权限边界的 agent 只能算 demo。 |

不建议把精力重押在已经泛化成模板的老式 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

开源项目参考：

| Project | Why It Fits Stage 2 | | --- | --- | | GPT Researcher | 最接近“资料研究助手”的成品：搜索、抓取、筛选、引用、生成长报告。 | | Open Deep Research | LangGraph 写的 deep research 示例，适合学多轮搜索、状态管理和引用输出。 | | STORM | Stanford OVAL 的研究写作系统，适合学 outline、question asking、多视角资料综合。 | | Khoj | 个人 second brain，适合学本地文档、网页、语义搜索和长期记忆。 | | Onyx | 企业级 RAG/search assistant，适合学 connectors、hybrid search、权限和生产化。 | | AnythingLLM | 本地 RAG + agents 产品，适合初学者快速理解完整应用形态。 | | RAGFlow | 文档理解型 RAG 引擎，适合学 ingestion、chunking、retrieval、grounded answer。 | | mem0 | 记忆层组件，适合学如何给 agent 加长期 memory。 | | Letta | 面向 stateful agents 的 memory/context 平台，适合学上下文管理。 |

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

Stage 3: Study One Modern Agent Harness

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

| System | Best For | Learn This If You Want To | | --- | --- | --- | | Claude Code Docs | Coding agent product | 学真实 coding agent 的 CLI、工具、权限、hooks、subagents、MCP。 | | learn-claude-code | From-scratch agent harness | 从 0 到 1 复刻 Claude Code-like harness。 | | claw0 | From-scratch OpenClaw gateway | 从 agent loop 一路构建 session、channel、gateway、memory、heartbeat、delivery、resilience、concurrency。 | | hello-agents | Chinese agent tutorial | 从零开始构建智能体，适合系统补 Agent 原理与实践。 | | OpenClaw | Local-first personal agent | 学本地长运行 agent、skills、消息入口、系统工具和安全边界。 | | Hermes Agent | Self-hosted growing agent | 学长期记忆、skills、toolsets、多平台消息网关和迁移能力。 | | CyberClaw | Transparent agent architecture | 学全行为审计、两段式安全调用、双水位记忆和心跳任务。 | | LangGraph | Stateful graph orchestration | 学状态图、可恢复执行和可控编排。 |

• [ ] 读懂一个 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

| Level | Project | What You Learn | | --- | --- | --- | | 1 | Calculator Agent | 最小 tool call loop | | 2 | Web Research Agent | 搜索、筛选、引用、总结 | | 3 | PDF QA Agent | RAG、chunk、retrieval、citation | | 4 | Coding Review Agent | 读取 diff、风险排序、测试建议 | | 5 | Browser Agent | 页面观察、点击、提取、失败恢复 | | 6 | Claude Code-like Nano Agent | shell、文件编辑、权限、session、compact | | 7 | OpenClaw-like Gateway | channel、routing、session、memory、heartbeat、delivery | | 8 | Reusable Skill Pack | SKILL.md、脚本、模板、触发条件、smoke test | | 9 | Multi-Agent Writer | planner、writer、reviewer 协作 | | 10 | Personal Agent | OpenClaw/Hermes-style 记忆、skills、消息入口 | | 11 | Production Harness | evals、trace、权限、CI、runner、回放 |

Curated Resources

Official Guides And Blogs

| Resource | Why It Matters | | --- | --- | | Anthropic: Building effective agents | Agent 设计入门必读，讲清 workflow 和 agent 的边界。 | | Claude Code Overview | 当前最值得研究的 coding agent 产品文档入口。 | | Claude Code Subagents | 学任务拆分、上下文隔离、专用子代理。 | | Claude Code Hooks | 学如何拦截、校验和扩展 agent 行为。 | | Claude Code GitHub Actions | 学 coding agent 如何进入 PR / issue 工作流。 | | Claude Code Advanced Patterns | Anthropic 官方材料，覆盖 subagents、MCP 和真实代码库扩展。 | | OpenAI: A practical guide to building agents | 面向产品和工程团队的 agent 落地指南。 | | OpenAI: New tools for building agents | Responses API、Agents SDK、工具和 tracing 的官方介绍。 | | OpenAI Agents SDK | OpenAI 原生 agent 开发入口。 | | Claude Tool Use | Claude 工具调用机制。 | | Claude Computer Use | 电脑操作类 agent 的官方参考。 | | Gemini Function Calling | Gemini 工具调用官方文档。 | | Gemini Code Execution | Gemini 代码执行工具。 | | Google Agent Development Kit | Google 的 agent 开发框架。 | | Model Context Protocol | Agent 连接工具和数据源的重要协议。 |

Project Map

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

| Layer | Study These | Learn | | --- | --- | --- | | Build From Scratch | learn-claude-code, claw0, hello-agents | agent loop、tool registry、session、context compaction、gateway、trace、subagents。 | | Personal / Always-On Agents | OpenClaw, Hermes Agent, CyberClaw | 长运行、skills、记忆、消息入口、权限、安全审计。 | | Coding Agents | Claude Code, OpenAI Codex, OpenCode, OpenHands, SWE-agent, pi | 真实代码库编辑、shell、测试、sandbox、PR 工作流。 | | Agent Harness / SuperAgent Runtime | DeerFlow, LangGraph | 长任务执行、sandbox、memory、skills、subagents、message gateway、trace。 | | Deep Research / RAG Agents | GPT Researcher, Open Deep Research, LlamaIndex | 搜索、抓取、检索、rerank、引用、报告生成。 | | Tutorial Encyclopedias | GenAI_Agents, hello-agents, smolagents, agents-towards-production | 横向看 ReAct、Plan-and-Execute、Multi-Agent、production patterns。 | | Browser / Multimodal Agents | browser-use, UI-TARS-desktop | 浏览器/桌面操作、视觉理解、动作空间、失败恢复。 |

Skills, Protocols, And Tooling

| Concept | Learn From | What It Solves | | --- | --- | --- | | Skills | Claude Code Skills, OpenClaw Skills | 把一类任务的流程知识、脚本、模板和验收标准打包成可复用能力。 | | MCP | Model Context Protocol, 官方 MCP Servers 合集 | 让 agent 标准化连接外部工具、数据源和服务；官方 servers 合集涵盖文件系统、数据库、搜索、浏览器等常见场景，是学 MCP 接入最直接的参考。 | | A2A | Agent2Agent Protocol | 让不同 agent 之间发现、通信和协作。 | | ACP | Agent Client Protocol | 让编辑器、终端、IDE、宿主应用和 agent 之间形成统一接口。 | | Skill Quality | SWE-Skills-Bench, Agent Skills analysis, SkillOpt | 评估、优化和验证 skills 是否真的提升成功率，而不是制造新的 prompt 噪声。 |

Modern Agent Systems

| System | Why It Is Useful | | --- | --- | | Claude Code | 学 coding agent 的产品化形态：shell、文件、权限、hooks、subagents、MCP。 | | learn-claude-code | 从零构建 Claude Code-like nano agent，适合理解 harness engineering。 | | claw0 | 从零构建 OpenClaw-like agent gateway，覆盖 channel、routing、session、memory、delivery、concurrency。 | | hello-agents | 中文智能体系统教程，适合从零开始补齐 Agent 原理与实践。 | | OpenClaw | 本地优先的个人 agent，适合研究长运行 agent 和系统级工具调用。 | | Hermes Agent | 自托管、长期记忆、skills、消息网关和 toolsets。 | | CyberClaw | 透明可控 agent 架构，适合研究审计、两段式执行和安全边界。 | | DeerFlow | 字节开源 long-horizon SuperAgent harness。2.0 主分支是从头重写的通用 agent runtime，适合研究 sandbox、memory、skills、subagents、message gateway 和长任务执行；原 Deep Research 框架在 1.x 分支。 | | smolagents | Hugging Face 轻量 agent 框架，CodeAgent 思路值得研究。 | | LangGraph | 状态图和可控 agent 编排，仍然值得作为工程基础学习。 | | Qwen-Agent | 国产模型生态里的工具调用、RAG、MCP agent 框架。 | | Pydantic AI | 类型安全和结构化输出，适合生产 Python agent。 | | pi | AI agent toolkit（TypeScript），含 coding agent CLI、agent core、统一多提供商 LLM API 和 TUI 库，支持自扩展。 |

Legacy Or Optional Frameworks

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

| Framework | Note | | --- | --- | | CrewAI | 可了解 role/task/crew 抽象，但很多场景已经被更强的 coding agent / harness 形态覆盖。 | | AutoGen | 多 agent 对话框架经典项目，适合了解历史和论文，不必重押。 | | LangChain Agents | 生态仍重要，但建议重点转向 LangGraph 和具体工程模式。 |

Papers

| Paper | Topic | | --- | --- | | ReAct | Reasoning + acting 的基础范式。 | | Toolformer | 模型学习何时调用工具。 | | Reflexion | 语言反馈和自我改进。 | | Generative Agents | 记忆、反思、规划驱动的模拟 agent。 | | Voyager | 开放世界中的长期学习 agent。 | | AutoGen | 多 agent 对话框架。 | | AgentBench | Agent 能力评测。 | | WebArena | 真实网页环境下的 agent benchmark。 | | SWE-bench | 真实 GitHub issue 修复评测。 | | GAIA | 通用 AI 助手基准，测推理、多模态、工具使用；人类 92% vs GPT-4 15%，差距揭示 agent 能力上限。 | | OSWorld | 真实操作系统环境下的多模态 agent benchmark，覆盖 Ubuntu / Windows / macOS；适合 Stage 6 计算机操作 agent 学习。 | | τ-bench | 测量 tool-agent-user 三方动态交互；GPT-4o 在真实场景成功率不足 50%，pass^8 不足 25%，是评估 agent 可靠性的重要参照。 | | SWE-agent | 软件工程 agent 的 agent-computer interface。 | | Dive into Claude Code | 从系统设计角度分析 Claude Code 这类 coding agent 的 harness、权限、压缩和扩展机制。 | | AI Harness Engineering | 把 harness 作为 agent 能力来源来研究。 | | Configuring Agentic AI Coding Tools | 对 Claude Code、Codex、Gemini、Cursor 等 coding tools 的配置机制分析。 | | Your Agent, Their Asset | OpenClaw 等本地 agent 的真实安全风险分析。 |

GitHub Repositories

| Repo | Why It Is Useful | | --- | --- | | datawhalechina/hello-agents | 中文智能体系统教程，从零开始构建智能体。 | | shareAI-lab/learn-claude-code | Bash is all you need，从 0 到 1 学 Claude Code-like agent harness。 | | shareAI-lab/claw0 | 从 0 到 1 学 OpenClaw-like gateway，10 个渐进章节覆盖 agent loop 到 concurrency。 | | openclaw/openclaw | 研究本地个人 agent、skills、长运行任务、系统工具和权限边界。 | | NousResearch/hermes-agent | 研究自托管 agent、长期记忆、skills、toolsets、多平台消息网关。 | | ttguy0707/CyberClaw | 研究透明 agent、安全审计、两段式执行、双水位记忆和心跳任务。 | | bytedance/deer-flow | 2.0 是通用 long-horizon SuperAgent harness，适合学习沙箱、memory、skills、subagents、message gateway 和产物生成；Deep Research 代码看 1.x 分支。 | | NirDiamant/GenAI_Agents | 综合教程库，适合横向比较 ReAct、Plan-and-Execute、Multi-Agent 等实现方式。 | | NirDiamant/agents-towards-production | production-grade agent 教程库，适合补工程化组件。 | | huggingface/smolagents | 轻量 CodeAgent 风格框架，适合研究“让模型写代码执行动作”的范式。 | | openai/codex | OpenAI 开源 coding agent CLI，适合研究 sandbox、approval、CLI 产品形态。 | | opencode-ai/opencode | 终端优先的开源 coding agent，适合对照 Claude Code / Codex。 | | Aider-AI/aider | 终端 AI pair programming 工具，支持多模型，与 git 深度集成；是最早期也最活跃的 coding agent 之一，对照 Claude Code 视角学习价值高。 | | block/goose | Block 出品的开源可扩展 AI agent，支持安装、执行、编辑、测试，不限于代码建议；架构和 skills 设计值得研究。 | | langchain-ai/langgraph | 状态图和可控 agent 编排。 | | openai/openai-agents-python | OpenAI Agents SDK Python。 | | QwenLM/Qwen-Agent | Qwen 生态 agent 框架。 | | browser-use/browser-use | 浏览器 agent 实战。 | | bytedance/UI-TARS-desktop | 多模态桌面 agent stack，适合研究视觉 UI 操作。 | | SWE-agent/SWE-agent | 软件工程 agent。 | | All-Hands-AI/OpenHands | 开源 coding agent。 | | microsoft/ai-agents-for-beginners | 系统化入门课程。 | | jjyaoao/HelloAgents | 基于 OpenAI 原生 API 的生产级多智能体框架，覆盖 ToolResponse、上下文工程、会话持久化、子代理、TraceLogger 等。 | | earendil-works/pi | TypeScript 写的 AI agent toolkit，含 pi-coding-agent CLI、pi-agent-core 运行时、pi-ai（统一多提供商 LLM API）、pi-tui（终端 UI 库），支持 Slack 机器人和 vLLM pods。 |

Thoughtful Blogs

| Blog | Why It Is Useful | | --- | --- | | Lilian Weng: LLM Powered Autonomous Agents | 经典长文，系统整理 agent 架构、记忆、规划和工具使用。 | | Simon Willison: AI/LLM writing | 非常务实的 LLM 工程观察，适合补工程直觉。 | | LangChain Blog | LangGraph、LangSmith、agent 工程实践。 | | Google Developers Blog: ADK | Google ADK 官方发布文章。 |

Claude Code Study Path

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

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

| Resource | Focus | | --- | --- | | Claude Code Common Workflows | 官方工作流教程，适合学日常使用和项目协作。 | | Claude Code Overview | 官方入口，理解产品能力和命令行工作方式。 | | learn-claude-code | 从零复刻 Claude Code-like agent，适合学 harness 最小实现。 | | Claude Code 源码解析 | 中文架构解读，适合按模块理解实现思路。 | | Claude Code 源码分析地图 | 用地图方式拆解 agent loop、工具、命令和多代理协作。 | | Dive into Claude Code | 从研究视角总结 Claude Code 的设计空间和 agent harness 模式。 | | Agentic Education | 用 Claude Code 学 Claude Code 的交互式课程思路。 |

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.