Agent runtime engineering with Sophos
From cognokratos/sophos-agent · docs/runtime/README.md · pinned revision 8d9fe52182d8
Educational material: the why, the experiments and the failure modes. The precise what and how live in the architecture reference.
| I want to… | Go to |
|---|---|
| Learn production agent fundamentals (loops, tools, MCP, guardrails, evals, HITL, security) | simple-agent-template — Learning path |
| Understand durable execution and runtime state | Runtime learning path |
| Follow one run end to end | Run lifecycle walkthrough |
| See how the architecture evolved, and why | Case studies |
| Test myself | Challenges |
| Look up exact implementation details | Architecture reference |
| Set up the labs | Lab environment |
Lessons
- Own the process — every resource has a creator, an owner and a closer
- Model execution state — conversation, thread, run, checkpoint
- Design durability boundaries — persist semantics, not everything
- Streaming is not persistence — transport vs truth
- Memory is not one thing — six responsibilities, six owners
- Failure, restart and resume — recovery as part of the model
- Side effects and idempotency — what checkpointing does not solve
- Local-first and runtime ownership — data flows, not labels
Lesson structure
Each lesson follows the same shape, so you can skip to the part you need:
Objective → Why it matters → Mental model → Where it lives in Sophos
→ Experiment (predict, break, inspect, recover)
→ Why the system behaves this way → What this does NOT guarantee
→ Takeaway → Go deeper
Predict before you inspect. The point of each lab is the gap between what you expected and what the runtime did.
Ground rules
- Disposable state only. Labs use
data/lab/(lab environment). Nothing in this curriculum asks you to deletedata/db/ordata/memory/. - Current code only. Everything described as behaviour is implemented on
main. Lab results were observed while writing the labs; a few edge cases are read from the code, and the lessons say so. Anything that is not implemented is labelled challenge or future design. - Model output is observed, not guaranteed. Tool choice and wording vary between models and runs. Runtime behaviour does not.