agent_learning: An Open-Source AI Agent Development Textbook with a Runnable Reference Implementation

Bridging the Gap Between LLM API Calls and Agent Engineering

A developer who can call an LLM API has the building block for an AI agent, but the gap between a single API call and a reliable, secure, production-deployed agent system is large. Filling it typically means reading across framework documentation (LangChain, LangGraph, CrewAI), research papers (ReAct, Reflexion, MemGPT, GRPO), and deployment guides, none of which form a coherent sequence.

agent_learning is an open-source textbook that attempts to close that gap with a single structured path. The README defines the scope explicitly: it is designed for the gap between "I can call an LLM API" and "I can build, evaluate, secure, and deploy an Agent system." The book takes the view that mechanisms come before frameworks: it explains why an abstraction exists before teaching its API. This is distinct from the LangChain or LlamaIndex documentation, which assume you want to use their specific framework and teach the API directly.

The repository is licensed under MIT, receives daily updates from automatic arXiv paper tracking, and maintains parallel editions in English and Chinese, each with 188 Markdown pages.

Twenty-Three Chapters: From Foundations to Capstone Projects

The textbook is organized into six groups. The foundations group covers what an agent is and the LLM fundamentals needed to understand one. The core capabilities group covers tools (function calling), memory systems, planning, RAG, context engineering, harness engineering, skills, Agentic RL, and self-evolving agents. The framework practice group covers LangChain, LangGraph, a survey of agent frameworks, and Claude Code. The multi-agent section covers collaboration patterns and the MCP and A2A protocols. The production engineering section covers evaluation, security, and deployment. Three capstone projects complete the sequence: a coding agent, a data agent, and a multimodal agent.

The paper-to-practice explanations throughout the textbook cover specific research contributions: ReAct (reason and act interleaving), Reflexion (self-reflection-based improvement), MemGPT (memory hierarchy for long-context agents), GraphRAG (knowledge-graph-augmented retrieval), GRPO (group relative policy optimization for Agentic RL), MCP (model context protocol), and A2A (agent-to-agent protocol). Each paper explanation includes the contribution, mechanism, practical use, and known limitations.

The 330+ SVG diagrams are described as load-bearing: they carry architecture and process information rather than decorating the text. The README states as a project principle that "visuals must teach." Five interactive demos in the src/en/animations/ and src/zh/animations/ directories provide dynamic versions of the diagrams that the websites render.

Running the Reference Agent and the Test Suite

The reference-agent/ directory contains a small runnable agent baseline that backs the hands-on chapters. The README describes its components: a minimal ReAct loop with a tool registry, an offline FakeProvider and an optional OpenAI provider, memory, prompt-injection guardrails, fail-closed permission checks, an MCP server, FastAPI endpoints, streaming, an evaluation harness, and a Dockerfile.

The test suite runs without an API key using the FakeProvider:

cd reference-agent
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

The 16 tests exercise the core loop and the security gates offline. The README is explicit about the scope: "The implementation is intentionally small enough to read. It is a teaching baseline, not a claim of production completeness." Teams should read it as a concrete example of the patterns described in the chapters, not as a starting point for a production deployment.

Bilingual Structure and How to Navigate the Repository

The English and Chinese editions are maintained as parallel source trees under src/en/ and src/zh/. Each has its own mdBook configuration file (book-en.toml for English, book.toml for Chinese) and its own SUMMARY.md table of contents. Diagrams in src/en/svg/ and src/zh/svg/ are separate SVG files; both editions have 330+ diagrams.

The published website has two entry points: the English edition at Haozhe-Xing.github.io/agent_learning/en/ and the Chinese edition at Haozhe-Xing.github.io/agent_learning/zh/. Locally, the serve.sh script builds and serves both editions:

bash serve.sh

The appendices include prompt templates, a FAQ, a resource list, a glossary, a KL divergence reference, and an environment setup guide. These are accessible from both language editions.

The repository includes an examples/ directory with example agent implementations (auto_research_demo/, dev_team/) that demonstrate multi-agent patterns from the curriculum in runnable form.

Limitations: Daily Updates Create Moving Content

The README lists automatic daily arXiv paper tracking as a feature. While this keeps the research references current, it also means specific technical claims in the text may change between reads. The mdBook chapter frontmatter includes date_updated fields, but those reflect the last edit date of a chapter, not whether the claims in a specific section were reviewed in the most recent update.

The reference agent covers MCP server integration and FastAPI endpoints, but the MCP protocol itself is evolving. Teams who need a production-grade MCP server should treat the reference implementation as a teaching example and evaluate production MCP frameworks separately.

The textbook does not cover fine-tuning models or training from scratch; it focuses on how to build systems around existing LLM APIs. Engineers who need to customize model weights for agent-specific behaviors will need to look beyond this resource for that aspect of their stack.

agent_learning vs Framework Documentation and Awesome Lists

LangChain and LangGraph documentation are the most commonly consulted resources for agent development in Python. They assume you want to use those specific frameworks and teach the APIs directly. They do not explain why the abstractions exist, and they do not connect to the research literature (ReAct, Reflexion, GRPO) that motivates the design choices. agent_learning explicitly puts the mechanism explanation before the framework API for every topic it covers.

Awesome-list repositories for LLM agents collect links to papers, tools, and blog posts. They provide breadth but no sequential learning path and no worked examples. The agent_learning README names this pattern directly: "awesome-list format that tells you to go somewhere else to learn."

The textbook is closest in spirit to fast.ai's practical deep learning course in that it combines text, code, and a working reference implementation around a single progression. The difference is that fast.ai focuses on model training while agent_learning focuses on agent system engineering around deployed LLM APIs.

Maintenance, License, and Project Activity

The last push to the agent_learning repository was on 2026-09-28. The project has no GitHub releases; chapters are published continuously through the GitHub Pages website as commits land. The MIT license permits any use including commercial, with attribution.

The repository has 188 Markdown pages per language edition, plus the SVG diagram files, the reference agent Python source, and the CI configuration under .github/. The scripts/ directory contains automation for the daily arXiv update. The README mentions a WeChat contact for the author for direct questions outside GitHub issues.

Editorial conclusion

agent_learning is the right starting point for developers who understand how to call an LLM API but want a structured path to production agent engineering. The 23-chapter sequence builds one connected mental model rather than jumping between frameworks. The reference agent in reference-agent/ is explicitly a teaching baseline, not a production-ready component; teams who read the security and deployment chapters will find the concepts they need to move beyond it. The bilingual English and Chinese editions make it accessible to a broader audience than English-only alternatives. Before relying on any specific section, check the date_updated frontmatter in that chapter since the repository tracks arXiv papers daily and updates may change specific technical claims.

Frequently asked questions

Official sources

1. Haozhe-Xing/agent_learning on GitHub
2. Issues
3. License: MIT
4. Project website
5. README