Find your path through Runifold
Choose a learning path, understand the execution model, and know which guide to read next.
Run the 5-minute Quickstart first. Then use the Cookbook for your product task or take the 45-minute core course for the complete mental model.
Explore the whole platform
Runifold is not only an Agent library. Start from the product surface you actually need:
| Surface | Core guides |
|---|---|
| execution kernel | RunContext, capability security, checkpoint recovery |
| models and providers | model protocol, Provider Runtime, provider testing |
| Agents | Agent construction, tools, conversation |
| durable workflows | Workers, parallelism, versioning, tenancy |
| integrations | MCP context and Sampling, MCP Tasks, retrieval pipelines, storage |
| quality and operations | evaluation CLI, Task governance, SLOs, trusted releases |
Read the complete platform architecture before designing a system that crosses more than one surface.
Choose a learning path
Runifold lets a small model call grow into a bounded, observable, recoverable system without switching to a second orchestration abstraction. You do not need to learn the whole runtime before starting.
| If you want to… | Start here | Then read |
|---|---|---|
| call a model from Rust | First trustworthy run | Choose an execution API |
| choose and configure a model service | Provider setup | Provider Runtime, Provider testing |
| build a tool-using Agent | Build an Agent | Typed tools, structured output |
| build a chat or assistant | Conversations and memory | Retrieval, streaming |
| coordinate specialized Agents | Delegation | Budgets and cancellation |
| run long-lived business work | Workflows | Durable workflows, effects |
| expose a Rust API | Deploy a web service | RunContext, observability |
| ship to production | Testing | Evaluation, observability, reliability |
If this is your first visit, complete the first-run tutorial before opening the reference-oriented guides. It establishes the vocabulary used everywhere else.
The execution model
Five ideas connect the entire API:
- Run — every execution has identity, a parent, a lifetime, and shared accounting.
- Event — the runtime records semantic state transitions separately from model-visible conversation.
- Capability — registering a callable says what exists; granting a capability says what this run may use.
- Effect — external writes have explicit recovery and idempotency semantics.
- Checkpoint — durable progress can be resumed without pretending an interrupted operation definitely failed.
This separation is the reason an ergonomic prompt_text call and a durable
multi-worker workflow can share the same execution kernel.
From prototype to production
Add constraints when the product needs them:
| Stage | Add | Why |
|---|---|---|
| Explore | prompt_text | shortest path to visible text |
| Integrate | typed output and Tools | stable application contracts |
| Bound | explicit RunContext | budgets, authority, deadline, cancellation |
| Resilient | routing and effects | safe recovery around uncertain networks |
| Durable | checkpoints and workflows | survive restarts and long waits |
| Operate | journals, OTel, tests, evaluations | explain and improve behavior |
Do not add every layer by default. A single classification endpoint may never need a workflow; a payment workflow should not rely on a prompt to define its transitions.
Where to look
- This site teaches tasks, decisions, and production consequences.
- docs.rs for 0.9.0 is the authoritative item-level Rust API reference.
- GitHub examples are compile-checked application patterns.
- Architecture RFCs explain why contracts exist and which alternatives were rejected.
- Provider support and reliability evidence are release-specific sources of truth.
When a guide and the API reference appear to disagree, pin the crate version, check the reference for that version, and report the mismatch with a minimal reproduction.
For quick answers, use the FAQ. For failures, follow the Troubleshooting guide before opening an issue.