Active Inference, The Learn Arc — Part 7: Chapter 6 — Ship Your First Agent, in Six Steps

#activeinference #elixir #ai #tutorial

Series: The Learn Arc — 50 posts teaching Active Inference through a live BEAM-native workbench. ← Part 6: Message Passing. This is Part 7.

The hero line

Ship your first agent — what's hidden, what's seen, what costs what.

Chapter 6 is the book's change of mode. Chapters 1–5 taught you the theory. Chapter 6 hands you a template: six questions you must answer to go from blank page to running agent. Answer them in order, wire up the matrices, press Run.

The Workbench's cookbook card format is derived directly from this template. Every one of the 50 recipes answers the same six questions.

The six questions

For any Active Inference agent, the design process is:

What's hidden? — list the hidden states s the agent will infer. (Positions in a maze. Which urn. Whether the coin is biased. Current context.)
What's seen? — list the observation modalities o. (Which cell's wall signature. Head vs tail. A bell tone.)
What can the agent do? — list the actions a. (Move cardinal. Draw from an urn. Sit still.)
What does what? — fill the A matrix P(o|s) (the sensor), the B matrix P(s'|s,a) (transitions), the D vector P(s₀) (initial prior).
What does the agent prefer? — fill the C vector P(o). This replaces the reward function.
Run and inspect. — boot the agent, step through, look at beliefs, policy posterior, and the signal river in Glass.

That's the whole design pipeline. Every Active Inference paper you'll ever read is answering some version of these six questions — sometimes with beautifully clean answers (Chapter 7's POMDPs), sometimes with messier ones (Chapter 9's fits to behavioral data).

The recipe card is this template

Open any cookbook card — say /cookbook/pomdp-tiny-corridor — and you'll see the six questions laid out one-to-one:

Title + level + tier — positions this recipe on the kid/real/equation/derivation learning-path ladder.
Math block — the core equation or decomposition the recipe demonstrates (answers "what does what" quantitatively).
Audiences — 4-tier plain-English walkthroughs. Answers "what's hidden / seen / actioned" at your vocabulary level.
Runtime — agent_module, world, horizon, policy_depth, preference_strength. Exact answers to "what does what" and "what does the agent prefer."
Actions used + Skills used — the blocks the agent is composed of. Think of these as the answer to "how does the model update?"
Cross-references — which equations, sessions, labs this recipe ties into.
Three Run buttons — Builder (open the canvas with the spec pre-loaded), Labs (one-click fresh-agent run), Studio (tracked-agent run with full lifecycle).

Every recipe in /cookbook has the same structure because every Active Inference model has the same structure. Chapter 6 is why.

From recipe to canvas

Chapter 6 shines when you stop reading recipes and start designing them. In the Workbench, that's the Builder canvas:

A recipe goes to the Builder via /builder/new?recipe=<slug>. Once the banner loads, you can:

Tweak A by adding an ObservationNoise block between the world and your agent's Perceive block.
Tweak B by swapping a transition skill (deterministic → stochastic → Dirichlet-learned).
Tweak C by adjusting the preference_strength parameter on Plan.
Add a second level of hierarchy by placing a second Perceive + Plan pair and wiring their messages.
Save+Instantiate — Mnesia stores the new spec, Studio picks it up, you can attach it to any world.

The Builder's Inspector validates everything server-side through Zoi before the spec can be saved. You never get a spec that compiles to a broken agent; the compiler refuses.

The Chapter 6 checklist

Running recipes is one thing. Designing your own is another. Chapter 6 ends with a practical checklist the Workbench uses to gate every new cookbook JSON before it's accepted:

Hidden-state cardinality is explicit and finite. (Or infinite-but-Gaussian for continuous-time.)
Observations are explicitly factored by modality. (Where the A matrix's columns come from.)
Every action has defined transition dynamics. (B is filled for every a.)
Every observation modality has a preference assignment. (C is non-degenerate.)
The initial prior D is either uniform or explicitly motivated.
The recipe's Math block cites at least one book equation.
At least one learning-path audience block is populated.

These are literally the checks in mix cookbook.validate. When the task reports "50 recipes, 0 errors," every recipe satisfies this checklist. That's not decoration; it's a contract.

The three sessions

Chapter 6 has three sessions under /learn/chapter/6:

States, observations, actions — the three lists you must produce first.
A, B, C, D — the matrix-filling step, with the pomdp-tiny-corridor recipe as the worked example.
Run and inspect — boot the agent, scan the policy posterior, read the Glass trace.

Work through them in order; at the end you'll have opened, edited, and run your first custom Active Inference agent.

Run it yourself

/cookbook — 50 recipes, all structured per Chapter 6's template.
/guide/cookbook — meta-guide: how to read any recipe card.
/builder/new?recipe=pomdp-tiny-corridor — open the canonical POMDP and start tweaking.
/guide/studio — Studio vs. Labs; when to use which.
/learn/chapter/6 — three workshop sessions.
mix cookbook.validate — the checklist above, enforced as CI.

The mental move

Active Inference has a reputation for being math-heavy and hard to ship. Chapter 6 kills that reputation in 20 pages: the design pipeline is six questions, and once you've answered them, the implementation is 200 lines of code. The Workbench makes that literal — every recipe is, under the hood, a ~200-line Jido agent spec.

The theory is deep. The pipeline is not.

Part 8: Chapter 7 — Active Inference in Discrete Time. POMDPs in full colour. Sophisticated planning (belief-propagated tree search), Dirichlet learning (the A and B matrices getting learned online, Eq. 7.10), and hierarchical composition (two agents talking to each other through a signal broker). The muscle chapter.

⭐ Repo: github.com/TMDLRG/TheORCHESTRATEActiveInferenceWorkbench · MIT license

📖 Active Inference, Parr, Pezzulo, Friston — MIT Press 2022, CC BY-NC-ND: mitpress.mit.edu/9780262045353/active-inference

← Part 6: Message Passing · Part 7: A Recipe for Designing (this post) · Part 8: Discrete Time → coming soon