OpenRath vs PyTorch 逐概念对照表：一文看懂 Session、Sandbox 与 Memory 三大核心机制-育师

【免费下载链接】OpenRath

An open-source, PyTorch-like runtime for dynamic multi-agent and multi-session workflows.

项目地址：https://gitcode.com/gh_mirrors/op/OpenRath

OpenRath 是一个 PyTorch 风格的开源多智能体 & 多会话Agent 框架。它把 Agent 运行时拆成Session、Sandbox、Memory、Tool、Agent、Workflow等明确、可组合的 Python 对象。本文用 PyTorch 的视角逐概念对照，帮你快速看懂 Session、Sandbox 与 Memory 三大核心机制。

💡 一句话理解：大多数 Agent 框架从"Agent 循环"开始，OpenRath 从Session开始。这正是它能同时处理多智能体、多分支、持久记忆、沙箱执行和可追踪谱系的原因。

为什么需要"Session 优先"的多智能体框架

传统框架把每个 Agent 的状态藏在各自的消息历史里；OpenRath 则认为，真正需要被分支、合并、复用、追踪的是Session 数据流本身。Agent 只是作用在 Session 上的一层"变换"。

这带来四个直接好处：

🧩上下文可复用：上下文以结构化chunks存储，而非反复复制消息字符串，Workflow 可 fork / 压缩 / 传递，减少 token 消耗。
🌳谱系可追溯：多 Agent 协作时，Session 谱系（lineage）像一张图，能解释"哪个角色、哪个分支、哪次工具调用产出了答案"。
🔁状态可组合：因为输入输出都是Session，Workflow 可无限嵌套，不必在每层发明新的状态格式。
🧠记忆可持久：短期 Session 状态 + 长期 Memory 协同，Agent 集群可以越用越强。

核心概念速查：PyTorch ↔ OpenRath 完整对照表

这是本文最重要的部分。把熟悉的 PyTorch 概念"翻译"成 OpenRath，学习成本会大幅下降：

PyTorch 理念	OpenRath 对应	它意味着什么
`Tensor`（张量）	`Session`	流动的运行时值：有序 chunks、placement、谱系、用量
`Device`（设备）	`Sandbox`/`Backend`	工具真正运行的执行环境：本地进程、OpenSandbox 等
`Parameter`（参数）	`Memory`	绑定到 Agent 的持久状态，可跨运行 recall / commit
`Function`（函数）	`Tool`	带模型可见 schema 与运行时行为的可调用操作
`nn.Linear`（线性层）	`Agent`	用 prompt、provider、tools、memory 把一个 Session 映射到另一个
`nn.Module`（模块）	`Workflow`	组合 Agent、Tool、Session 变换与嵌套 Workflow 的容器
控制流`if`/`while`	`Selector`	LLM 驱动的路由器，运行时决定下一个 Workflow

🎯核心记忆点：Session = 数据、Sandbox = 算力、Memory = 参数。三者各司其职，是理解 OpenRath 的钥匙。

Session 核心机制：流动的运行时状态

Session是 OpenRath 的中心运行时值，对应 PyTorch 的Tensor。它内部是一张有序的 chunk 表，包含system、user、assistant、tool-result等行，并记录 sandbox 绑定、谱系（lineage）与 token 用量。

它最像 PyTorch 的"可分支张量"，核心 API 一目了然：

from rath.session import Session root = Session.from_user_message("Plan a small project.") plan = root.fork() # 类比 torch clone()：保留父链 fresh = root.detach() # 类比 torch detach()：切断谱系，成为新根 merged = plan.merge(fresh) # 合并两个兼容分支并记录谱系

🌱fork()：创建可追踪的新分支，保留父节点链接。
✂️detach()：创建不带父谱系的新 Session（新根）。
🔗merge()：合并兼容分支，并记录合并谱系。
📦to("local", spec="./")：为 Session 绑定执行环境（见下文 Sandbox）。

这些操作会形成一张谱系图，可以遍历、导出为 JSONL，为大型 Agent 集群提供图状的溯源层。相关实现见 session.py 与 primitives.py，无需 API Key 即可体验的完整示例在 02_session_lineage.py。

Sandbox 核心机制：工具到底在哪里运行

Sandbox是 Session 的执行落地位置，对应 PyTorch 的Device（如.to("cuda")）。关键点是：工具不在抽象的 prompt 里运行，而是运行在当前绑定到 Session 的 sandbox 中。

