Samples live under
samples/. Shared glue
is in Voluta.Samples.Shared.
They are teaching tools, not product templates. Each one isolates a concept so you can see the runtime without five concerns fighting in one file.
Catalog
| Sample | What it is for | Command |
|---|---|---|
| 01 — Hello World | The core loop: channels, cycle, StreamMode.Updates, in-memory checkpoints | dotnet run --project samples/01-HelloWorld |
| 02 — Interrupt / Resume | Human-in-the-loop: pause, inspect payload, resume with a Command | dotnet run --project samples/02-InterruptResume |
| 03 — AOT Smoke | “Does the core publish under Native AOT?” Linear graph, publish path | dotnet run --project samples/03-AotSmoke · dotnet publish samples/03-AotSmoke -c Release |
| 04 — ReviewBot | Multi-node plan → sandboxed tools → review (more realistic shape) | dotnet run --project samples/04-ReviewBot -- --offline --root . |
| 05 — DocQ | Docs Q&A over a sandboxed folder (tools + questions) | dotnet run --project samples/05-DocQ -- --offline --root . --question "What is voluta?" |
Suggested order (and why)
01-HelloWorld— If you skip this, the rest feels like magic. You need the feel of a superstep, a conditional edge, and streaming once.02-InterruptResume— This is the durability story. Same thread id, different process (or at least a second call): interrupt → checkpoint → resume. Almost every production agent eventually needs “wait for a human.”03-AotSmoke— Only if AOT / publish size matters to you. Otherwise leave it until later.04/05— When you want multi-node structure and tool-ish side effects without inventing your own sandbox.
How to read a sample
- Run it once. Watch the stream.
- Open the graph builder section — channels first, then edges. Ask: why this kind?
- Open one node. Ask: what does it write, and what does it leave alone?
- Only then read helpers / CLI flags.
If a sample feels “too big,” go back to 01 and re-draw the topology on paper. The runtime is small; the sample surface grows with the scenario, not with framework ceremony.