OpenRath
A Session-first Python runtime for traceable multi-agent, multi-session workflows.
- Source repo
- Rath-Team/OpenRath
- Stars
- ★ 957
- Last updated
- 1mo ago
- License
- BSD-3-Clause
- Primary language
- Python
- FA score
- 47/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Python team coordinating specialist roles on a complex request can use Session lineage to trace which branch, role, tool call, and workspace produced an output.
- Not a fit if
- Small teams unwilling to run PostgreSQL, Redis, and S3 infrastructure
- Users needing a stable production HTTP API; Agent Server is Beta
- Source review
- 47/100 · Major gaps
What does this agent do, and when should you use it?
OpenRath is a PyTorch-like Python framework and runtime for multi-agent, multi-session applications built around Session. A Session carries ordered chunks, sandbox placement, lineage, token usage, and pending lazy work, while Agent, Workflow, Tool, Memory, and Selector operate on that shared value. Workflows implement forward(session) -> session, can be nested, and can fork, merge, compress, or route session branches. Version 2.0.0 adds a production execution layer in which @step and @router boundaries compile into immutable plans and durable Runs use checkpoints, leases, effects, and interrupts. PostgreSQL is the documented durable source of truth, with optional Redis signaling and S3-compatible artifact storage; the Agent Server HTTP surface is Beta.
An application creates a Session with Session.from_user_message(...) and can bind its execution placement using session.to("local", spec="./"). A flow.Agent applies its prompt, Provider, optional FlowToolCall tools, and optional Memory to the session; model-visible JSON schemas and Python tool behavior live together, and tools execute against the bound Sandbox. A flow.Workflow can invoke agents, child workflows, flow.Compressor, or flow.Selector, then returns a new Session. Sessions can fork(), detach(), merge(...), and export JSONL; memory can be written, recalled, and committed with remember_memory(...), recall_memory(...), and commit_memory(...). In production mode, plans, Runs, Events, Checkpoints, an Effect Ledger, leases, and durable Interrupts support retries, cancellation, deadlines, and resumable execution.
- A Python team coordinating specialist roles on a complex request can use Session lineage to trace which branch, role, tool call, and workspace produced an output.
- An application developer evaluating several solution paths can fork sessions, merge compatible branches, and use
flow.Compressorto reduce the resulting context. - An automation engineer who needs a model to use filesystem, shell, or code tools in a defined workspace can place the Session on the
localor optionalopensandboxbackend. - A product team that wants an agent to retain useful facts between runs can bind
memory="local", recall relevant entries before a run, and commit the transcript afterward. - An operations team running long-lived workflows can use the production profile with PostgreSQL, leases, checkpoints, effect handling, and human approval interrupts.
How do you install or deploy this agent?
Base install:
pip install openrathOptional integrations:
pip install "openrath[opensandbox]"
pip install "openrath[openviking]"Most model examples require OpenAI-compatible credentials:
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://your-gateway/v1
export OPENAI_DEFAULT_MODEL=your-model-nameA Provider can also be configured in ~/.openrath/config.json; environment variables take precedence. For the production profile, install pip install "openrath[server,postgres]" and run openrath-migrate.
How do you use this agent?
After configuring credentials, start with:
python example/01_hello_agent.pyThe basic flow is to construct a flow.Agent, create Session.from_user_message(...), and invoke agent(session). For composition, subclass flow.Workflow and implement def forward(self, session: Session) -> Session:. The documented production setup is:
runtime = LocalRuntime(store, effect_ledger=ledger, production_mode=True)
server = AgentServer(store, runtime, auth=auth, audit_sink=audit)What are this agent's strengths and limitations?
- Session is a first-class runtime value with structured chunks, placement, lineage, and usage, rather than only an opaque chat history.
- The common
Session -> Sessioninterface lets agents and workflows compose, whileflow.Selectorkeeps runtime routing inside ordinary Python control flow. FlowToolCallcombines the schema exposed to the model with the Python behavior that runs against a Session, and stdio MCP tools can be adapted into that abstraction.- The v2 production model explicitly covers immutable plans, checkpoints, leases, fencing, effect tracking, and durable human interrupts.
- The base local memory backend has no dependencies and supports BM25 recall; the documented Provider variation keeps Session and Workflow code stable across model vendors.
- Most model examples require OpenAI-compatible environment variables or a configured Provider; the supplied material does not document a complete model-free Agent execution path.
- Production deployment adds infrastructure requirements: PostgreSQL is the durable store, while Redis and S3-compatible storage serve operational roles.
- The Agent Server HTTP interface is explicitly Beta, and v1 JSONL imports are historical records rather than resumable active Runs.
- Synchronous steps cannot declare a preemptive timeout; enforcing a deadline requires an async step or an isolated executor.
- The local Sandbox runs filesystem, command, and code tools in the bound host workspace, so adopters must assess that execution boundary.
How does this agent compare with similar options?
OpenRath frames its design through PyTorch analogies: Session maps to Tensor, Sandbox/Backend to Device, Memory to Parameter, Tool to Function, Agent to nn.Linear, and Workflow to nn.Module. It also documents local and OpenSandbox execution backends, plus local and OpenViking memory backends.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OpenRath This agent | 47 · Major gaps | Library / SDKFree + model costs | ★ 957 | 1mo ago | Python | OpenAI API |
| FlowCraft | 77 · Good | CLIFree + model costs | ★ 410 | 4d ago | Go | OpenAI API · Claude API |
| LightAgent | 60 · Some gaps | Library / SDKFree + model costs | ★ 1.2k | 9d ago | Python | OpenAI API |
| LlamaAgents | 66 · Some gaps | Library / SDKFree + model costs | ★ 464 | 6d ago | Python | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README describes production-mode permission controls (e.g., tokens carry explicit action grants, tenant/project scoping, policy checks, secret references, trust labels, audit), but lacks implementation details or configuration examples. User confirmation mechanisms (e.g., NEEDS_REVIEW interrupts) are mentioned but not detailed. Data flow transparency: Session and lineage concepts provide traceability, but no actual data flow diagrams or logs are shown. Sensitive data handling: only secret references mentioned, no encryption or masking. Dependency security: dependencies listed in pyproject.toml but no vulnerability scanning or lock file review (uv.lock exists but not examined). External effects: Effect Ledger and idempotency keys mentioned but not implemented. Rollback: checkpoints and resumable queues mentioned but no rollback mechanism. Source attribution: README and LICENSE provide copyright, but publisher unverified. Deductions: most security features are asserted without evidence, and publisher identity unknown.
Evidence shows: API descriptions in README and pyproject.toml are consistent; test_public_surface.py verifies sync public API, indicating good internal consistency. Dependencies are clearly listed, and CI workflows for build and lint are configured, but no dependency availability tests. Failure messages: NEEDS_REVIEW state mentioned but no error handling examples. Deductions: specific failure message formats and error handling strategies not shown.
Evidence shows: README clearly describes multiple use cases (single-agent, multi-agent, multi-session, etc.) with example code and directory, indicating good audience and scenario coverage. Capability boundaries: distinguishes FlowToolCall and BackendTool, and explains pluggable sandbox and memory backends. Trigger precision: Selector and workflow triggers described but not detailed. Environment fit: supports local, OpenSandbox, OpenViking backends, and environment variable configuration. Deductions: trigger precision and some environment configuration details insufficient.
Evidence shows: README structure is clear, with installation, examples, and docs links, good information architecture. Install notes are detailed, including pip and optional dependencies. Naming stability: v2.0.0 mentioned as production version but no naming conventions or API stability statement. Examples and FAQ: 12 examples provided but no FAQ. Known limitations: Agent Server HTTP surface is Beta, but other limitations not listed. License: BSD-3-Clause, compliant. Versioning and changelog: v2.0.0 mentioned but no CHANGELOG. Maintenance responsibility: GitHub links provided but no explicit maintainers. Deductions: missing FAQ, CHANGELOG, and explicit maintainer info.
Evidence shows: README provides multiple examples, output is Session object, easy to use. Marginal value: OpenRath offers unique multi-agent multi-session paradigm, potentially high value. Cost-benefit: README mentions context reuse and token reduction but no benchmarks. Deductions: cost-benefit lacks data support.
Evidence shows: Claims in README (e.g., production features) lack implementation or test evidence. Cross-source corroboration: README cites arXiv paper and docs site but no other independent sources. Fact-inference separation: design philosophy and features are mixed, not clearly separated. Deductions: claims lack traceability and independent verification.
- Publisher identity is unverified; treat with caution.
- Security features (e.g., permission controls, audit) are asserted in README but lack implementation details; further code review needed.
- Dependency security lacks vulnerability scanning or lock file review; consider checking uv.lock and dependency versions.
- Missing FAQ, CHANGELOG, and explicit maintainer info may affect long-term maintenance.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v2.0.0 OpenRath v2.0.0
Release notes excerpt
OpenRath v2.0.0 OpenRath 2.0.0 将框架从进程内 Agent 工作流扩展为可部署的持久化多 Agent Runtime 与 Agent Server。本版本引入可恢复执行、受治理的副作用、人工中断、安全与租户边界，以及面向 PostgreSQL、Redis、S3 和 OpenTelemetry 的生产部署能力。  核心特性 持久化 Runtime - 显式编译模型 — @step、@router 编译为规范化执行计划与不可变 revision。 - 可恢复 Run — Events、Checkpoints、Interrupts、取消、截止时间、重试、租约 fencing 与队列恢复形成完整生命周期。 - 受控副作用 — Effect Ledger 保存结果和幂等键；无法安全判定的非幂等操作进入 NEEDS_REVIEW，避免盲目重放。 …View on GitHub ↗ -
Release notes excerpt
OpenRath v1.3.0 在 v1.2.2 的 LiteLLM 接入与运行时健壮性之上，v1.3.0 把重心放在基础层加固与 Workflow 静态编译上。持久化写入、配置/凭据分离、环境变量解析、Provider 重绑定与 Workflow.compile() 构成一条连贯的「先 inspect、再 validate、再运行」路径；OpenSandbox 适配层与 CI 也去掉了对 --reruns 的依赖，用更长超时与有针对性的重试消除 flaky。没有 intentional 破坏性改动：内联 api_key 仍可加载并在下次保存时迁移到 credentials.json，compile() 为纯 opt-in。 核心特性 持久化与布局（atomic writes + manifest + GC） - rath.persistence.atomic — atomic_write_text / atomic_write_json：临时文件 + os.replace、路径级锁、Windows sharing-violation 重试；修复 Windows 并发保存 config 时的 PermissionError。 …View on GitHub ↗ -
Release notes excerpt
OpenRath v1.2.2 延续 v1.2.1 的动态工作流之后，v1.2.2 把重心放在接入面与运行时健壮性上。核心新特性是 litellm provider：通过一个薄适配器把 OpenRath 接到 100+ 模型供应商（Gemini、Bedrock、Azure、Ollama、Groq……），不必再在内置 Provider / chat_client_for 之外手工接线。围绕它，本版补齐了 Session 的常用取值与序列协议，并集中修复了一批并发竞态、内存增长与持久化 round-trip 的问题。没有破坏性改动，可从 v1.2.1 直接升级。 核心特性 LiteLLM provider（一个适配器接入 100+ 模型） 新增 provider_kind="litellm"，经 [LiteLLM](https://github.com/BerriAI/litellm) 路由到上百家供应商。RathLiteLLMChatClient 复用 OpenRath 既有的 OpenAI 归一化与 kwargs 构造逻辑（LiteLLM 返回 OpenAI 兼容响应），因此适配层很薄，并且不改动既有 provider 分派，也不引入新的运行时依赖： …View on GitHub ↗
FAQ
Is OpenRath limited to OpenAI models?
Provider while Session and Workflow code remains stable.Can I evaluate it without a model API key?
How are ambiguous side effects handled after a failure?
NEEDS_REVIEW instead of being replayed blindly.