简体中文 · English
Notes I took while developing Reina, a desktop AI agent, covering how coding agents (tools like Claude Code, Codex, opencode) work internally. Each note covers one mechanism, simplified from Reina's production implementation into a zero-dependency, single-file, runnable Node program — so these approaches aren't guessed from API docs; they're validated in a real product.
Node 18+, zero dependencies:
git clone https://github.com/7-e1even/learn-agent && cd learn-agent
AGENT_API_KEY=sk-xxx node s01_agent_loop/agent.mjsAny OpenAI-compatible API key works (DeepSeek / Kimi / GLM / OpenRouter / local Ollama); without one, most notes' demo.mjs and s12's self-test mode need no key at all.
s01–s12 build a complete, usable agent from scratch — read them in order; s13 onward are boundary problems I ran into (and wrote down) while developing Reina — pick what interests you. Each note ends with a pointer to the corresponding production code in Reina.
| # | Topic | The question it answers |
|---|---|---|
| s01 | The agent loop | What does the smallest usable agent look like? |
| s02 | Tool system | How do you keep adding tools without touching the loop? |
| s03 | Loop budget & correction | The model spins in place or keeps erroring — how do you catch it and pull it back? |
| s04 | Tool-output budget & spill | One cat can overflow the context — what then? |
| s05 | Streaming & interruption | The user hits Ctrl+C mid-response — how do you repair the half-broken message history? |
| s06 | Context compaction | The context is full and must be compacted — how do you not forget the original task? |
| s07 | Prompt caching | Same conversation — why is someone else's bill 10× cheaper? |
| s08 | Session persistence & resume | The process crashed half an hour in — how does the session pick up where it left off? |
| s09 | Subagents & watchdog | A subtask hangs — how do you notice, and keep the work it already finished? |
| s10 | System-prompt assembly | The system prompt keeps growing — how do you assemble it on demand? |
| s11 | Multi-agent coordination | Several agents working at once — how do they split work without duplicating or colliding? |
| s12 | Full agent assembly | What do all the previous mechanisms look like back in one loop? |
| s13 | Permissions & approval | The model wants to run rm -rf — how do you stop it before it acts? |
| s14 | Provider compatibility | Switch models and the tool calls come out mangled — how do you stay compatible? |
| s15 | Progressive tool disclosure | Dozens of tools — how do you keep them from filling the context? |
| s16 | MoA multi-model deliberation | Letting several models deliberate together — is it worth it? |
| s17 | Self-evolution review loop | Can the agent review its own conversations and distill what it learned into memory and skills? |
| s18 | Completion gate for autonomous runs | The agent says "done" — why should you believe it? |
| s19 | Compaction vs. prompt cache | Compaction inevitably busts the cache — how do you minimize the damage? |
Spotted a factual error or a code bug? Please open an issue. MIT License · © 2026 7-e1even