The Agent Harness course
A hand-drawn course following one real agent from a customer's message to the real code.
1 · Purpose
This course follows one real agent, the motor-insurance claims assistant on Azure, from the moment a customer types to the moment the reply goes back. It comes in two parts: a hand-drawn tutorial where every box opens the next level down until you reach the code, and a deep-dive Series with each of 22 concerns on its own page. It is for engineers and architects who can call a model but have not yet built everything around it. Real numbers, traces and code come from the live agent, and anything not yet built is labelled so.
2 · Business benefits
3 · Status and how to join
Good first tasks this week:
- Read the tutorial start to end and list unclear pages
- Draft an exercise for one lesson
- Check the code on three pages still matches the repository
4 · Requirements
What it must do
- Shows the architecture as drawings, from one block down to each component.
- Follows one message end to end, with every box linking to its design page.
- Draws 19 real conversation flows as the path each message took.
- Compares tech choices for 22 concerns: what we chose, Azure options and open-source options.
- Shows real code, call stacks and class diagrams on design pages.
- Covers cost, testing, evaluation and observability, each on its own pages.
How well it must do it
- Plain words and black-and-white drawings, readable without a cloud background.
- A build fails if any link points to a page that does not exist.
- Code snippets print "code not found" when the source moves, rather than going stale silently.
- The publish step redacts cloud account ids and resource names on every page.
- Each detail is written once, in its own page, and linked from elsewhere.
5 · Architecture, very high level
6 · Tech stack, per platform
| Component | Open stack | Azure | AWS |
|---|---|---|---|
| Content sources | — | the claims agent on Container Apps, API Management, Entra ID and Application Insights ✓ | not covered |
| Drawing kit | inline SVG ✓ | — | — |
| Builder | Python static site generator ✓ | — | — |
| Publisher | GitHub Pages ✓ | — | — |
7 · What needs to be done
The Series 2 of 3 done
| Task | Status | Size | Skill |
|---|---|---|---|
| 22 concerns, each on its own page | done | L | AI architecture |
| Live flow pages from real Azure turns | done | M | Observability |
| Study the flows not yet covered, such as withdrawing a claim | todo | M | AI architecture |
The tutorial 3 of 3 done
| Task | Status | Size | Skill |
|---|---|---|---|
| Hand-drawn pages from architecture down to code | done | L | Technical illustration |
| Real code, call stacks and class diagrams on design pages | done | M | Python |
| Tech comparisons for every concern | done | M | Cloud and open source |
Published 1 of 3 done
| Task | Status | Size | Skill |
|---|---|---|---|
| Live at /learn/agent-harness/ with a redacted Series | done | S | Web publishing |
| One page per lesson with a short exercise | todo | M | Teaching |
| Add a data engineering course in the same style | todo | L | Data engineering |
8 · Roles
| Role | How many | Hours / week | What they do |
|---|---|---|---|
| Course reviewer | 2 | 1-2 hours/week | Reads pages as a newcomer and reports what was unclear. |
| Content author | 1 | 3-5 hours/week | Writes and draws new pages from the live agent. |
| Exercise designer | 1 | 2-3 hours/week | Writes hands-on exercises for each lesson. |
9 · What you'll learn
- What sits around a model call in a production agent, and why.
- How one message travels through sign-in, routing, the loop, tools and checks.
- How to choose between Azure services and open-source tools per concern.
- How evaluation, cost and testing are designed into an agent.
- How to read real agent code with a call stack and class diagram beside it.
Level-up questions
- Which step in one message's journey would fail first under load?
- Where in the loop would you put a check that blocks a reply?
- When does an agent need durable execution rather than a simple retry?
- What would you change to run the same agent on a different cloud?