跳到主要内容
Rath Lab
Harness Arch开源项目

OpenRath

OpenRath 是一个类似 PyTorch 的多智能体 & 多会话框架。

当前版本
v2.0.0
许可证
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 年

arXiv:2606.19409
01

核心抽象

它把 Agent 运行时状态拆成明确的、可灵活组合的 Python 对象:

  • Session承载对话状态与 Agent 间协作谱系。
  • Sandbox决定工具到底在哪里运行。
  • Memory持久化跨运行保留的 Agent 记忆状态。
  • Tool暴露给模型的"算子调用"。
  • Agent可复用、可组合的 Session 变换层。
  • Workflow把多个 Agent/Workflow 组合成更大的系统。
  • Selector在运行时于自描述的 Workflow 之间路由,使 if / while 控制流仍是普通 Python。
02

OpenRath 的 PyTorch 视角

上下两排对照图:上排是 PyTorch 的 Tensor、Function、nn.Module 与 Device、Parameter;下排是 OpenRath 的 Session、Agent、Workflow 与 Sandbox、Memory。
  • TensorSession流动的运行时值:有序 chunks、placement、lineage 和 usage。
  • DeviceSandbox / Backend工具运行的执行环境:本地进程、OpenSandbox 或其他后端。
  • ParameterMemory绑定到 Agent 或 store 的持久状态,可在跨运行时 recall 和 commit。
  • FunctionTool带模型可见 schema 和运行时行为的 callable operation。
  • nn.LinearAgent使用 prompt、provider、tools 和 memory 将一个 Session 映射到另一个 Session 的可复用层。
  • nn.ModuleWorkflow用于 agent、tools、session 变换和嵌套 workflows 的可组合容器。
  • control flowSelector一个 LLM 驱动的路由器,在运行时选择下一个 workflow,实现 Agent 间的动态 if / while。

大多数 Agent 框架从 agent loop 开始。OpenRath 从 Session 开始。

03

v2.0.0:面向生产环境

v2.0.0

OpenRath v2.0.0 最重要的变化,是 OpenRath 从一个可组合的 Python 框架,进入可部署、可恢复、可运维的生产环境。

原有以 Session 为核心的 Python API 保持不变;这个版本在其外层增加了一套生产级执行与运维体系。

  • 持久化执行

    显式的 @step / @router 边界会编译成不可变执行计划;Run、Event 与 Checkpoint 能跨进程和 Worker 重启保留。

  • Worker 故障恢复

    Lease、Fencing、Retry、Cancellation、Deadline 与可恢复队列,防止过期 Worker 静默提交新状态。

  • 受控副作用

    Effect Ledger 记录执行结果与幂等键;无法确认的非幂等副作用会停在 NEEDS_REVIEW,而不是被盲目重放。

  • 人工决策

    持久化 Interrupt 可以暂停 Run 等待审批或输入,并在不重建隐藏循环状态的情况下恢复。

  • 安全与租户隔离

    Agent Server Token 使用显式 Action Grant;Tenant/Project Scope、Policy、Secret Reference、Trust Label 与 Audit 保持为独立边界。

  • 生产运维

    PostgreSQL 是持久化事实来源,Redis 可加速信号传递,S3 兼容存储保存 Artifact,并提供健康检查、迁移、遥测、容器与 Kubernetes 参考。

v2 执行链路图:@step 与 @router 编译成不可变的 ExecutionPlan,经 Agent Server 与 Worker lease 进入 Run → Event → Checkpoint,并连到 Effect Ledger 与 Interrupt。
这张图概括了 OpenRath 的生产执行路径:Python 定义先编译为不可变执行计划,持久化 Run 由 Checkpoint、Lease、Effect 与 Interrupt 共同保障,PostgreSQL、Redis 和 S3 兼容存储则构成生产环境的数据与信号层。
  • Embedded

    Embedded mode 仍适合可信进程内部使用。

  • Agent Server

    Agent Server mode 是严格的生产 Profile。

