Sage RSI Agent Harness
Improve agents through task feedback, with every candidate version backed by recorded evidence.
- Source repo
- ZHangZHengEric/Sage
- Stars
- ★ 1.2k
- Last updated
- 1d ago
- License
- MIT
- Primary language
- Python
- FA score
- 48/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Teams that want to raise a support or retail dialogue agent's success rate and keep auditable evidence for each change
- Not a fit if
- Teams needing horizontal scaling or multi-worker server deployment
- Teams requiring strong container-level isolation for untrusted code
- Teams expecting RSI candidates to be auto-activated without review
- Website
- zhangzhengeric.github.io/Sage ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-20latest release v2.2.0 (2026-11-13)+0.6 ★/day over 7 days
- Source review
- 48/100 · Major gaps
What does this agent do, and when should you use it?
Sage is an RSI (Recursive Self-Improvement) agent harness that turns a goal or curated usage history into comparable agent versions through a loop of Runner execution, independent Evaluator grading, Tuner optimization, and version selection. Its SAgents v2 runtime defines agent packages in sage.yaml (instructions, Skills, tools, resources) and provides model routing, context budgets, MCP tools, persistent Sessions, and Runs that can pause and resume for human input or approvals. It ships in three forms: a Flutter Desktop app, a multi-user Server with Agent Studio, and an embeddable Python SDK built on SAgentBuilder, StartRun, and run_stream. RSI only produces candidates, leaving adoption, diffs, and evaluation records in your hands. Built-in deployments target a single process or host, Server supports one worker, and local process execution is explicitly not container isolation. The README also reports an exploratory local τ²-bench retail experiment (40 test tasks, four trials each, task success 75.000% → 83.125%) and labels it as not an official leaderboard result.
An agent package is declared in sage.yaml with metadata, agents (instructions, models), and entrypoint; credentials can be pulled from environment variables. SageManifestLoader().loads() parses YAML text, and SAgentBuilder().build() assembles the runtime and application. You execute by calling ApplicationEntrypoint.run_stream(StartRun(...), context, agent=agent) with InputItems containing TextBlock content, consuming a stream of events and then awaiting stream.wait() for the final state; Sessions persist conversation history across Runs and can pause for human input or approvals. The RSI loop feeds a goal or curated history to the Runner, grades with an independent Evaluator over train/dev suites and a separate test measurement, and lets the Tuner (gpt-6.1-sol in the published experiment) propose candidates while retaining diffs and evaluation records for manual selection. The host binds sandbox providers, tool policies, runtime budgets, and credentials, and can swap model, memory, storage, tool, and scheduling providers. Desktop adds streaming OpenUI surfaces with local calculations and editable PPTX export.
- Teams that want to raise a support or retail dialogue agent's success rate and keep auditable evidence for each change
- Python developers embedding a streaming, pausable multi-turn agent into their own backend services
- Internal platform teams standing up a multi-user agent management and tuning portal with Server and Agent Studio
- Engineers prototyping with native tools, reusable Skills, and MCP services on a local machine
- Regulated environments that need human approval gates and sandbox policy rather than fully autonomous execution
- Users who prefer a visual desktop app to watch RSI progress and per-agent version history
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Environment variables
MODEL_API_KEY- Config files
.env.exampleapp/v2/server/.envsage.yaml- Runtime
- Python 3.12+ · Node.js 22.12+
- Install notes cover
- Windows · macOS · Linux
How do you install or deploy this agent?
Download the 2.1.1 desktop installer for macOS (arm64/x86_64), Windows (x86_64), or Linux (arm64/x86_64); Python and the backend are bundled, so no checkout or system Python/Flutter is needed. Linux still requires GTK and bubblewrap. macOS packages are not notarized and Windows installers are not code-signed.
Running Desktop from source requires Python 3.12+ and Flutter with desktop support (Dart ^3.12.2):
git clone https://github.com/ZHangZHengEric/Sage.git
cd Sage
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[desktop]'
cd app/v2/desktop
flutter pub get
flutter run -d macosServer requires Python 3.12+, MySQL, and Node.js 22.12+:
python -m pip install -e '.[server]'
cp .env.example app/v2/server/.env
cd app/v2/server/web
npm install
npm run build
cd ../../..
python -m app.v2.serverFill in the MySQL connection, JWT secret, and initial administrator credentials in .env.
How do you use this agent?
Shortest path: install Desktop, add a model under Settings, configure an agent, then start a conversation or open a project. The app boots its local backend automatically; settings and session data live in ~/sage/runtime and the default workspace is ~/sage/agent_workspace.
Without an API key you can run the offline RSI walkthrough to inspect a scripted loop. With the Python SDK, a single file runs one agent with no sage.yaml file required:
from sagents.v2.composition.loaded_agents import ApplicationEntrypoint
from sagents.v2 import ActorRef, RequestContext, SAgentBuilder, StartRun
from sagents.v2.contracts.commands import InputItem
from sagents.v2.contracts.items import TextBlock
from sagents.v2.contracts.principals import PrincipalType
from sagents.v2.package.manifest import SageManifestLoader
manifest = SageManifestLoader().loads(AGENT_YAML)
app = await SAgentBuilder().build(runtime=default_runtime("runtime"), models_config_text=MODELS_YAML)
agent = await app.load_agent(manifest)
stream = await cast(ApplicationEntrypoint, app.entrypoint()).run_stream(StartRun(
agent_id=agent.id,
input=(InputItem(role="user", content=(TextBlock(text="Say hello!"),)),),
resolved_spec_hash=agent.composition_hash,
idempotency_key=str(uuid4()),
), RequestContext(actor=ActorRef(principal_id="user-1", principal_type=PrincipalType.USER)), agent=agent)
async for event in stream.events:
print(event.model_dump_json())Supply the model key via environment variable:
export MODEL_API_KEY="your-api-key"
python quickstart.pyAfter starting Server, open localhost:8090; /studio manages agent packages.
What are this agent's strengths and limitations?
- Clean RSI separation of concerns: Runner executes, an independent Evaluator grades, the Tuner optimizes, and train/dev drives selection while test stays observation-only
- Candidates are never auto-activated; diffs and evaluation records are retained for human sign-off
- One SAgents v2 runtime powers the Flutter desktop app, the multi-user server, and an embeddable Python SDK, with swappable model, memory, storage, tool, and scheduling providers
- Ships MCP tooling, reusable Skills, persistent Sessions, and pause/resume approvals, which is unusual depth for an agent harness
- Publishes a reproducible τ²-bench retail protocol with per-trial data and honestly flags it as exploratory local measurement
- Offers an offline RSI walkthrough that needs no API key, lowering the cost of evaluating the approach
- Server supports only one worker; MySQL persistence does not enable horizontal scaling, distributed job takeover, or automatic checkpoint resume
- Local process execution is not container isolation, so untrusted code should not be run this way
- Desktop RSI currently supports only simple types and native tools; general MCP support does not imply RSI bindings
- Building from source pulls in Python 3.12+, Flutter, MySQL, and Node.js 22.12+, plus GTK and bubblewrap on Linux
- macOS installers are not notarized and Windows installers are unsigned, adding friction for managed fleets
- Some component guides exist only in Chinese, so English readers may need to switch languages
- The reported benchmark gain comes from a single exploratory experiment with no independent replication
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Sage RSI Agent Harness This agent | 48 · Major gaps | Desktop appFree + model costs | ★ 1.2k | 1d ago | Python | OpenAI API |
| NextClaw | 61 · Some gaps | Desktop appFree + model costs | ★ 264 | 1d ago | TypeScript | Codex · Claude Code |
| PocketPaw | 44 · Major gaps | Desktop appFree + model costs | ★ 934 | 2d ago | Python | Codex · OpenAI API · Claude API |
| OpenWork | 71 · Some gaps | Desktop appFreemium | ★ 25k | today | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Trust evidence is limited. least_privilege: README mentions sandbox, tool policies and host authorization, but the sampled agent-browser skill allows broad Bash(npx agent-browser:*) and Bash(agent-browser:*) with no fine-grained restriction shown, so 1. user_confirmation: brainstorming skill has a HARD-GATE requiring user approval and README mentions approvals and pause/resume, but product-level confirmation is not fully evidenced, 1. data_flow_transparency: CONFIGURATION explains credential declaration and reference without embedding secrets, but model data flows (e.g. default OrcaRouter endpoint) are only briefly described, 1. sensitive_data_handling: TROUBLESHOOTING requires redacted logs and no API keys; the AstrBot plugin suppresses exception text and bounds image/text size, 2. dependency_security: pyproject pins mcp==1.28.1 and lark-oapi==1.7.5 but most deps use loose lower bounds; no vulnerability scanning or SBOM shown, 1. external_effects: README states RSI produces candidates without activating them and advises reconciling unknown tool outcomes before retry, but browser automation and other side effects lack unified rollback, 1. rollback: versions and diffs are retained, but docs explicitly say persistent state provides no distributed takeover or automatic checkpoint resume, 1. source_attribution: LICENSE copyright is Zavixai while pyproject author is Eric ZZ and publisher is unverified, so attribution is inconsistent, 1.
self_consistency: README, CONFIGURATION and TROUBLESHOOTING agree on single worker, MySQL requirement and Python 3.12+, 2. dependency_availability: dependencies are public PyPI packages, but server/desktop need MySQL, Node, Flutter and bubblewrap, and some version constraints are loose, 1. failure_messages: TROUBLESHOOTING gives symptom-check tables, the AstrBot plugin has structured error codes and Chinese messages, and the CLI exposes next_steps, 2.
audience_and_scenarios: covers Desktop, Server and Python SDK hosts across multiple scenarios, 2. capability_boundaries: README states RSI support boundaries, single-process/single-worker limits and that local execution is not container isolation, 2. trigger_precision: skill descriptions use broad triggers (brainstorming claims it MUST be used before any creative work; agent-browser covers many tasks), risking over-triggering, 1. environment_fit: gives macOS/Windows/Linux install paths and Linux GTK/bubblewrap requirements, 2.
information_architecture: README has clear navigation tables and collapsible sections; docs are bilingual with nav_order, 2. install_notes: Desktop install, source run and Server run steps are concrete, 2. naming_stability: v1/v2 coexist with Sage/SAgents/Desktop/Server naming and scattered migration notes, 1. examples_and_faq: full Python quickstart, offline RSI walkthrough and troubleshooting table, 2. known_limitations: explicitly lists RSI boundaries, single worker, unsigned installers and partly Chinese-only docs, 2. license: full MIT text present and consistent with pyproject, 2. versioning_changelog: version badge 2.1.1 plus release_notes and change_log references, 2. maintenance_responsibility: publisher unverified, only 'Sage Team' and a contribution guide, so ownership is unclear, 1.
output_usability: quickstart yields an event stream and final state; Desktop/Server provide usable UIs, 2. marginal_value: the RSI experiment snapshot is an exploratory local measurement, not an official leaderboard, with modest gains and self-reported regressions, 1. cost_benefit: requires model API spend plus heavy MySQL/Node/Flutter dependencies while benefit evidence is thin, 1.
claim_traceability: README claims link to an experiment protocol and per-trial JSON, but that data file is not in the packet and cannot be checked, 1. cross_source_corroboration: README, CONFIGURATION and TROUBLESHOOTING corroborate some facts, but the experiment conclusion rests on a single source, 1. fact_inference_separation: docs mostly separate claims from boundaries, but the experiment snapshot is mixed with product capabilities without explicit inference labeling, 1.
- Publisher identity is unverified and the LICENSE copyright (Zavixai) differs from the pyproject author (Eric ZZ); verify provenance and maintainer before adoption.
- Skills such as agent-browser grant broad Bash execution; browser automation can cause external side effects like logins and form submissions, so use in a controlled environment with approvals.
- The RSI experiment gain in README is an exploratory local measurement, not an official leaderboard, and the per-trial data is not in the packet; do not generalize from it.
- Server supports only one worker and local execution is not container isolation; it depends on heavy external components (MySQL, Node, Flutter, bubblewrap).
- Most dependencies use loose lower bounds with no vulnerability scanning or SBOM shown; pin and audit dependencies yourself.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v2.2.0 Sage 2.2.0
Release notes excerpt
Sage 2.2.0 新增与改进 - 桌面插件。在桌面端上传、打开和固定 HTML/CSS/JavaScript 插件。Agent 可以用内置插件开发 Skill 与示例生成、注册插件,并在发起请求的窗口打开。插件可通过宿主接口使用存储及获授权的能力。 - 桌面工作台。改进项目导航、对话历史恢复、消息和工具过程展示。开启「优先交互 UI」后按对话预加载 OpenUI;关闭后省去这部分上下文。 - Sage Voice。仓库新增独立语音客户端,支持流式语音、实时字幕和打断。可以逐项启用 Agent 工具,编辑中英文进度播报,使用临时工作区和目标模式。Voice 从源码单独运行。 - Skill 与执行恢复。支持按 Run 授权发现和按引用加载 Skill,并支持 Skill 版本管理。改进模型能力探测、工具或模型调用失败后的受限恢复,以及本地沙箱的联网与 Office 文档转换。 - 内置 Skill 调整。缩减随安装包分发的通用 Skill,新增桌面插件开发 Skill 与示例。 - RSI、Server 与诊断。完善数据集治理、重复评估与版本追踪,新增成对网页设计评估。增加 Feishu 等 IM 集成能力、运行耗时和请求诊断,并扩展 SQL 观测存储与 libSQL 记忆后端。 Highlights …View on GitHub ↗ -
v2.1.1 Sage 2.1.1
Release notes excerpt
Sage 2.1.1 Patch release containing the changes merged since 2.1.0. 本次补丁版本包含 2.1.0 之后合入的更新。 Changes / 更新 - Improve Desktop agent configuration, resource selection, skill import, settings and chat history rendering. - Unify v2 agent and Team execution, improve durable recovery, and suspend uncertain tool outcomes for reconciliation. - Improve sandbox execution, shared Team sandbox leases, workspace isolation and session authorization. - Improve Server model and plugin configuration, session diagnostics, and request latency reporting. …View on GitHub ↗ -
v2.1.0 Sage 2.1.0
Release notes excerpt
Sage 2.1.0 Native interactive UI / 原生交互式界面 Sage Desktop now uses the official [OpenUI](https://github.com/thesysdev/openui) parser with its own native Flutter Glass renderer. Assistant output renders incrementally as text arrives, with light and dark themes and 31 registered component types. This is a supported native component subset, not the upstream Web renderer or OpenUI Cloud Reports API. Desktop 使用 OpenUI 官方解析器和 Flutter 原生 Glass 组件随文本输出增量渲染,支持深浅色与 31 类注册组件。加号菜单可开启“优先交互 UI”,设置 → 通用可指定新聊天的默认值;开启时自动加载内置 Skill,无需调用工具加载渲染能力。 …View on GitHub ↗
FAQ
Will RSI change my agent automatically?
Does Sage cost anything?
Can I serve multiple users?
Does the built-in sandbox isolate untrusted code?
Can I cite the README's success-rate gain?
Is Sage RSI Agent Harness open source?
Is Sage RSI Agent Harness still maintained?
Who makes Sage RSI Agent Harness?
What is Sage RSI Agent Harness's official website?
Thanks — we use this to improve the page.