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
OpenRath: Session-Centered Runtime State for Agent Systems
Fukang Wen, Zhijie Wang, Ruilin Xu · cs.SE (primary) · cs.PL · 2026
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/whilecontrol flow stays plain Python.
OpenRath in the PyTorch Lens
- 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/whileover agents.
| PyTorch idea | OpenRath idea | What it means |
|---|---|---|
| Tensor | Session | The flowing runtime value: ordered chunks, placement, lineage, and usage. |
| Device | Sandbox / Backend | The execution environment where tools run: local process, OpenSandbox, or another backend. |
| Parameter | Memory | Persistent state bound to an agent or store, recalled and committed across runs. |
| Function | Tool | A callable operation with model-visible schema and runtime behavior. |
| nn.Linear | Agent | A reusable layer that maps one session to another using a prompt, provider, tools, and memory. |
| nn.Module | Workflow | A composable container for agents, tools, session transforms, and nested workflows. |
| control flow | Selector | An 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.
v2.0.0: Built for Production
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/@routerboundaries 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_REVIEWinstead 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.
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)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.
Why the Multi-Agent-Multi-Session Paradigm
- 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
| Paradigm | Typical shape | Example |
|---|---|---|
| Single agent, single session | One model over one conversation | ChatGPT-style chat |
| Multi-agent, single session | Several roles read and write one shared state | Sub-agent-style multi-agent collaboration |
| Single agent, multi-session | One agent manages many session branches | OpenClaw-style session fanout |
| Multi-agent, multi-session | Many agents share many sessions and collaborate or evolve through Session | 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.
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.
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.
The Runtime Pieces
Session
The Flowing StateSessionis 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 LandSandbox 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 RunsMemory 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 ModelFlowToolCallis the model-visible tool abstraction. Custom Python tools can implement the same interface, and stdio MCP tools can be adapted into the loop as normalFlowToolCallinstances.- FlowToolCall
- The flow-layer function visible to the model.
- BackendTool*
- The lower-level payload consumed by a sandbox backend.
Agent
One Reusable Layerflow.Agentis the small reusable layer most users start with. It is closer tonn.Linearthan to a full application: it has a prompt, a provider, optional tools, optional memory, and aforward(session) -> sessionpath.Workflow
Compose Without Chaosflow.Workflowis the composition surface. Because the input and output are bothSession, workflows can be nested without inventing a new state format at each layer.Subclasses implement def forward(self, session: Session) -> Session: ...flow.Selectorreturns the next workflow to run, orflow.EmptyWorkflowwhen the task is doneselector = flow.Selector(provider) while not isinstance( nxt := selector.forward(session, triage, tech, wrapup), flow.EmptyWorkflow ): session = nxt(session)
Quick Install
pip install openrathpip install "openrath[opensandbox]"
pip install "openrath[openviking]"git clone https://github.com/Rath-Team/OpenRath.git
cd OpenRath
uv sync --group dev --group docsexport OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://your-gateway/v1
export OPENAI_DEFAULT_MODEL=your-model-nameYou can also configure providers in ~/.openrath/config.json. Environment variables take precedence.
Learn By Running
The example/ directory is a numbered learning ladder. Each script introduces one concept.
python example/01_hello_agent.py- 0101_hello_agent.pyNeeds a keyThe smallest OpenRath program: build
flow.Agent, call it onSession, stream a response. - 0202_session_lineage.pyNo keyBranch a session with
fork, cut lineage withdetach, inspect the session graph, export JSONL. - 0303_sandbox_backend.pyNeeds a keyPlace the same session on
localoropensandboxand observe where tools execute. - 0404_tools_builtin.pyNeeds a keyUse built-in filesystem and shell tools that every loop can expose.
- 0505_custom_tool.pyNeeds a keyImplement a custom
FlowToolCallwith a JSON schema and Python runtime behavior. - 0606_mcp_tool.pyNo keyWrap a tiny stdio MCP server and borrow its tools without writing new tool classes.
- 0707_streaming.pyNeeds a keyReceive streaming deltas and inspect cumulative token usage after the run.
- 0808_compress.pyNeeds a keyUse
flow.Compressorto reduce a long session into a smaller context session. - 0909_memory.pyNo keyUse the local memory backend to remember, recall, and optionally commit a live turn.
- 1010_provider_variation.pyNeeds a keySwap model vendors by changing
Provider, while keeping Session and Workflow code stable. - 1111_dynamic_selector.pyNeeds a keyRoute between self-describing workflows with
flow.Selector:ifbranching and awhileloop that ends onflow.EmptyWorkflow. - 1212_compile.pyNo keyStatically
compile()a workflow: inspect its resource manifest, run offlinevalidate(), and use the lifecycle context manager.
Complete, production-shaped scenarios with fixed inputs, durable state, QA, and committed deliverables
Rath-Team/OpenRath-ExampleOpenRath uses a BSD-style license. BSD-3-Clause