Choose a track

Six source-backed flow tracks and overviews, each grounded in a flow that actually ships in the demo application. Start with BasicFlow.

Every lesson on this site is derived from a real, running flow in pico-demo/src/myflow. Nothing here is a sketch: the code quoted in a lesson is the code the demo NestJS application loads, and the transitions described are the ones the end-to-end tests assert against the persisted session document.

There are six flows represented here. They overlap deliberately — each one is a complete workflow, not a fragment — but each was written to make a different set of framework features unavoidable.

The six flows

BasicFlowthe complete tour Fourteen registered steps covering tools, MCP, logic steps, structured output, nested execution, memory namespaces, and batch mode. Eighteen lessons. HotelFlowmulti-turn assistant A search, compare, and book workflow. Large prompt files, your own backend behind a tool, memory compaction, and answering without an LLM call. InvoiceFlowone-shot extraction No conversation to speak of. Attach a PDF or PNG, extract typed JSON, return it with a content type, and fan the same job out over a list of files. SupportFlowguided support case Verify an order, route returns or billing, apply policy in deterministic steps, obtain approval when required, and close the case with a durable recap. HomeInsuranceQuoteFlowregulated quote journey A twenty-turn intake, correction, deterministic rating, exact comparison, re-rating, option selection, and consent workflow. EmployeeBenefitsFlowguided benefits enrollment A twenty-two-turn eligibility, household, plan comparison, account-limit, ancillary-benefit, beneficiary, review, and enrollment workflow, with seven implementation lessons.

What each track demonstrates

Feature	BasicFlow	HotelFlow	InvoiceFlow	SupportFlow	Home insurance	Employee benefits
Zod tool definitions and `@Tool` handlers	yes	yes	yes	yes	yes	yes
Multi-tool batching with `@Tools([...])`	yes	no	no	no	no	no
MCP server behind a tool handler	yes	no	no	no	no	no
`LogicStep` (no model call)	yes	no	no	yes	yes	yes
Structured output via `structOutputSchema()`	yes	no	no	no	no	no
Nested execution: `runStep()` / `runSteps()`	yes	no	no	no	no	no
Memory compaction and summarisation	no	yes	no	yes	yes	yes
`direct()` responses with no second model call	no	yes	yes	no	yes	yes
Multimodal file uploads	no	no	yes	no	no	no
Batch mode via `spawnSteps()` + `concurrentSteps()`	yes	no	yes	no	no	no
Per-step model overrides	yes	yes	yes	yes	no	no
Named memory namespaces	yes	yes	yes	yes	yes	yes
Custom session restoration	no	no	no	yes	yes	yes

Which one first

Read BasicFlow first, even if your production workflow looks more like HotelFlow. BasicFlow is the only track that exercises the whole Step contract, and the later tracks assume you already know what go(), stay(), saveState(), and a memory namespace are. The BasicFlow track spends its first six lessons on exactly those fundamentals and only then moves into composition.

BasicFlow is also a slightly artificial flow. It asks for the weather in two cities, then your favourite colour, then your name, then your date of birth, then your address. No product would be shaped that way. It is shaped that way so that every lesson has a step that isolates one framework idea, and so the end-to-end test can walk a single deterministic eight-turn path through all of it.

Note

The demo application registers all six flows in one NestJS module and serves them from one endpoint, POST /ai/run. The flowName field in the request body selects which flow a session belongs to. A session is bound to exactly one flow for its lifetime.

Running the code alongside the lessons

Every lesson names the demo file it quotes, in the source line under the page title. Open that file while you read. Two commands cover most of what you need:

npm run start:dev
npm run test:basic-flow

The first starts the NestJS application on port 8000. The second replays the scenario in test/basic-flow/basic-flow.scenario.json through the real HTTP controller and asserts both the assistant’s wording and the persisted step cursor after every turn.

Start with the BasicFlow track overview, which maps all fourteen steps before the first lesson. For a regulated money boundary, continue to the HomeInsuranceQuoteFlow overview. For a wider enrollment journey with several deterministic policy boundaries, continue to the EmployeeBenefitsFlow overview.

The six flows

What each track demonstrates

Which one first

Running the code alongside the lessons

Next