Skip to content
Meftun Akarsu
A 17-part course

Agents from First Principles

Most agent tutorials hand you a framework and a black box. This one builds the whole thing by hand, one concept at a time, so you understand every moving part: the reason/act/observe loop, typed tools, memory, planning, reflection, durability, and how to make a multi-agent system observable, secure, and graded in production. Retrieval is demoted to one tool the agent may call. Every part runs on a single example you can follow end to end, with runnable code and an interactive figure.

Start with Part 1: The Augmented LLM Code on GitHub (opens in a new tab) Glossary

Core track · Parts 1–11

  1. Part 1: The Augmented LLM 18 min read · code A bare model cannot touch your data or act. The augmented LLM (a model ringed by typed tools in the smallest loop with a stop condition) can. Part 1 names the primitive, draws the do-you-even-need-an-agent ladder, and gives tools a contract.
  2. Part 2: When Tools Fail 16 min read · code A schema-valid tool call can still throw, time out, or return garbage at run time. The fix is a robustness layer: a failure taxonomy, bounded retries, and an idempotent refund tool.
  3. Part 3: Planning the Work 14 min read · code ReAct pays an LLM call per hop, so the bill balloons and the plan is re-derived every step. Making the plan a first-class artifact (plan-and-execute, ReWOO, the tool DAG) cuts LLM calls and critical-path depth.
  4. Part 4: Surviving a Broken Plan 14 min read · code An up-front plan is a bet that the world will not change. When a SKU is discontinued mid-run, a prospective critic and an error-triggered replanner that revises only the remaining steps save the run.
  5. Part 5: Learning from Failure 13 min read · code Replanning recovers within a run, but the agent repeats the same mistake across runs. In-loop self-critique fixes what it can see; Reflexion writes a verbal lesson to a buffer the next trial reads.
  6. Part 6: The Four Memories 14 min read · code A flat buffer cannot separate what happened from what is true from how to do a task, and read-only tools cannot update state. Four typed stores plus self-editing memory fix it.
  7. Part 7: Surviving the Long Haul 16 min read · code A long run overflows the window and a grow-only store turns to noise. Hot/warm/cold compaction bounds the window; forgetting (decay, supersede, evict) keeps memory useful.
  8. Part 8: Stopping the Runaway 15 min read · code An agent that never gives up retries a dead search forever and burns the budget. Multi-dimensional budgets, a loop detector, and a circuit breaker trip it to a graceful partial result.
  9. Part 9: The Durable Agent 18 min read · code A crash mid-run loses the half-issued refund and a naive restart re-charges the customer. A journal, replay, and idempotency keys make the agent effectively-once.
  10. Part 10: Pause, Approve, Resume, Steer 17 min read · code Some actions need human approval and a user may want to correct the agent mid-run. A journal-backed interrupt, resume, and steer put a human in the loop, durably.
  11. Part 11: Shipping It 19 min read · code A durable agent you cannot see into is undebuggable. Fold the same journal into OTel-shaped spans for trajectory, cost, latency, and cost-per-success.

Frontier track · Parts 12–17

The protocol wire and multi-agent territory you reach for once the single agent is solid: MCP, sandboxed code, supervisors and handoffs, A2A, security, and evaluation.

  1. Part 12: Tools as a Protocol 19 min read · code Tools are a hardcoded dict no other host can discover. A minimal MCP server and host by hand turn tool use into a JSON-RPC wire protocol with discovery and multiplexing.
  2. Part 13: The Code-Running Tool 18 min read · code Agents need to run code and act on a screen, not just call JSON tools, and that power is dangerous. A sandbox permission boundary contains it. The toy is illustrative.
  3. Part 14: The Supervisor and the Handoff 19 min read · code One agent with one context cannot parallelize breadth-first work and is overkill for a specialist. Orchestrator-worker fan-out, handoff-as-a-tool, honest economics.
  4. Part 15: Agent to Agent 16 min read · code A handoff stops at the process boundary; a billing agent owned by another team is unreachable. A2A Agent Cards, JSON-RPC delegation, and a trust allowlist cross it.
  5. Part 16: Securing the Agent 19 min read · code An agent with tools, memory, code, and untrusted content is an attack surface. The lethal trifecta and indirect prompt injection, beaten by breaking a leg.
  6. Part 17: Grading the Agent 21 min read · code Eyeballing checks only the answer, so a right answer via a wrong, expensive, or unsafe path passes; a three-layer eval and a regression gate catch it. The finale.