Viable Agents — a course, not a feature tour

Build your own agent harness.

Most agent courses teach you the buttons. This one teaches the control system, and you leave holding a harness you wrote yourself: regulator. Each module opens with a regulatory question an autonomous agent forces on you, derives the mechanism that answers it, then shows the Pi feature and the typed treatment underneath regulator, the control plane this course is built against.

Prompts advise. Types describe. Gates enforce. The premise the whole course is organized around
Why cybernetics

Agents need a regulator, not just a good prompt

The Viable System Model (VSM) is Stafford Beer's answer to an old question: what does any system, whether an organism, a company or an autonomous agent, need structurally to stay viable while its environment keeps generating more variety than anyone predicted? Ashby's Law gives the constraint: only variety can absorb variety, so a regulator with fewer possible responses than the disturbances it faces will eventually fail somewhere it can't see. A model plus a good prompt is not a regulator. It is a hope, and hope doesn't survive contact with a real codebase, a real filesystem, or real money moving. This course treats the harness itself as the regulator: explicit functions, typed channels, and gates that hold when the prompt is ignored or the model changes, and even when the task has nothing to do with code. More on VSM and the six functions →

Who it's for

Not a prompt pack, not a persona library

If you've used an agent for real work and hit its limits, this course gives you the vocabulary and the mechanism to fix that inside a harness you write yourself.

WhoWhat this course gives you
Senior / staff engineersrunning agents on real codebases: a principled reason for every guardrail, tuned to their repo.
Platform & DevEx teamsa design method for an internal agent platform, plus the evaluation machinery to prove it helps.
Agent-tool buildersdeep Pi extension/SDK competence and a structural critique of "five agents in a trench coat."
Technical leadersa vocabulary for where autonomy is safe, and what evidence would demonstrate it.

