Stable release · OpenRath v2.0.0
Durable, explicit multi-agent execution.
OpenRath v2 compiles explicit workflow steps into immutable plans, then persists Runs, Events, Checkpoints, Interrupts, and effect outcomes across worker restarts. The v1 Session and Agent façade remains available in v2.0.0.
Get Started with v2.0.0
Read v2 Overview
GitHub
```python
from pathlib import Path
from uuid import uuid4
from rath.context import RunContext
from rath.definition import EffectClass, step
from rath.flow import Workflow
from rath.runtime import LocalRuntime, SQLiteRunStore
from rath.session import Session
class DurableHello(Workflow):
@step(entry=True, effects=EffectClass.READ_ONLY)
def finish(self, state, context):
return {**state, "message": "hello from OpenRath v2"}
def forward(self, session: Session) -> Session:
return session
store = SQLiteRunStore(Path("openrath.db"))
runtime = LocalRuntime(store)
run = runtime.submit(
DurableHello(),
session_id=uuid4(),
context=RunContext.local(revision_id=uuid4()),
)
completed = runtime.work_once(worker_id="local-worker")
print(completed.status, completed.state)
```
The embedded path provides local durable execution with SQLite. Agent Server
deployments use PostgreSQL, explicit action grants, governed adapters, a
durable audit sink, and optional Redis and S3-compatible services.
## Where To Start
| Path | Use it for | Entry |
| --- | --- | --- |
| v2 quickstart | Install the v2.0.0 release wheel and run one durable workflow with SQLite. | [Quickstart](v2/quickstart.md) |
| v2 operations | Configure storage, rollout, incident, and recovery boundaries. | [Operations](v2/operations.md) |
| Migration | Bring v1 JSONL Sessions into the v2 history model. | [v1 → v2 migration](v2/migration.md) |
| Installation | Choose the v2.0.0 release asset or the v1-compatible PyPI path. | [Installation](install.md) |
| Project Status | Review v2.0.0 capability coverage and rollout guidance. | [Project Status](project_status.md) |
| v1-compatible tutorials | Learn the Session, Workflow, Tool, Sandbox, and Memory façade retained in v2.0.0. | [Tutorials](tutorial/index.md) |
| Release Notes | Review v2.0.0 features, compatibility, and upgrade guidance. | [Release Notes](releases/index.md) |
| Blog | Read project updates, release announcements, and engineering notes. | [Blog](https://blog.openrath.com) |
| Developer Notes | Understand runtime components, call boundaries, memory, and async behavior. | [Developer Notes](developer_notes/index.md) |
| API Reference | Look up public modules, function signatures, and integration points. | [API Reference](reference/index.md) |
## v2 Durable Model
| Concept | Role |
| --- | --- |
| `@step` / `@router` | Declares explicit, compilable execution and routing boundaries. |
| `ExecutionPlan` | Canonical graph bound to an immutable revision identity. |
| `Run` | Durable execution state with tenant, session, plan, and revision identity. |
| `Event` / `Checkpoint` | Records ordered lifecycle evidence and resumable per-step state. |
| Lease / fencing token | Prevents a stale worker from committing after ownership changes. |
| Effect ledger | Reconciles retries and ambiguous external side effects. |
| `AgentServer` | Exposes tenant/project-scoped HTTP and SSE resources behind explicit grants. |
## v1 Compatibility Model
| Concept | Role |
| --- | --- |
| `Session` | Carries ordered chunk rows, sandbox placement, and lineage metadata through a run. |
| `Backend` | Opens the local or OpenSandbox execution environment attached to a session. |
| `Memory` | Persists recalled and committed agent knowledge through local or optional OpenViking stores. |
| `FlowToolCall` | Exposes JSON schemas to the model and Python callables to the runtime. |
| `Workflow` | Composes agents as modules and can compile a static resource manifest before runtime. |
| `Selector` | Chooses the next self-describing workflow while control flow stays in ordinary Python. |
| `AgentParam` | Stores the agent system session plus LLM routing options. |
| `Provider` | Routes OpenAI-compatible, Anthropic, or optional LiteLLM chat clients and stores request policy. |
| `CompiledWorkflow` | Wraps a workflow with an inspectable resource snapshot, offline preflight, and memory-store lifecycle. |
```{figure} _static/pytorch-lens.png
:alt: OpenRath in the PyTorch lens
OpenRath borrows PyTorch's compositional vocabulary for agent runtime state:
Session as the flowing value, Backend as placement, Memory as persistent state,
Tool as callable operation, and Workflow as composition.
```
```{figure} _static/paradigm-map.png
:alt: OpenRath paradigm map
The runtime separates agent composition, session state, backend placement, and
memory into explicit surfaces.
```
## v1-compatible Example Ladder
| Example | Demonstrates |
| --- | --- |
| [01 Hello Agent](tutorial/examples/01_hello_agent.md) | The smallest `flow.Agent` program. |
| [02 Session Lineage](tutorial/examples/02_session_lineage.md) | Fork, detach, session graph, and JSONL export. |
| [09 Memory](tutorial/examples/09_memory.md) | Key-free local memory remember / recall / commit. |
| [10 Provider Variation](tutorial/examples/10_provider_variation.md) | Swapping OpenAI-compatible and Anthropic providers. |
| [11 Dynamic Selector](tutorial/examples/11_dynamic_selector.md) | Routing among workflows with `Selector` and `EmptyWorkflow`. |
| [12 Workflow Compile](tutorial/examples/12_compile.md) | Inspecting and validating a static resource manifest without an API call. |
## PyTorch Mental Model
| PyTorch mental model | OpenRath counterpart |
| --- | --- |
| Tensor carries data | `Session` carries agent state |
| Module composes computation | `Workflow` / `Agent` composes behavior |
| device controls placement | `Backend` controls execution placement |
| Parameter persists state | `Memory` persists agent knowledge |
| callable module exposes a reusable interface | `FlowToolCall` exposes tools |
| ordinary control flow selects a module | `Selector` chooses a `Workflow` for Python `if` / `while` |
```{toctree}
---
maxdepth: 3
caption: OpenRath
hidden:
---
OpenRath v2