agent_learning: A Bilingual Textbook That Ships a Runnable Reference Agent

The Gap Between Calling an API and Operating an Agent

The README names its own target reader precisely: someone stuck between "I can call an LLM API" and "I can build, evaluate, secure, and deploy an Agent system." That is a real and specific gap. Most people who have wired a chat completion endpoint into a script have never decided what happens when a tool call fails, where conversation state lives after the context window fills, or how to tell whether a prompt change made the agent better or worse. Those are the questions this repository organizes itself around. The stated progression runs from LLM fundamentals through tools, memory, planning, RAG, context engineering, harness engineering, skills, agentic RL, multi-agent systems, evaluation, security, and deployment. The audience is an engineer who can read code and wants the mental model before the framework. It is explicitly not an awesome-list and not a framework manual, and the README states that distinction directly. That framing matters because it sets expectations about what you will and will not find: no curated link dump, no API reference for LangChain, but a connected explanation of how the pieces relate.

How the Book Is Structured and Built

The repository is an mdBook project with two parallel source trees, src/en/ and src/zh/, each carrying its own SUMMARY.md table of contents. The README reports 188 Markdown pages per language and 23 chapters, grouped into foundations, core capabilities, framework practice, multi-agent systems, production engineering, and capstone projects. Diagrams are stored as original SVG under src/en/svg/ and src/zh/svg/, and there are five interactive demos under src/en/animations/ and src/zh/animations/. Two separate mdBook configuration files exist, book.toml for the Chinese build and book-en.toml for the English one, which is the mechanism that keeps the two languages from interfering with each other during a build. A serve.sh script is provided to build and serve both books locally. The themes are shared through a theme/ directory. If you have used mdBook before, the layout will be immediately legible: SUMMARY.md drives navigation, the .toml files drive output, and everything else is content. The dual-tree approach has a maintenance consequence worth naming. Any correction to a diagram or a paragraph has to be applied twice, once per language, and the two SUMMARY.md files can drift apart without any automated check catching it, because nothing in the described layout enforces parity between them.

The Reference Agent: What Actually Runs

The part most likely to change your decision is reference-agent/, described as a dependency-light implementation behind the hands-on chapters. According to the README it contains a minimal ReAct loop and a tool registry, an offline FakeProvider plus an optional OpenAI provider, memory handling, prompt-injection guardrails, and permission checks that fail closed rather than open. It also ships an MCP server, FastAPI endpoints, streaming, an evaluation harness, and a Dockerfile. The test suite is 16 tests and, per the README, runs without an API key. That last detail is the most consequential design choice in the whole repository. A provider abstraction with a fake implementation means the agent loop, the tool dispatch, the memory layer, and the guardrails can all be exercised in CI without network access or spend. The source layout under reference-agent/src/reference_agent/ is split into the agent loop, providers, tools, memory, security, server, and evaluation. That is a small surface area by design. This is a teaching baseline, not a production runtime: it exists so the chapters have something concrete to point at. Treat the module boundaries as the lesson, and expect to replace the internals when you build something real.

Getting It Running

The README gives the setup sequence for the reference agent: change into the directory with cd reference-agent, create a virtual environment with python -m venv .venv, activate it with source .venv/bin/activate on a Unix shell, and install dependencies with pip. The README text is truncated mid-command at that point, so the exact install line and the exact test invocation are not visible in the supplied material. Do not guess at a requirements file name or a pytest target. Read reference-agent/ directly to confirm both. The book build is separate and better documented. Two mdBook configuration files exist, book.toml and book-en.toml, and serve.sh is described as building and serving both books locally, so that script is the entry point rather than a raw mdbook serve invocation. The published output lives at the project homepage, with /en/ and /zh/ paths for the two languages, which means you can read the entire book without cloning anything. That is the sensible first step: read a chapter online, then clone only if you intend to run the reference agent or edit the source. The offline FakeProvider is the reason the second step is cheap, because it removes the API key from the critical path of getting tests green.

Breadth as a Maintenance Liability

Twenty-three chapters covering LangChain, LangGraph, Claude Code, MCP, A2A, GRPO, DSPy, and GraphRAG is a lot of surface area to keep current. The framework chapters are the exposed edge. LangChain and LangGraph both change their APIs at a pace that outruns book revisions, and a chapter that teaches a specific chain construction or graph state pattern can go stale between one release and the next. No releases were retrieved for this repository, so there is no versioned snapshot to pin your reading against and no changelog to tell you which chapters were revised when. The last push timestamp tells you the repository is active, but it does not tell you which of the 188 pages per language were touched. The paper-to-practice chapters on ReAct, Reflexion, MemGPT/Letta, GraphRAG, GRPO, MCP, and A2A age more slowly because the underlying papers are fixed, though the implementations they describe move. Practically, this means you should read the foundations and core capability chapters as durable material and treat the framework chapters as a starting orientation that you verify against current upstream documentation before copying any code. The repository does not appear to offer a mechanism for flagging which chapters are stale, and nothing in the described structure automates a check against upstream framework versions.

Where a Book Is the Wrong Tool

If what you need is a runtime, agent_learning is the wrong choice, and the README is honest about that. Compare it with LangGraph, which the book itself covers in chapter 13. LangGraph is a library you install and import; it gives you a graph execution engine, state management, checkpointing, and a release cadence with version numbers you can pin in a lockfile. agent_learning gives you prose, SVG diagrams, and a deliberately minimal reference implementation whose stated purpose is teaching. The difference in approach is not quality, it is category. A library makes a promise about behavior across versions. A textbook makes a promise about explanation, and it can be correct on the day it is written and misleading a year later without anyone doing anything wrong. The same distinction applies against the MCP specification itself, which the book covers in chapter 17. If you are implementing a protocol client, you need the specification, not a chapter about the specification. The reference agent's MCP server is useful precisely because it shows a small working example, but it is a teaching artifact, not a conformance suite. Pick this repository when the missing thing is understanding. Pick a library or a spec when the missing thing is an interface you have to depend on.

Licence, Reuse, and What to Verify

The repository is MIT licensed, which is permissive and permits reuse with attribution and the licence text retained. That covers the code in reference-agent/ and the chapter source. It does not automatically resolve the status of third-party material the book discusses, such as quoted paper figures or framework documentation excerpts, and the supplied material does not describe how those are handled. If you intend to reuse the 330+ SVG diagrams in your own training material, check the individual files for embedded attribution before doing so. This is not legal advice; read the LICENSE file and the specific asset you want to reuse. On maintenance cost, the honest position is that a 188-page bilingual book is expensive to keep current, and the two-language structure doubles the editing work for every correction. There is no evidence in the supplied material of a translation sync check, a chapter-level freshness marker, or a release process. Before you commit to it as a team resource, verify that the specific chapters your team needs are present in src/en/SUMMARY.md, that the reference-agent tests pass on your Python version using the offline FakeProvider, and that the framework chapters you plan to rely on still match the upstream APIs they describe.

Editorial conclusion

Adopt agent_learning if you already call an LLM API and need a structured path through tools, memory, planning, RAG, evaluation, security, and deployment, and you want the reference-agent source as a reading companion. Skip it if you need a maintained runtime library, an SDK with versioned releases, or a book that tracks framework API churn closely, since no releases were retrieved and the prose is tied to specific framework chapters. Before committing, verify three things: that the chapter you need actually exists in src/en/SUMMARY.md, that reference-agent tests pass on your Python version using the offline FakeProvider, and that the MIT licence terms fit how you intend to reuse the SVG diagrams and chapter text.

Official sources

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