📱 On a phone, read the docs site rather than this page.

Trilingual — the English edition is fully maintained, not a thin machine translation (only ~0.4% of English lines carry any CJK, almost all intentional bilingual term-mapping). zh-TW is the curation source of truth (new content lands there first); the English and 简中 editions track the same structure, with CI checking localization correctness and anchor integrity across all three.

#🎯 Why this exists

What this repo is: a learning roadmap + 240+ curated resources + simple illustrative cases — three pillars helping AI / AI-agent learners go from "I don't know where to start" to "I can design multi-agent systems."

Concretely:

After the main path, you go from "LLM user" to "agent system builder" — capable of designing multi-agent collaboration, writing your own MCP server, and shipping real agent systems.

#📋 Table of Contents

• 🎯 Why this exists
• 📚 Quick Start
  • Read online
  • Local clone
  • ✨ What you get
• 🗺️ Learning Map (Two Tracks)
• 💡 How to Learn
• 📚 Related Resources
• 🤝 Contributing
• 🙏 Acknowledgments
• 🎓 Citation
• ☕ Support this project
• License

#📚 Quick Start

#🚀 First time with AI agents / never written code before?

Start here: resources/setup-guide.en.md — 30-45 minutes from zero, walks you through getting an API key, installing Python, and running your first LLM hello-world.

#Read online

• Learning Map (Two Tracks) — read this section to decide Track A or Track B
• Stage 0 Foundations — already know Python / git / API? Skip straight to Stage 1

#Local clone

git clone https://github.com/WenyuChiou/awesome-agentic-ai-zh.git
cd awesome-agentic-ai-zh
# Start with stages/00-foundations.en.md

#✨ What you get

• 📖 Fully free — MIT-licensed, all content open
• 🗺️ Two learning tracks — Track A (CLI Power User) for "use existing CLIs"; Track B (Agent Builder) for "build your own". Shared Stages 0-2 foundation.
• 🛠️ Foundational hands-on exercises — 1-5 illustrative exercises per stage (specs + dual-path SDK comparison + success criteria). Positioned as foundational + roadmap verification — for chapter-length depth exercises see the hello-agents / Anthropic Cookbook callout in each stage
• 🎯 240+ curated projects — each with star rating, audience, what it teaches, how to run (incl. local LLM runners: Ollama, llama.cpp, LocalAI, MLX)
• 🌏 Trilingual, fully maintained — zh-TW (canonical) / 简中 / English; the English edition is complete, not a thin mirror
• 🎓 Beyond frameworks: Claude Code ecosystem — MCP / Skills / Plugins / SDK full stack
• 🔬 5 specialized branches — researcher / developer / teacher / knowledge worker / everyday user
• ⏱️ Time commitment, stated upfront — Track A 8-10 weeks / Track B 16-22 weeks minimum, 5-7 months realistic (5-8 hr/week part-time)

#🗺 Learning Map (Two Tracks)

After Stages 0-2 (shared foundations), pick a track based on your goal:

• Track A — CLI Power User: you want to USE existing CLI agents (Claude Code, Codex, OpenCode, Gemini CLI, etc.) to get work done — not build agents from scratch. 3 sub-stages (A1-A3).
• Track B — Agent Builder: you want to BUILD your own agents — learn frameworks, write ReAct, design multi-agent systems. Stages 3-8 main path.

The two tracks are not mutually exclusive — most people start with A to get hands-on, then come back to B for internals (or vice versa). Stage 5 (Claude Code Ecosystem) is used by both tracks.

#Shared Foundations (Stages 0-2)

#Track A — CLI Power User (use CLIs to get work done)

Track A total time: includes Stages 0-2 (shared foundations) + A1-A3 + Stage 5 + Stage 8 (two shared hubs) ≈ 8-10 weeks. Core reference: resources/cli-agents-guide.en.md.

#Track B — Agent Builder (build agents from scratch)

Track B total time: minimum 16-22 weeks, realistic 5-7 months (5-8 hr/week part-time)

Two shared hubs (used by both Track A + Track B):

• Stage 5 = Claude Code Ecosystem (MCP / Skills / Plugins / Subagents) — Track A learns MCP-into-CLI, Track B learns agent runtime structure
• Stage 8 = Agent Interfaces (Computer Use / Browser / Sandbox, 2024-2026 frontier) — Track A learns "how to use" for task delegation, Track B learns "how to build" with embedded interfaces

💡 Want a concrete cross-stage example? Build Your First AI Agent in 7 Steps — same Paper Summary Bot traced from Stage 1 through Stage 7, ~300 lines of executable code (Track B)

After the main path, pick one of 5 specialized branches. Not sure which?

💡 The Everyday User branch can be read directly without walking the main path — it's for people who want to use AI without writing code.

#💡 How to Learn

Welcome — future agent system builder. Some guidance before you start.

This roadmap balances concepts with hands-on work, helping you transform from an LLM user into an agent system builder. It assumes basic Python. Before starting:

• Basic Python — written functions, used APIs, can read JSON
• Basic git — clone, commit, push
• Motivation to learn — agents are the fastest-changing area in AI 2025+, and require sustained effort

If anything's missing, do Stage 0; if not, start at Stage 1.

The main path has 5 parts:

• Part 1 (Stages 0-2): Foundations & LLM Basics — Python / git / API, what's an LLM, prompt design
• Part 2 (Stages 3-4): Build Your Agent — from tool use to agents, learn the major frameworks
• Part 3 (Stage 5) Shared Hub — Claude Code Ecosystem (MCP / Skills / Plugins / Subagents; used by both Track A + B)
• Part 4 (Stages 6-7): Advanced Integration — memory / RAG / multi-agent collaboration / harness engineering
• Part 5 (Stage 8) Shared Hub — Agent Interfaces (Computer Use / Browser Use / Code Sandbox, 2024-2026 frontier; used by both tracks)

