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。

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 加最大步数、超时和错误处理。

推荐阅读：

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

Stage 2: Learn Tool Use, RAG, And Memory

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

推荐阅读：

开源项目参考：

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 更好。

推荐阅读：

产出：一个小型多 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，验证它是否真的提升任务成功率。

推荐阅读：

产出：一个可复用 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、动作日志，方便复盘。

推荐阅读：

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

Stage 7: Evaluation, Observability, And Safety

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

推荐阅读：

产出：一个 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.