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 年
核心抽象
它把 Agent 运行时状态拆成明确的、可灵活组合的 Python 对象:
- Session承载对话状态与 Agent 间协作谱系。
- Sandbox决定工具到底在哪里运行。
- Memory持久化跨运行保留的 Agent 记忆状态。
- Tool暴露给模型的"算子调用"。
- Agent可复用、可组合的 Session 变换层。
- Workflow把多个 Agent/Workflow 组合成更大的系统。
- Selector在运行时于自描述的 Workflow 之间路由,使
if/while控制流仍是普通 Python。
OpenRath 的 PyTorch 视角
- 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。
| PyTorch 理念 | OpenRath 理念 | 含义 |
|---|---|---|
| Tensor | Session | 流动的运行时值:有序 chunks、placement、lineage 和 usage。 |
| Device | Sandbox / Backend | 工具运行的执行环境:本地进程、OpenSandbox 或其他后端。 |
| Parameter | Memory | 绑定到 Agent 或 store 的持久状态,可在跨运行时 recall 和 commit。 |
| Function | Tool | 带模型可见 schema 和运行时行为的 callable operation。 |
| nn.Linear | Agent | 使用 prompt、provider、tools 和 memory 将一个 Session 映射到另一个 Session 的可复用层。 |
| nn.Module | Workflow | 用于 agent、tools、session 变换和嵌套 workflows 的可组合容器。 |
| control flow | Selector | 一个 LLM 驱动的路由器,在运行时选择下一个 workflow,实现 Agent 间的动态 if / while。 |
大多数 Agent 框架从 agent loop 开始。OpenRath 从 Session 开始。
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 参考。
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)pip install "openrath[server,postgres]"
openrath-migrate
openrath-migrate --check- 运行时身份不需要 DDL 权限。
- 同步 Step 不能声明抢占式超时,需要强制 Deadline 时应使用 Async Step 或隔离执行器。
- Agent Server HTTP 接口仍为 Beta;v1 JSONL 导入属于历史记录,不能恢复 Active Run。
为什么是多 Agent 多 Session 范式
- 单 Agent,单 Session一个模型处理一条对话示例:ChatGPT 式聊天
- 多 Agent,单 Session多个角色读写同一份共享状态示例:子代理式多 Agent 协作
- 单 Agent,多 Session一个 Agent 管理多个 Session 分支示例:OpenClaw 式 session 扇出
- 多 Agent,多 Session多个 Agent 共享多个 Session,通过 Session 协作或演化示例:OpenRath
| 范式 | 典型形态 | 示例 |
|---|---|---|
| 单 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。
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 后端可以灵活接入。
一个极简但完整的 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 压缩最终上下文。
运行时组件
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.EmptyWorkflowselector = flow.Selector(provider) while not isinstance( nxt := selector.forward(session, triage, tech, wrapup), flow.EmptyWorkflow ): session = nxt(session)
快速安装
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-name你也可以在 ~/.openrath/config.json 中配置 providers。环境变量优先级更高。
通过运行来学习
example/ 目录是一个编号的学习阶梯。每个脚本引入一个概念。
python example/01_hello_agent.py- 0101_hello_agent.py需要 key最小的 OpenRath 程序:构建
flow.Agent,在Session上调用,流式输出响应。 - 0202_session_lineage.py无需 key用
fork分支 session,用detach切断谱系,检查 session graph,导出 JSONL。 - 0303_sandbox_backend.py需要 key将同一个 session 放到
local或opensandbox,观察工具在哪里执行。 - 0404_tools_builtin.py需要 key使用每个循环可以暴露的内置文件系统和 shell 工具。
- 0505_custom_tool.py需要 key实现带 JSON schema 和 Python 运行时行为的自定义
FlowToolCall。 - 0606_mcp_tool.py无需 key包装一个微型 stdio MCP server,无需编写新 tool 类即可借用其工具。
- 0707_streaming.py需要 key接收流式 delta,并在运行后检查累积 token 使用情况。
- 0808_compress.py需要 key使用
flow.Compressor将长 session 缩减为更小的上下文 session。 - 0909_memory.py无需 key使用本地 memory 后端进行 remember、recall,并可选地 commit 一个真实回合。
- 1010_provider_variation.py需要 key通过更改
Provider切换模型厂商,同时保持 Session 和 Workflow 代码稳定。 - 1111_dynamic_selector.py需要 key使用
flow.Selector在自描述的 workflows 之间路由:if分支和一个在flow.EmptyWorkflow时结束的while循环。 - 1212_compile.py无需 key静态
compile()一个 workflow:查看其资源清单、离线validate()、并使用生命周期上下文管理器。
包含固定输入、持久化状态、质量检查和已提交交付物的完整生产化场景
Rath-Team/OpenRath-Example