🔭 How the concept layers evolved: prompt engineering (Stage 2 — how to write a single prompt) → context engineering (Stage 3 onward — how to dynamically assemble system prompt + memory + retrieved chunks + tool schema) → harness engineering (Stage 7 — agent loop / eval / observability / deploy as a complete production system). After 2026, the community extended this outward with two more layers: loop (letting the agent run itself to completion) and graph (making the execution flow explicit). For the full five-layer model and each layer's purpose, see Stage 7 five-layer engineering split. See stages/02-prompt-engineering.en.md "Beyond prompts: context engineering" and stages/07-multi-agent-production.en.md Required Reading 5+6.

After the main path (16-22 weeks for Track B, 8-10 weeks for Track A), pick a branch.

The most important advice: don't skip the hands-on exercises. Each stage's exercises are "you can't learn this without doing it" — skim past them and you'll get stuck later.

🎓 How to actually use the exercises: the starter.py in each exercise folder is a complete solution, not a TODO skeleton. If you clone, cat starter.py, and run python test.py to all-green, you'll think "I learned it" — but you haven't written a single line. Correct learning loop: mv starter.py starter_reference.py, look at signatures (not bodies), write your own, peek at the reference only after 20 min stuck. Full method + per-stage time budgets + escalation order in docs/HOW_TO_USE.md.

Ready? Start at Stage 0.

#📚 Related Resources

The full related-resources block (term definitions + daily-tool MCP/Skill highlights + awesome lists + Chinese-community resources) lives in RESOURCES.en.md so this README stays focused.

Common quick links, grouped by scenario:

#🚀 Onboarding / Environment

#📖 Concepts / Terminology

#🛠 Hands-on

#🔌 Daily tool integrations / Finding MCP servers

#🔬 Research / Production

#🤝 Contributing

This repo is an AI learning document — if you've also curated great resources, contributions are very welcome:

• 🐛 Bug reports — wrong content, broken links, stale info → open Issue
• 💡 Suggestions — missing stage / new project to add → open Issue to discuss
• 📝 Improvements — refine existing stage content, fix typos → direct PR
• ✍️ Add a project — 1-3 new projects per stage with "why this teaches that stage" rationale
• 🌏 Translations — improve the English edition or translate to other languages
• 🌱 Become a Stage / Branch maintainer — long-term review of a specific area, see CONTRIBUTORS.md

PR process and style rules: CONTRIBUTING.en.md + resources/style-guide.en.md.

🤖 New project links are auto-audited — when a PR adds a new github.com/owner/repo link, a GitHub Action comments with its stars, license, archived status, and last-push, flagging archived / stale (>6 months) / unlicensed entries against the curation bar. Advisory only, never blocks — the maintainer decides what gets in (v1 runs on maintainer-branch PRs; fork PRs are skipped for now due to token scope).

📅 Want to see what shipped recently? → CHANGELOG.md (last 14 days). Internal phase rollout progress and launch checklist: .github/launch-checklist.md (maintainer-facing internal doc).

#💬 Advisory / Contact

A free, open (MIT) learning edition — use it freely.

Currently focused on advisory work: teams or companies needing prompt review / audit or AI agent workflow consulting are welcome to reach out (PhD student, limited availability): 📧 wenyuchiou12@gmail.com

#🙏 Acknowledgments

#Inspiration

• Datawhale Hello-Agents — the most thorough chapter-length agent tutorial in the Chinese-language ecosystem; inspired our chapter + progress structure. Every stage / exercise folder has a 📚 callout pointing to the relevant depth chapter. Special thanks.
• Datawhale community — landmark Chinese ML learning community; multiple anchor projects come from them
• liyupi/ai-guide — largest Chinese-language "AI mega-guide" + Vibe Coding tutorial (covers Agent Skills / RAG / MCP / A2A / Harness Engineering). This repo is a "structured roadmap"; ai-guide is a "breadth resource hub" — complementary

#Related projects

Other lists in the same space — useful to browse alongside this repo when hunting for specific tools:

• wong2/awesome-mcp-servers — categorized MCP server catalog
• punkpeye/awesome-mcp-servers — another MCP server catalog
• hesreallyhim/awesome-claude-code — Claude Code tools & plugins list

These are pure catalogs (browse and pick). This repo is different in that it has a learning order from Stage 0 all the way to production.

#Contributors

New contributors appear above automatically. Full list → GitHub Contributors.

#Personal

• @WenyuChiou — Maintainer

#🎓 Citation

If this learning roadmap helps your study or work, please cite:

@misc{awesome_agentic_ai_zh_2026,
  title = {awesome-agentic-ai-zh: A Structured Learning Roadmap for Agentic AI},
  author = {Chiou, Wenyu},
  year = {2026},
  url = {https://github.com/WenyuChiou/awesome-agentic-ai-zh},
  note = {8-stage learning path from prerequisites to Agent Interfaces (Computer Use / Browser Use / Code Sandbox), with curated projects + hello-X demos. Trilingual (zh-TW / 简中 / English).}
}

#☕ Support this project

This learning map is free and open-source (MIT). If it helps you, a ⭐ Star means a lot — and if you'd like to support ongoing updates, you can buy the author a coffee:

Or use the ❤ Sponsor button at the top of the repo. (GitHub Sponsors is under review and will be added once approved.)

#License

MIT. Maintained by @WenyuChiou.