Skip to content
Rath Lab
Harness ArchOpen source

OpenRath

OpenRath is a PyTorch-like multi-agent & multi-session framework.

Version
v2.0.0
License
BSD-3-Clause
Python
3.10 – 3.13
PyPI
openrath
Paper

OpenRath: Session-Centered Runtime State for Agent Systems

Fukang Wen, Zhijie Wang, Ruilin Xu · cs.SE (primary) · cs.PL · 2026

arXiv:2606.19409
01

Core abstractions

It turns agent runtime state into explicit, composable Python objects:

  • SessionCarries conversation state and inter-agent collaboration lineage.
  • SandboxDecides where tools actually run.
  • MemoryPersists agent memory state across runs.
  • ToolThe operator-like callable surface exposed to the model.
  • AgentA reusable, composable session transformation layer.
  • WorkflowComposes multiple agents and workflows into larger systems.
  • SelectorRoutes between self-describing workflows at runtime, so if / while control flow stays plain Python.
02

OpenRath in the PyTorch Lens

Two aligned rows: PyTorch’s Tensor, Function, and nn.Module alongside Device and Parameter; below them OpenRath’s Session, Agent, and Workflow alongside Sandbox and Memory.
  • TensorSessionThe flowing runtime value: ordered chunks, placement, lineage, and usage.
  • DeviceSandbox / BackendThe execution environment where tools run: local process, OpenSandbox, or another backend.
  • ParameterMemoryPersistent state bound to an agent or store, recalled and committed across runs.
  • FunctionToolA callable operation with model-visible schema and runtime behavior.
  • nn.LinearAgentA reusable layer that maps one session to another using a prompt, provider, tools, and memory.
  • nn.ModuleWorkflowA composable container for agents, tools, session transforms, and nested workflows.
  • control flowSelectorAn LLM-backed router that picks the next workflow at runtime, enabling dynamic if / while over agents.

Most agent frameworks begin with an agent loop. OpenRath begins with Session.

03

v2.0.0: Built for Production

v2.0.0

The defining change in OpenRath v2.0.0 is that OpenRath moves beyond a composable Python framework and becomes a durable runtime designed for production deployment.

The existing Session-first Python API remains intact; the release adds a production execution and operations layer around it.

  • Durable execution

    Explicit @step / @router boundaries compile into immutable execution plans. Runs, Events, and Checkpoints survive process and worker restarts.

  • Resilient workers

    Leases, fencing, retries, cancellation, deadlines, and resumable queues prevent stale workers from silently committing new state.

  • Controlled side effects

    An Effect Ledger records outcomes and idempotency keys. Ambiguous non-idempotent effects stop in NEEDS_REVIEW instead of being replayed blindly.

  • Human decisions

    Durable Interrupts pause a Run for approval or input and resume it without rebuilding hidden loop state.

  • Security and tenancy

    Agent Server tokens carry explicit action grants; tenant/project scope, policy checks, secret references, trust labels, and audit remain separate boundaries.

  • Production operations

    PostgreSQL is the durable source of truth, Redis can accelerate signaling, S3-compatible storage holds artifacts, and health, migration, telemetry, container, and Kubernetes references are included.

The v2 execution path: @step and @router compile into an immutable ExecutionPlan, which flows through Agent Server and a worker lease into Run, Event, and Checkpoint, connecting to an Effect Ledger and Interrupt.
The diagram summarizes this production path: Python definitions compile into immutable plans, durable Runs are governed by checkpoints, leases, effects, and interrupts, and PostgreSQL, Redis, and S3-compatible storage provide the operational data plane.
  • Embedded

    Embedded mode remains useful inside a trusted process.

  • Agent Server

    Agent Server mode is the strict production profile.

runtime = LocalRuntime(
    store,
    effect_ledger=ledger,
    production_mode=True,
)
server = AgentServer(store, runtime, auth=auth, audit_sink=audit)
Install the production profile and run schema migration as a separate operation
pip install "openrath[server,postgres]"
openrath-migrate
openrath-migrate --check
  • Runtime identities do not need DDL privileges.
  • Synchronous steps cannot declare a preemptive timeout; use an async step or isolated executor when a deadline must be enforced.
  • The Agent Server HTTP surface remains Beta, and v1 JSONL imports are historical records rather than resumable active Runs.
Deployment, migration, security, and operations guidanceoperations-v2.mdmigration-v2.mdopenapi-v2.json
04

Why the Multi-Agent-Multi-Session Paradigm

