Understand the complete Runifold platform
See how the execution kernel, model protocol, Agents, workflows, stores, MCP, evaluation, and observability fit together.
The platform in one view
Runifold is not only an Agent framework. It is a layered execution platform:
The application chooses the product surface. Every surface reuses the same identity, cancellation, budget, capability, event, and effect semantics. A workflow can call an Agent; an MCP Task can represent a workflow; an Agent can use retrieval and typed tools; all of them can share one causal Run tree.
Seven product surfaces
| Surface | Owns | Does not own |
|---|---|---|
| execution kernel | identity, lifetime, authority, accounting, events | model or workflow policy |
| model protocol | provider-neutral request, stream, response, capability evidence | Agent loops |
| Agents | model-tool loop, structured output, conversation, delegation | durable business transitions |
| workflows | deterministic composition, checkpoints, workers, waits, leases | prompt semantics |
| integrations | MCP, retrieval, vector stores, SQL stores | application authorization |
| evaluation | deterministic doubles, scorers, experiments, CI gates | production traffic |
| observability | traces, metrics, journals, SLO assets | business reconciliation |
This separation lets you use the model layer directly, build a deterministic workflow with no Agent, or expose durable work over MCP without pretending every workload is a chat assistant.
Crate map
| Crate family | Main responsibility |
|---|---|
runifold-core | Run IDs, context, budgets, cancellation, capabilities, events, journals |
runifold-model, runifold-providers | canonical model protocol and provider adapters |
runifold-tool, runifold-agent, runifold-effect | callable boundaries and Agent execution |
runifold-workflow | durable orchestration, workers, waits, tenancy, retention |
runifold-mcp, runifold-retrieval* | external capability and knowledge edges |
runifold-store-* | SQLite and PostgreSQL durability |
runifold-testkit, runifold-eval-cli | offline correctness and quality evidence |
runifold-observability-otel | OpenTelemetry and operational policy |
runifold | feature-gated facade that re-exports the public platform |
Applications normally start with the facade. Infrastructure libraries can depend on narrower crates to keep dependency and feature boundaries explicit.
Choose your entry point
| You are building | Start with |
|---|---|
| one provider-neutral model call | Model protocol |
| a bounded model-and-tool loop | Agents |
| deterministic multi-step business work | Workflows |
| restart-safe background execution | Workflow workers |
| an MCP server or client edge | MCP |
| durable MCP operations | MCP Tasks |
| quality gates for model behavior | Evaluation CLI |
| production platform operations | SLO operations |
Architectural laws
- Streaming is the source of truth for model invocation.
- A Run owns control state; conversation history is separate model context.
- Registering a callable does not grant authority to execute it.
- External writes cross an explicit Effect boundary.
- Durable recovery never guesses that an ambiguous operation failed.
- Workflow ownership is fenced; a stale Worker cannot commit.
- Tenant identity is part of authorization, accounting, and storage lookup.
- Reliability claims name the evidence that supports them.
These laws are more stable than individual builder methods. Learn them first; use the API reference for the exact version you compile.