heaven999b/hello-agent-system

What it solves

Most agent tutorials only show you how to write a simple loop that calls an LLM and uses tools. But putting an agent into a company where thousands of people use it brings real problems: the model returns rate-limit errors, the agent gets stuck in infinite loops burning money, users hide prompt-injection instructions in documents, one tenant's data leaks into another's answers, a prompt change breaks other scenarios, or the process crashes mid-run. This project is a structured training system that teaches you how to solve all of these production concerns, not just how to make a demo.

How it works

The project is a 32-lesson, bilingual (Chinese/English) bootcamp. It avoids any agent framework and instead has you hand-write every layer of a production agent from scratch. Part 1 builds the core async runtime: the agent loop, tools, context management, architectures, and orchestration. Part 2 covers enterprise problem cards with 2–5 solution options per issue—reliability, security, observability, evals, production architecture, high concurrency, cost, RAG, and release operations. Part 3 goes deeper into retrieval quality, memory systems, MCP, framework comparisons, agent data, evaluation methodology, optimization, coding agents, and proactive agents. Part 4 swaps the same internal interfaces to mature components like Postgres, Redis, Temporal, OpenTelemetry, LiteLLM, and Cedar for real deployment.

Each lesson has the same flow: read the lecture, run a demo, write an exercise, and make the automated offline deterministic tests pass. From lesson 02 the code is async—one process serves hundreds of sessions. From lesson 12 it uses real multi-process execution with lease queues, fencing tokens, kill -9 takeover, SIGSTOP zombie detection, and graceful shutdown, all verified on actual processes and signals. At the end you assemble everything into a capstone IT service desk agent and can also deploy it with docker-compose or Kubernetes.

Who it's for

This is for developers who already know how to call LLM APIs from code but want to learn how to design, build, and operate agent systems that are reliable, secure, and controllable in a real enterprise setting. It suits engineers who want to move past demo-level examples and understand every layer of an agent, including the failure modes and how to recover from them.

Highlights

• 32 lessons, bilingual (Chinese/English), each with exercises and automated offline deterministic tests.
• Hand-written agent runtime: approximately 3,800 lines of core async code plus 2,000 lines for distributed modules, built without any agent framework.
• Real multi-process execution: lease queues, fencing, crash takeover, zombie worker recovery, graceful shutdown—all proven with actual processes and signals.
• Enterprise problem cards: every major issue comes with 2–5 solution options compared on pros, cons, and applicable scale.
• Migration path: start with SQLite and in-process state, then swap to Postgres, Redis, Temporal, OpenTelemetry, LiteLLM, and Cedar without changing the agent code.
• Capstone project (ITBuddy) that ties everything together, plus a 24-case evaluation suite including 10 security cases.
• Extensive reference docs: 79 failure modes, 199 design review checklist items, 76 interview questions, 246 glossary terms, and a production readiness guide.
• Works with any OpenAI-compatible endpoint (OpenAI, DeepSeek, Qwen, vLLM, etc.) and includes a --offline mode using a scripted LLM for zero-cost learning.