Tiny-Agent: From One Model Call to an Engineered Agent System

Language: English | 简体中文

Many Agent tutorials start by installing a framework and calling create_agent(). The demo works. The harder questions arrive later: Why did the model repeat a Tool? Why did retrieval become “truth”? Who owns the side effect? What survives a restart? Why did context become unstable?

Tiny-Agent takes a mechanism-first path.

This is a zero-to-Agent engineering course. It begins with model calls, Structured Output, Tool Calling, runtimes, workflows, state, and retrieval. Only after those foundations exist do MCP, memory, context engineering, Skills, safety, evaluation, Multi-Agent coordination, sandboxing, production services, and long-horizon execution appear.

Frameworks are welcome, but they do not arrive before the problem they solve. The goal is not to memorize one generation of APIs. It is to be able to design a new Agent system and explain which decisions need a model, which control flow should remain ordinary code, what the model may propose, what the application may execute, and how the system stops, recovers, gets approval, and proves quality.

Course map

The curriculum uses continuous integer Stages from 00 to 15.

The intended path is sequential because later boundaries are built from earlier ones.

How to study each Stage

Each Stage is self-contained:

stages/<stage>/
├── README.md
├── README.zh-CN.md
└── code/

The README is the lesson. Code blocks inside the lesson show only the mechanism currently under discussion. The complete runnable program lives under that Stage's code/ directory.

A useful learning loop is:

read one section
    ↓
inspect the local snippet
    ↓
explain the problem it solves
    ↓
run the complete demo
    ↓
run checks.py / runtime_checks.py
    ↓
break one invariant deliberately
    ↓
explain the failure

Do not study only the happy path. Rejected inputs and bounded failures often teach the architecture more clearly.

Running the code

Python 3.10+ is the baseline.

Many later Stages use only the standard library:

python stages/06-memory-persistence-hitl/code/demo.py
python stages/06-memory-persistence-hitl/code/checks.py

Stages with external dependencies declare them locally in code/requirements.txt:

python -m pip install -r stages/05-mcp/code/requirements.txt
python stages/05-mcp/code/in_memory_client.py
python stages/05-mcp/code/checks.py

The repository does not require one global “install every Agent dependency” environment. Install what the Stage you are studying actually needs.

Early stages include real provider adapters and explain their environment variables in the chapter. The course checks prefer deterministic model doubles, fake clients, or offline data whenever the invariant itself does not require a live model. A runtime should not need a lucky online generation to prove that it rejects unauthorized Tools, stops a loop, or avoids duplicate side effects.

Why mechanisms come before frameworks

An abstraction becomes much easier to use when you know what it hides.

Stage 03 derives State, Node, Edge, and Reducer semantics before mapping them to LangGraph. Stage 04 derives chunking, vector representation, similarity, and Top-K retrieval before using vector backends. Stage 05 separates Function Calling from external protocol interoperability before introducing MCP.

This is not anti-framework. It is how frameworks stop feeling magical.

One principle repeated throughout the course

If you remember one invariant, remember:

Proposal is not authority.

The model may propose a Tool Call, Route, Plan, Memory Candidate, refund action, or delegation. Retrieved content may be relevant. A Skill may recommend using a capability. Another Agent may ask for work.

None of those facts automatically grants execution authority. Application-owned validation, policy, ownership, approval, authorization, and execution boundaries remain explicit.

Repository structure

The repository intentionally stays course-shaped:

Tiny-Agent/
├── README.md
├── README.zh-CN.md
├── CONTRIBUTING.md
├── CONTRIBUTING.zh-CN.md
├── LICENSE
└── stages/
    ├── 00-foundations/
    ├── 01-react-runtime/
    ├── ...
    └── 15-capstone-enterprise-agent/

Each Stage owns its complete teaching implementation and executable checks. There is no second global implementation or test tree that students must reconcile with chapter code.

Prerequisites and outcome

Basic Python is enough to begin: functions, classes, dict / list, exceptions, basic JSON, and running Python from a terminal. Async programming, SQLite, subprocesses, graph orchestration, and service concepts are introduced when the course reaches a problem that needs them.

Finishing the course should mean more than “I can use an Agent framework.” Before choosing a framework for a new system, you should be able to reason about model decisions, structured contracts, Tool authority, state scope, durability, memory policy, context selection, evidence, retries, idempotency, approval, authorization, execution isolation, tracing, evaluation, service identity, and worker recovery.

When those boundaries are clear, frameworks become implementation choices rather than architecture substitutes.

Start with Stage 00.

Star History

Track Tiny-Agent's growth on Star History.