runtime = LocalRuntime(
    store,
    effect_ledger=ledger,
    production_mode=True,
)
server = AgentServer(store, runtime, auth=auth, audit_sink=audit)
安装生产 Profile,并将数据库 Schema 迁移作为独立操作执行
pip install "openrath[server,postgres]"
openrath-migrate
openrath-migrate --check
  • 运行时身份不需要 DDL 权限。
  • 同步 Step 不能声明抢占式超时,需要强制 Deadline 时应使用 Async Step 或隔离执行器。
  • Agent Server HTTP 接口仍为 Beta;v1 JSONL 导入属于历史记录,不能恢复 Active Run。
部署、迁移、安全和运维指南operations-v2.mdmigration-v2.mdopenapi-v2.json
04

为什么是多 Agent 多 Session 范式

一张四象限图,横轴是单会话到多会话,纵轴是单 Agent 到多 Agent。OpenRath 位于多 Agent 且多会话的象限。
  • 单 Agent,单 Session一个模型处理一条对话示例:ChatGPT 式聊天
  • 多 Agent,单 Session多个角色读写同一份共享状态示例:子代理式多 Agent 协作
  • 单 Agent,多 Session一个 Agent 管理多个 Session 分支示例:OpenClaw 式 session 扇出
  • 多 Agent,多 Session多个 Agent 共享多个 Session,通过 Session 协作或演化示例:OpenRath

一个 Agent 是 Session 上的变换层,因此真正需要被 fork、merge、复用和追踪的是 Session 数据流,而不是每个 Agent 各自维护的一段 message history。

会话以图的形式在多个 Agent 之间流转:Planner、Researcher、Coder、Reviewer 各自变换同一个 Session,中间经历 fork、detach、merge、loop。
  • Session 作为数据流核心

    上下文以结构化 chunks 存储,而不是反复复制 message 字符串。Workflow 可以直接复用、fork、压缩和传递上下文,极大提高上下文复用率并减少 token 消耗。

  • 面向大规模 Agent 集群的 Session Graph

    大型运行需要解释哪个 role、分支、tool call 和 workspace 产生了某个答案。Session lineage 为运行时提供图状的 provenance 层,而不是一堆事后日志。

  • Session 加上 Agent Memory

    短期 Session 状态和长期记忆协同工作:Agent 可以在运行前 recall 事实,在运行后 commit 新知识,使 Agent 集群在使用过程中持续改进。

  • 模块化 Workflow

    管理成百上千个 Agent 变成一个组合问题,而不是 prompt 意大利面。Agent 是小层;Workflow 是可嵌套、可复用、可检查的模块,使大规模 Agent 管理变得可行。

  • Sandbox 作为后端

    执行不硬编码到一个 shell。本地、OpenSandbox 或未来的第三方后端都可以在同一个 session placement 模型后面,使第三方执行后端可以灵活接入。

  • Memory 作为后端

    Recall 不硬编码到一个数据库。本地 memory、OpenViking 或未来的第三方 memory 系统可以共享同一个 memory plane,使第三方 memory 后端可以灵活接入。

05

一个极简但完整的 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)

这个小程序在很短篇幅里展示了完整的形态:Session 承载数据,Sandbox 放置执行,Tool 注册到 Agent,Memory 跨运行持久化,Workflow 组合路径,Compressor 压缩最终上下文。

06

