Learn AI Agents from Scratch

A visual, bilingual, and engineering-first textbook for building reliable LLM Agents.

From Function Calling, memory, planning, RAG, and context engineering to Agentic RL, multi-agent systems, evaluation, security, and production deployment.

中文说明 · Complete directory · Runnable reference agent · Contributing

What is this repository?

agent_learning is an open-source AI Agent textbook and learning repository. It is designed for the gap between "I can call an LLM API" and "I can build, evaluate, secure, and deploy an Agent system."

Instead of teaching isolated framework APIs, the book builds one connected mental model:

LLM fundamentals → tools → memory → planning → RAG → context → harness → skills → Agentic RL → multi-agent → evaluation → security → deployment

The repository includes:

• 23 chapters across foundations, core capabilities, frameworks, multi-agent systems, production, and capstone projects.
• 188 Markdown pages per language, maintained in English and Chinese.
• 330+ original SVG diagrams and 5 interactive demos for architecture, state, sequence, and training flows.
• Paper-to-practice explanations covering ReAct, Reflexion, MemGPT/Letta, GraphRAG, GRPO, MCP, A2A, and more.
• reference-agent/, a small runnable Agent baseline with tools, memory, security gates, evaluation, an MCP server, a FastAPI service, and 16 tests.

This is not an awesome-list and not a framework manual. It is a structured path from first principles to production engineering.

Complete directory

• Book source
  • src/en/ — English mdBook source
  • src/zh/ — Chinese mdBook source
  • src/en/SUMMARY.md — English table of contents
  • src/zh/SUMMARY.md — Chinese table of contents
• Foundations
  • 1. What Is an Agent?
  • 2. LLM Fundamentals
• Core capabilities
  • 3. Tools
  • 4. Memory
  • 5. Planning
  • 6. RAG
  • 7. Context Engineering
  • 8. Harness Engineering
  • 9. Skills
  • 10. Agentic RL
  • 11. Self-Evolving Agents
• Framework practice
  • 12. LangChain
  • 13. LangGraph
  • 14. Agent Frameworks
  • 15. Claude Code
• Multi-agent systems
  • 16. Multi-Agent Collaboration
  • 17. Agent Protocols
• Production engineering
  • 18. Evaluation
  • 19. Security
  • 20. Deployment
• Capstone projects
  • 21. Coding Agent
  • 22. Data Agent
  • 23. Multimodal Agent
• Appendices
  • Prompt templates
  • FAQ
  • Resources
  • Glossary
  • KL divergence
  • Environment setup
• Runnable implementation
  • reference-agent/ — teaching baseline Agent implementation
  • reference-agent/src/reference_agent/ — Agent loop, providers, tools, memory, security, server, evaluation
  • reference-agent/tests/ — offline test suite
• Assets and build files
  • src/en/svg/ — English diagrams
  • src/zh/svg/ — Chinese diagrams
  • src/en/animations/ — English interactive demos
  • src/zh/animations/ — Chinese interactive demos
  • theme/ — shared mdBook theme
  • book.toml — Chinese mdBook config
  • book-en.toml — English mdBook config
  • serve.sh — build and serve both books locally

Runnable reference agent

reference-agent/ is the shared, dependency-light implementation behind the hands-on chapters. It includes:

• a minimal ReAct loop and tool registry;
• offline FakeProvider and optional OpenAI provider;
• memory, prompt-injection guardrails, and fail-closed permission checks;
• an MCP server, FastAPI endpoints, streaming, evaluation harness, and Dockerfile;
• 16 tests that run without an API key.

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

The implementation is intentionally small enough to read. It is a teaching baseline, not a claim of production completeness.

Project principles

1. Mechanisms before frameworks. Explain why an abstraction exists before teaching its API.
2. Visuals must teach. Diagrams carry architecture and process information; they are not decoration.
3. Research must lead to engineering insight. Paper notes include contribution, mechanism, use, and limitations.
4. Production claims must be honest. Runnable code, tests, security boundaries, and known limitations are stated explicitly.
5. Bilingual content stays aligned. Text, diagrams, navigation, and interactive demos are maintained in both languages.

Contributing

Corrections, clearer explanations, runnable examples, translation fixes, and new paper notes are welcome.

• Found an error? Open an issue.
• Want to improve a chapter? Edit the matching file under both src/en/ and src/zh/ when possible.
• Adding a page? Update both SUMMARY.md files.
• Adding a diagram? Place localized assets under src/en/svg/ and src/zh/svg/.
• Before a PR, run ./serve.sh and verify both language builds.

Please keep claims verifiable and prefer primary sources for papers, protocols, versions, and external projects.

Roadmap

• 23-chapter bilingual mdBook
• Localized diagrams and interactive demos
• Agentic RL, context engineering, harness engineering, and self-evolving Agent coverage
• Runnable reference-agent baseline with offline tests
• More end-to-end capstone implementations
• Searchable diagram gallery and concept index
• Evaluation and observability starter templates
• More exercises, interview questions, and regression cases

Suggestions are welcome in Issues.

License

Released under the MIT License.