By the end, you can

  1. Describe an agent harness as a control system: what regulates what, over which channel, with what authority, closing which feedback loop.
  2. Apply the mechanism hierarchy instead of solving every problem with prompt text.
  3. Extend Pi confidently: typed tools, the tool-call lifecycle, context shaping, per-phase model routing, SDK/RPC, packaging.
  4. Design work units as instead of prose task descriptions, with each decision marked fixed (not up for grabs), delegated (the agent chooses, within bounds), or unresolved (nobody's decided yet).
  5. Build audit that does not depend on the executor's self-report.
  6. Keep system identity durable and version-controlled instead of trapped in a context window.
  7. Decide when a human must be interrupted, and build the channel that does it.
  8. Measure whether your regulation actually improved outcomes, with a control arm.

Three ways to take it

Self-paced

~40h + capstone

Repo, written modules, recorded walkthroughs, graded labs. Ends at reference-build checkpoint 14.

Cohort

6 weeks

Two 90-minute live sessions a week, labs between, design reviews, capstone crit.

Team intensive

2 days

Modules 01, 02, 03, 09 & 10 only. Labs run on the team's own repository.

Table of contents

Full syllabus — a primer, 15 modules, six parts

Every module is a fixed unit: question → concept → Pi mechanism → build step → break it → field study → checkpoint. The primer is the one exception: it teaches the cybernetics the rest relies on, with figures, and builds nothing. Modules 00 to 15 are written end to end in course/modules/. The capstone is specified in course/ASSESSMENT.md, and docs/PATHOLOGIES.md catalogs the ways a viable system fails as a whole (structural, functional, channel, and the agent-specific rows), each mapped to the regulator that absorbs it, the fixture that reproduces it, and what nothing absorbs yet.

PART 0Framing
00
A primer on cybernetics
Why describe a harness in the language of control, and what does the vocabulary buy?
The thesis, stated once: many ideas in the agentic-AI world can be restated in cybernetic terms, and restating them lets us talk consistently and concretely about the organizational forms that keep agentic work viable. Then the ideas the rest of the course leans on, each with a figure: the closed loop, variety and Ashby's law, attenuators and amplifiers, feedback delay, the Viable System Model function by function, recursion, the homeostat, and the algedonic channel. Last, a table that restates twenty agentic terms in cybernetic ones.
No Pi surface — reading, eight figures, paper exercises
Written
01
The harness is the regulator
Why doesn't a good model plus a good prompt suffice?
Set up the mental model the rest of the course builds on: the model supplies judgment, the harness supplies control. You'll sketch your own harness as a system diagram before writing a line of it, and see exactly where a prompt-only approach runs out of road.
CLI · TUI · sessions · -e
Written
02
Anatomy of a turn
Where exactly can I intervene?
Trace one agent turn through Pi's extension lifecycle end to end (tool call, tool result, session settle) and mark every point where your code, not the model, gets the last word. This map is what every later module hooks into.
Extension event lifecycle
Written
PART 1S1 — Operations
03
Tools as the variety interface
How does the agent act on the world, and how narrowly?
Register your first typed tool with a runtime schema instead of a loose function call, and see why what actually bounds an agent is the tool's declared effect (filesystem, execution, network), not its name or its docstring.
registerTool · typebox · truncation
Written
04
Capability profiles and the advisory layer
How do I specialize work without roleplay?
Retire the persona prompt ("you are a careful senior reviewer") in favor of a capability profile that grants real tools and real writable paths: the difference between asking an agent to behave and making it unable to do otherwise.
setActiveTools · skills · AGENTS.md
Written
PART 2S2 — Coordination
05
Isolation, leases, and the anti-oscillation problem
What stops two operations from fighting?
Give concurrent units their own worktrees and a time-limited lease that expires if whoever holds it goes quiet, then build the thrash detector that catches "fix A breaks B, fix B breaks A" before it burns through your whole budget.
pi.exec · worktrees · tool execution events · no-sandbox position
Written
PART 3S3 — Control
06
Work contracts: what you are actually authorizing
What am I actually authorizing this run to decide?
Stop writing task descriptions in prose. Declare a work contract that marks each decision fixed, delegated within bounds, or genuinely unresolved, then see how much ambiguity that removes from every review you'll ever do on this unit's output.
SDK sessions as a driver · typed session entries · extension flags
Written
07
Context and budget as regulated resources
What do I spend, and on what?
Turn tokens and turns into a metered, policy-governed resource: route cheap models to cheap phases, compact context without silently discarding a decision that mattered, and cut a run off before it runs away from you.
compaction hooks · ctx.abort · model_select · ModelRuntime
Written
08
Failure, recovery, and the retry lattice
What happens on attempt two, and on attempt six?
Design what happens after a unit fails: a versioned recovery policy that reads the failure and routes it, instead of a bare "try again," plus a durable effect journal so a crash mid-write never gets silently repeated or lost.
agent_end · agent_before_settle · effect journal · recovery routing
Written
PART 4S3* — Audit
09
Evidence, not claims
How do I know the work is done?
Build the closeout gate that never takes a unit's word for its own success. It re-runs the checks itself, against the exact commit, and produces a technical verdict that no amount of confident prose in the report can talk its way past. It also judges the unit by the test suite it inherited, so a failing test can't be made to pass by deleting it.
tool_call / tool_result hooks · host-run checks · the closeout gate · inherited-tests
Written
10
Authority boundaries and protected state
What must the agent never be able to change?
Draw a hard line around the files an agent must never edit on its own (identity, policy, invariants) and enforce it with a write preflight the agent literally cannot route around, instead of a rule it's merely asked to remember.
tool_call blocking · the write preflight · project trust · BOUNDARY.md
Written
PART 5S4, S5 & the algedonic channel
11
Environmental intelligence and the obligation lifecycle
How does the system learn about its world, and how does that knowledge get a say without becoming the decision?
Add a research unit that can raise a flag about the environment (a dependency advisory, a deadline coming due) and route it into an obligation that stays visible until a person or S3 actually resolves it, so intelligence gets a voice but never a vote.
research unit · report_intelligence · obligation ledger · routing policy · progression veto
Written
12
Durable identity and policy
Six months and four model versions later, what keeps this system the same system?
Move your harness's identity (its invariants, its policy, its domain model) out of any one session's context window and into version-controlled files that only a single, declared decision path is ever allowed to write.
identity set · identity-untouched check · remember · S5 decision path · definition check
Written
13
Algedonic channels and human interaction contracts
Normal regulation is not working and the loop cannot close. Who gets interrupted, how fast, and what counts as an answer?
Build the exception channel Beer called algedonic (literally "pain/pleasure"): the interrupt that skips the normal chain of command, plus the interaction contract that decides whether silence, a timeout, or a stray click ever counts as a real answer.
ask_human · interaction kinds · pause gate · outbox delivery · disposition authority
Written
PART 6Proving it and shipping it
14
Observability, evals, and longitudinal drift
You added all this regulation. Did it help, or does it just feel rigorous?
Run your harness against a scripted drift scenario with an ablation arm (the same system with one regulator switched off) and walk away with a statistically backed answer about what your guardrails actually bought you.
eval harness · arms and ablation · outcome and trajectory graders · export-signature · OpenTelemetry spans · review and retirement
Written
15
Packaging and operating your harness
It works on your laptop. How does your team run it on Monday, and who owns it in three months?
Ship the harness as an installable package with a CI entry point, a doctor command, and a review date on every regulator in the registry, so "who owns this, and is it still earning its keep" has a file behind it instead of a hallway answer.
pi package · regulator init · doctor · pre-merge trial · glossary-lint · watch · identity promote
Written
CAPSTONE — THE VIABILITY CASE

Present the finished harness as a control system, not a feature demo: a system map, a channel table, a mechanism ledger, an enforcement-boundary statement, evidence, the residual uncertainty that's still unresolved, and a boundary critique. The critique asks who may amend the system's purpose, who is affected but cannot challenge it, what its metrics conceal, and when the system itself should be retired. The harness you present has to have survived one run in which the regulatory machinery itself failed, not only its executor. The crit attacks from the course's catalog of pathologies, the ways a viable system fails as a whole.

The reference build

regulator — what you'll actually build

This isn't a hypothetical. regulator is the product itself, and it's already running end to end: the agentic loop, a versioned recovery policy, a that never trusts a unit's own report, and a read-only control room over all of it. You build it the same way, one checkpoint per lesson.

0–14
Lab checkpoints already built and tested, the exact path the course walks you through
44
Records in the registry, 42 active and two retired, each with a stated limitation, an ablation switch and a retirement condition
15 / 15
Modules written end to end, plus the primer. Nothing in the syllabus above is a placeholder

The full architecture (the control model, the orchestrator, the mechanism hierarchy, and the control room) has its own page. How a unit runs draws the mechanism out end to end, and the worked example declares a second workload, a household ledger instead of a codebase, to show what's yours to design versus what the harness already gives you.