运行时组件

  • Session

    流动的状态

    Session 是 OpenRath 的中心运行时值。它持有一个有序 chunk 表,包含 system、user、assistant 和 tool-result 行。

    Session.from_user_message(...)
    创建用户侧 Session。
    Session.from_agent_prompt(...)
    创建 Agent/system prompt Session。
    session.to("local", spec="./")
    绑定 sandbox 后端和工作区。
    session.fork()
    创建可追踪分支。
    session.detach()
    创建不带父谱系的新 Session。
    session.merge(...)
    合并兼容分支并记录 merge 谱系。
  • Sandbox

    工具落地之处

    Sandbox 是 Session 的执行 placement。工具不是在抽象 prompt 中运行;它们是在当前绑定到 Session 的 sandbox 中运行。

    local
    始终可用,在宿主机工作区中运行文件、命令和代码工具。
    opensandbox
    可选,将同一 tool 层连接到容器化的 OpenSandbox runtime。
    session = Session.from_user_message("List files").to("local", spec="./")
  • Memory

    跨运行留存的东西

    Memory 是与 sandbox 执行平行的持久平面。基础安装包含一个零依赖的本地 memory 后端。OpenViking 作为可选后端,为需要更丰富外部 memory 服务的用户提供。

    memory=
    在构造时绑定 store。
    remember_memory(...)
    写入明确事实。
    recall_memory(...)
    检索相关条目。
    commit_memory(...)
    在运行后保存 transcript。
    commit_on_forward=True
    可以自动 commit。
    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

    模型的可调用函数

    FlowToolCall 是模型可见的工具抽象。自定义 Python 工具可以实现相同的接口,stdio MCP 工具也可以被适配为循环中的普通 FlowToolCall 实例。

    FlowToolCall
    模型可见的 flow 层函数。
    BackendTool*
    sandbox 后端消费的更底层负载。
  • Agent

    可复用的一层

    flow.Agent 是大多数用户开始使用的小型可复用层。它更接近 nn.Linear 而不是完整应用:它有 prompt、provider、可选 tools、可选 memory,以及一条 forward(session) -> session 路径。

  • Workflow

    无混乱地组合

    flow.Workflow 是组合表面。因为输入和输出都是 Session,workflows 可以嵌套,而不需要在每一层发明新的 state 格式。

    子类实现
    def forward(self, session: Session) -> Session:
        ...
    flow.Selector 返回下一个要运行的 workflow,或在任务完成时返回 flow.EmptyWorkflow
    selector = flow.Selector(provider)
    while not isinstance(
        nxt := selector.forward(session, triage, tech, wrapup), flow.EmptyWorkflow
    ):
        session = nxt(session)
07

快速安装

核心包
pip install openrath
可选的 sandbox 和 memory 集成
pip install "openrath[opensandbox]"
pip install "openrath[openviking]"
源码开发
git clone https://github.com/Rath-Team/OpenRath.git
cd OpenRath
uv sync --group dev --group docs
大多数 LLM 示例使用 OpenAI 兼容的环境变量
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://your-gateway/v1
export OPENAI_DEFAULT_MODEL=your-model-name

你也可以在 ~/.openrath/config.json 中配置 providers。环境变量优先级更高。

08

通过运行来学习

example/ 目录是一个编号的学习阶梯。每个脚本引入一个概念。

运行第一层
python example/01_hello_agent.py
  1. 0101_hello_agent.py需要 key最小的 OpenRath 程序:构建 flow.Agent,在 Session 上调用,流式输出响应。
  2. 0202_session_lineage.py无需 key用 fork 分支 session,用 detach 切断谱系,检查 session graph,导出 JSONL。
  3. 0303_sandbox_backend.py需要 key将同一个 session 放到 local 或 opensandbox,观察工具在哪里执行。
  4. 0404_tools_builtin.py需要 key使用每个循环可以暴露的内置文件系统和 shell 工具。
  5. 0505_custom_tool.py需要 key实现带 JSON schema 和 Python 运行时行为的自定义 FlowToolCall。
  6. 0606_mcp_tool.py无需 key包装一个微型 stdio MCP server,无需编写新 tool 类即可借用其工具。
  7. 0707_streaming.py需要 key接收流式 delta,并在运行后检查累积 token 使用情况。
  8. 0808_compress.py需要 key使用 flow.Compressor 将长 session 缩减为更小的上下文 session。
  9. 0909_memory.py无需 key使用本地 memory 后端进行 remember、recall,并可选地 commit 一个真实回合。
  10. 1010_provider_variation.py需要 key通过更改 Provider 切换模型厂商,同时保持 Session 和 Workflow 代码稳定。
  11. 1111_dynamic_selector.py需要 key使用 flow.Selector 在自描述的 workflows 之间路由:if 分支和一个在 flow.EmptyWorkflow 时结束的 while 循环。
  12. 1212_compile.py无需 key静态 compile() 一个 workflow:查看其资源清单、离线 validate()、并使用生命周期上下文管理器。

包含固定输入、持久化状态、质量检查和已提交交付物的完整生产化场景

Rath-Team/OpenRath-Example

OpenRath 使用 BSD 风格许可证。 BSD-3-Clause