Concepts
This is the foundations layer: the ideas behind multi-agent systems, explained for a developer who is competent but new to the AI/agent world. You do not need to know what an agent is, what “multi-agent” means, or what a guardrail is for before you start — every term is defined before it is used.
Every page follows the same shape:
- What it is — plain language, one honest analogy, no jargon in the definition itself.
- Why it matters — the concrete problem it solves, and what breaks if you skip it.
- When to use it — and when not to. Explicit non-use cases.
- How it works here — the pattern running in this application, with a link to the real source file and the symbol named in prose, plus a diagram of the real path.
The repository is the source of truth for these ideas. Nothing here depends on an external article — read this, then read the file it points at, and you have the whole picture.
Not sure you are ready for this layer? The AI Knowledge Hub sits below it: eleven modules and ten labs taking you from a model running on your laptop to an agent in production, free and local. These pages assume you can read code and want to know why a pattern exists; the hub assumes less and has you build each idea yourself first. Individual pages here link to the matching hub module where one exists.
Two reading paths
New to agents — start here. Read in order:
- What is an agent
- The agentic loop
- Tools
- The agent harness
- Why multi-agent
- Orchestration patterns
- Graphs in agent systems
By page 7 you have the full vocabulary this repo uses, and you can either keep going below or jump straight to docs/architecture.md to see how the six agents in this codebase are actually wired together.
Already know agents — show me the system. Skip straight to docs/architecture.md for the system-level view, and come back to individual pages here when a term needs unpacking.
The rest of the pages
| Page | What it answers |
|---|---|
| 08 — State, memory, and sessions | Why agents are stateless by default, and the three different things people call “memory” |
| 09 — Grounding and RAG | Why models fabricate, and the difference between retrieving data and verifying a claim |
| 10 — Guardrails | The threat model in plain terms, and what each defensive layer can and can’t stop |
| 11 — Human-in-the-loop | Why some actions must never run unsupervised, and two different ways to gate them |
| 12 — Evaluation | Why “it looked right in the demo” isn’t evidence, and what to measure instead |
| 13 — Observability and cost | Tracing a request across six services, and tokens as the unit of cost |
| 14 — Production concerns | Idempotency, retries, rate limits — what turns a demo into a system (and an honest look at what this repo does and doesn’t have yet) |
How this fits together with the rest of the repo
Four layers, each answering a different question:
docs/concepts/ "What is this idea, and why would I reach for it?"
tutorials/NN "Show me — I'll build a tiny version myself."
agents/python/ "Here it is doing real work, at scale, in production code."
docs/architecture.md "How does the whole system fit together?"
Nothing here is a summary of a blog post. If a concept page and the code it points to ever disagree, the code is right and the page is out of date — please open an issue.
Source: docs/concepts/README.md — this page is generated from the repository.