它同样像tensor.to(device)，用一个动词.to()决定算力落在哪里：

# 绑定本地后端 + 工作目录（.to() 等价于 tensor.to(device)） session = Session.from_user_message("List files").to("local", spec="./")

两种典型后端：

🏠local（始终可用）：直接在宿主机工作区运行文件、命令、代码工具。
🐳opensandbox（可选）：把同一套工具层接入容器化的 OpenSandbox 运行时，实现隔离执行。

由于返回的 Session 会保留活跃的 sandbox 所有权，后续工具调用会始终在同一执行上下文进行，不会悄悄漂移到别的目录或机器。这与 PyTorch 中张量"粘"在某个 device 上的行为如出一辙。后端抽象基类定义见 backend/abc.py，对照示例 03_sandbox_backend.py。

Memory 核心机制：跨运行留存的状态

Memory是与 sandbox 执行平行的持久平面，对应 PyTorch 的Parameter——它不是工具结果，也不是 prompt 文本，而是可绑定到 Agent、运行前 recall、运行后 commit的状态。

基础安装自带一个零依赖的本地 memory 后端（数据存于.openrath/memory/），无需 LLM 即可用 BM25 词法检索，配置了 embedding provider 后还能用向量检索。API 设计得非常直观：

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") # 检索 # 运行后还可 commit_memory(session) 保存整段对话

四个动词覆盖完整生命周期：

方法	作用
`memory=`	构造时绑定一个 memory store
`remember_memory(...)`	写入明确事实
`recall_memory(...)`	检索相关条目
`commit_memory(...)`	运行后保存整段 transcript

这让短期 Session 与长期记忆协同工作：Agent 在运行前回忆事实、运行后沉淀新知识，从而让 Agent 集群在使用过程中持续改进。抽象基类见 memory/abc.py，Agent 侧 API 见 flow/agent.py，免 Key 可运行示例 09_memory.py。

Agent 与 Workflow：把三层组装成系统

理解了 Session / Sandbox / Memory 三个"基础件"后，上层组装就很自然：

🧠Agent≈nn.Linear：一个小型可复用层，拥有 prompt、provider、可选 tools、可选 memory，路径是forward(session) -> session。它不拥有整个世界，只是 Session 上的一层变换。
📦Workflow≈nn.Module：组合表面，可串联 Agent、fork Session、压缩上下文、分发到子 Workflow。因为输入输出都是Session，所以可无限嵌套。
🔀Selector≈ 动态控制流：一个 LLM 驱动的路由器，在多个自描述 Workflow 之间选择下一个要运行的，任务完成时返回EmptyWorkflow，让if/while保持普通 Python。

一个极简但完整的工作流，能在很短篇幅里同时展示全部形态（Session承载数据、Sandbox放置执行、Tool注册到 Agent、Memory跨运行持久化、Compressor压缩上下文），代码见 README 示例与 flow/workflow.py。

三大核心机制小结

机制	PyTorch 类比	一句话职责	关键入口
Session	`Tensor`	承载对话数据 + 谱系的流动状态	`fork`/`detach`/`merge`
Sandbox	`Device`	决定工具在哪里执行	`session.to(backend, spec=...)`
Memory	`Parameter`	跨运行留存的持久状态	`remember`/`recall`/`commit`

记住这三句，你就掌握了 OpenRath 的骨架：

🧩 Session 是数据（流动的运行时值）。
🏠 Sandbox 是算力（执行的落地位置）。
🧠 Memory 是参数（跨运行留存的状态）。

快速上手：三步跑通你的第一个 OpenRath

# 1. 安装（可选集成沙箱 / 记忆后端） pip install openrath # pip install "openrath[opensandbox]" # pip install "openrath[openviking]" # 2. 配置 LLM（OpenAI 兼容环境变量） export OPENAI_API_KEY=sk-... export OPENAI_DEFAULT_MODEL=your-model-name # 3. 从示例阶梯开始，逐概念学习 python example/01_hello_agent.py # 最小 Agent 程序 python example/02_session_lineage.py # Session 分支/谱系（无需 Key） python example/09_memory.py # Memory 记住/检索（无需 Key）

example/目录是一个编号学习阶梯：每个脚本只引入一个概念（Session、Sandbox、Tool、Memory、Selector 等），样板代码集中在_shared/，帮你循序渐进地理解各对象如何拼装。详见 example/README.md。