OpenRath

<p align="center"> <img src="assets/readme/logos/openrath-logo-white.png" alt="OpenRath logo" width="860" /> </p> <p align="center"> <a href="https://pypi.org/project/openrath/"><img src="https://img.shields.io/pypi/v/openrath.svg" alt="PyPI"></a> <a href="https://pypi.org/project/openrath/"><img src="https://img.shields.io/pypi/pyversions/openrath.svg" alt="Python"></a> <a href="https://github.com/Rath-Team/OpenRath/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-BSD--3--Clause-blue.svg" alt="License"></a> <a href="https://docs.openrath.com"><img src="https://img.shields.io/badge/docs-openrath.com-blue" alt="Docs"></a> <a href="https://arxiv.org/abs/2606.19409"><img src="https://img.shields.io/badge/arXiv-2606.19409-b31b1b.svg?logo=arxiv&amp;logoColor=white" alt="arXiv"></a> </p> <div align="center">

English | 简体中文

</div>

---

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

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

• Session carries conversation state and inter-agent collaboration lineage.
• Sandbox decides where tools actually run.
• Memory persists agent memory state across runs.
• Tool is the operator-like callable surface exposed to the model.
• Agent is a reusable, composable session transformation layer.
• Workflow composes multiple agents and workflows into larger systems.
• Selector routes between self-describing workflows at runtime, so if / while control flow stays plain Python.

---

OpenRath in the PyTorch Lens

<p align="center"> <img src="assets/readme/diagrams/pytorch-lens.png" alt="OpenRath in the PyTorch Lens" width="860" /> </p>

| 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. That difference matters when one application needs multiple agents, multiple branches, durable memory, sandboxed execution, and traceable lineage at the same time.

OpenRath is designed for this: many agents collaborating across many branchable sessions, while still tracing every role, workspace, memory write, and final output.

OpenRath 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.

<p align="center"> <img src="assets/readme/diagrams/v2-durable-runtime.png" alt="OpenRath v2.0.0 durable runtime overview" width="860" /> </p>

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.

| Production concern | What OpenRath provides | | --- | --- | | 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. |

Embedded mode remains useful inside a trusted process. 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. Tokens need explicit action grants, object access is tenant/project scoped, and synchronous steps cannot declare a preemptive timeout; use an async step or isolated executor when a deadline must be enforced.

OpenRath v2.0.0 is designed for production deployment while keeping interface maturity explicit: the Agent Server HTTP surface remains Beta, and v1 JSONL imports are historical records rather than resumable active Runs. Deployment, migration, security, and operations guidance lives in deploy/, including operations-v2.md, migration-v2.md, and the generated openapi-v2.json.

<p align="center"> <img src="assets/readme/diagrams/paradigm-map.png" alt="Multi-Agent Multi-Session Map" width="860" /> </p>

| 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 |

---

Why the Multi-Agent-Multi-Session Paradigm

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.

<p align="center"> <img src="assets/readme/diagrams/multi-agent-multi-session.png" alt="Why Multi-Agent Multi-Session" width="860" /> </p>

OpenRath's design addresses the problems that appear when agent systems move from one assistant to large clusters:

• 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.

The result is a runtime where state, execution, memory, and orchestration stay decoupled enough to scale, yet remain connected through one flowing value: Session.

---

A Minimal but Complete OpenRath 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 State

Session is OpenRath's central runtime value. It holds an ordered chunk table containing system, user, assistant, and tool-result rows. It also records sandbox placement, lineage, token usage, and pending lazy work.

This is why OpenRath can model more than a single chat transcript. A session can be forked into a new branch, detached from its parent chain, merged back with another compatible branch, serialized to JSONL, or handed to a different workflow. Agent-side instructions are represented as their own session chunks and prepended by the loop, rather than repeatedly pasted into an opaque prompt.

Common entry points:

• 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 wit