A four-quadrant map: single-to-multi session on one axis, single-to-multi agent on the other. OpenRath sits in the multi-agent, multi-session quadrant.
  • Single agent, single sessionOne model over one conversationExample: ChatGPT-style chat
  • Multi-agent, single sessionSeveral roles read and write one shared stateExample: Sub-agent-style multi-agent collaboration
  • Single agent, multi-sessionOne agent manages many session branchesExample: OpenClaw-style session fanout
  • Multi-agent, multi-sessionMany agents share many sessions and collaborate or evolve through SessionExample: OpenRath

An agent is a transformation layer on Session, so what really needs to be forked, merged, reused, and traced is the Session dataflow—not a separate message history maintained by each agent.

Sessions flow as a graph between agents: Planner, Researcher, Coder, and Reviewer each transform the same Session through fork, detach, merge, and loop.
  • Session as the dataflow core

    Context is stored as structured chunks rather than repeatedly copied message strings. Workflows can reuse, fork, compress, and pass context directly, which greatly improves context reuse and reduces token consumption.

  • Session Graph for massive agent clusters

    Large runs need to explain which role, branch, tool call, and workspace produced an answer. Session lineage gives the runtime a graph-shaped provenance layer instead of a pile of post-hoc logs.

  • Session plus Agent Memory

    Short-term session state and long-term memory work together: agents can recall facts before a run and commit new knowledge afterward, so an agent cluster can keep improving as it is used.

  • Modular Workflow

    Managing hundreds or thousands of agents becomes a composition problem instead of prompt spaghetti. Agents are small layers; workflows are nested, reusable, inspectable modules that make large-scale agent management tractable.

  • Sandbox as a backend

    Execution is not hardcoded to one shell. Local, OpenSandbox, or future third-party backends can sit behind the same session placement model, so third-party execution backends plug in flexibly.

  • Memory as a backend

    Recall is not hardcoded to one database. Local memory, OpenViking, or future third-party memory systems can share one memory plane, so third-party memory backends plug in flexibly.

05

A Minimal but Complete Workflow

from collections.abc import Mapping
from typing import Any

from pydantic import BaseModel, Field

from rath import flow
from rath.flow.tool import FlowToolCall
from rath.session import Session


class WordCountInput(BaseModel):
    text: str = Field(description="Text to count.")


# OpenRath Tool
class WordCountTool(FlowToolCall):
    @property
    def name(self) -> str:
        return "word_count"

    @property
    def description(self) -> str:
        return "Count words in a short text."

    @property
    def parameters(self) -> Mapping[str, Any]:
        return WordCountInput.model_json_schema()

    def __call__(self, session: Session, arguments: Mapping[str, Any]) -> dict[str, int]:
        data = WordCountInput.model_validate(dict(arguments))
        return {"words": len(data.text.split())}


# OpenRath Workflow
class ReadmeWorkflow(flow.Workflow):
    def __init__(self) -> None:
        # OpenRath Provider
        provider = flow.Provider(model="gpt-5.5")

        # OpenRath Agent
        self.agent = flow.Agent(
            "Use the `word_count` tool, then answer briefly.",
            provider,
            tools=[WordCountTool()],
            memory="local",
        )

        # OpenRath Compressor
        self.compressor = flow.Compressor(
            "Compress the run into one concise assistant message.",
            provider,
        )

    def forward(self, session: Session) -> Session:
        # OpenRath Memory
        self.agent.remember_memory("The user likes compact technical summaries.")
        session = self.agent(session)
        self.agent.commit_memory(session)
        return self.compressor(session)


workflow = ReadmeWorkflow()

# OpenRath Session
user_session = Session.from_user_message(
    "Count the words in: OpenRath makes agent clusters traceable."
)

# OpenRath Sandbox
user_session = user_session.to("local", spec="./")
out = workflow(user_session)

This small program shows the whole shape in a short span: Session carries the data, Sandbox places execution, Tool is registered on an Agent, Memory persists across runs, Workflow composes the path, and Compressor shrinks the resulting context.

06

The Runtime Pieces

  • Session

    The Flowing State

    Session is OpenRath’s central runtime value. It holds an ordered chunk table containing system, user, assistant, and tool-result rows.

    Session.from_user_message(...)
    Creates a user-side session.
    Session.from_agent_prompt(...)
    Creates an agent/system prompt session.
    session.to("local", spec="./")
    Binds a sandbox backend and workspace.
    session.fork()
    Creates a traceable branch.
    session.detach()
    Creates a new session without parent lineage.
    session.merge(...)
    Combines compatible branches and records merge lineage.
  • Sandbox

    Where Tools Land

    Sandbox is the execution placement for a session. Tools do not run in an abstract prompt; they run against the sandbox currently bound to the session.

    local
    Always available; runs file, command, and code tools against the host workspace.
    opensandbox
    Optional; connects the same tool layer to a containerized OpenSandbox runtime.
    session = Session.from_user_message("List files").to("local", spec="./")
  • Memory

    What Survives Between Runs

    Memory is a persistent plane parallel to sandbox execution. The base install includes a zero-dependency local memory backend. OpenViking is available as an optional backend for users who want a richer external memory service.

    memory=
    Binds a store at construction time.
    remember_memory(...)
    Writes explicit facts.
    recall_memory(...)
    Retrieves relevant entries.
    commit_memory(...)
    Stores a transcript after a run.
    commit_on_forward=True
    Can commit automatically.
    with flow.Agent("You remember useful facts.", model="gpt-5.5", memory="local") as agent:
        agent.remember_memory("The user works mostly in Python.")
        hits = agent.recall_memory("preferred programming language")
  • Tool

    Callable Functions for the Model

    FlowToolCall is the model-visible tool abstraction. Custom Python tools can implement the same interface, and stdio MCP tools can be adapted into the loop as normal FlowToolCall instances.

    FlowToolCall
    The flow-layer function visible to the model.
    BackendTool*
    The lower-level payload consumed by a sandbox backend.
  • Agent

    One Reusable Layer

    flow.Agent is the small reusable layer most users start with. It is closer to nn.Linear than to a full application: it has a prompt, a provider, optional tools, optional memory, and a forward(session) -> session path.

  • Workflow

    Compose Without Chaos

    flow.Workflow is the composition surface. Because the input and output are both Session, workflows can be nested without inventing a new state format at each layer.

    Subclasses implement
    def forward(self, session: Session) -> Session:
        ...
    flow.Selector returns the next workflow to run, or flow.EmptyWorkflow when the task is done
    selector = flow.Selector(provider)
    while not isinstance(
        nxt := selector.forward(session, triage, tech, wrapup), flow.EmptyWorkflow
    ):
        session = nxt(session)
07

Quick Install

Core package
pip install openrath
Optional sandbox and memory integrations
pip install "openrath[opensandbox]"
pip install "openrath[openviking]"
For source development
git clone https://github.com/Rath-Team/OpenRath.git
cd OpenRath
uv sync --group dev --group docs
Most LLM examples use OpenAI-compatible environment variables
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://your-gateway/v1
export OPENAI_DEFAULT_MODEL=your-model-name

You can also configure providers in ~/.openrath/config.json. Environment variables take precedence.

08

Learn By Running

The example/ directory is a numbered learning ladder. Each script introduces one concept.

Run the first rung
python example/01_hello_agent.py
  1. 0101_hello_agent.pyNeeds a keyThe smallest OpenRath program: build flow.Agent, call it on Session, stream a response.
  2. 0202_session_lineage.pyNo keyBranch a session with fork, cut lineage with detach, inspect the session graph, export JSONL.
  3. 0303_sandbox_backend.pyNeeds a keyPlace the same session on local or opensandbox and observe where tools execute.
  4. 0404_tools_builtin.pyNeeds a keyUse built-in filesystem and shell tools that every loop can expose.
  5. 0505_custom_tool.pyNeeds a keyImplement a custom FlowToolCall with a JSON schema and Python runtime behavior.
  6. 0606_mcp_tool.pyNo keyWrap a tiny stdio MCP server and borrow its tools without writing new tool classes.
  7. 0707_streaming.pyNeeds a keyReceive streaming deltas and inspect cumulative token usage after the run.
  8. 0808_compress.pyNeeds a keyUse flow.Compressor to reduce a long session into a smaller context session.
  9. 0909_memory.pyNo keyUse the local memory backend to remember, recall, and optionally commit a live turn.
  10. 1010_provider_variation.pyNeeds a keySwap model vendors by changing Provider, while keeping Session and Workflow code stable.
  11. 1111_dynamic_selector.pyNeeds a keyRoute between self-describing workflows with flow.Selector: if branching and a while loop that ends on flow.EmptyWorkflow.
  12. 1212_compile.pyNo keyStatically compile() a workflow: inspect its resource manifest, run offline validate(), and use the lifecycle context manager.

Complete, production-shaped scenarios with fixed inputs, durable state, QA, and committed deliverables

Rath-Team/OpenRath-Example

OpenRath uses a BSD-style license. BSD-3-Clause