Sage RSI Agent Harness

Improve agents through task feedback, with every candidate version backed by recorded evidence.

Stars
★ 1.2k
Last updated
1d ago
License
MIT
Primary language
Python

At a glance

How it runs
Desktop appLibrary / SDKSelf-hosted service
Works with
Portable with changesOpenAI API
Cost
Free software; you pay for model usage
Setup effort
Medium · a few setup steps
You'll need
Python 3.12+Flutter with Dart ^3.12.2 (desktop from source)MySQL (server)Node.js 22.12+ (server web build)GTK and bubblewrap (Linux desktop)Shell / CLINetwork accessLocal filesystemMCP Server
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
Maintenance
Commits in the last 30 dayslast commit 2026-11-20latest release v2.2.0 (2026-11-13)+0.6 ★/day over 7 days

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.

  1. Teams that want to raise a support or retail dialogue agent's success rate and keep auditable evidence for each change
  2. Python developers embedding a streaming, pausable multi-turn agent into their own backend services
  3. Internal platform teams standing up a multi-user agent management and tuning portal with Server and Agent Studio
  4. Engineers prototyping with native tools, reusable Skills, and MCP services on a local machine
  5. Regulated environments that need human approval gates and sandbox policy rather than fully autonomous execution
  6. 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.example app/v2/server/.env sage.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 macos

Server 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.server

Fill 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.py

After starting Server, open localhost:8090; /studio manages agent packages.

What are this agent's strengths and limitations?

Pros
  • 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
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Major gaps
48/ 100 5-point scale 2.4 / 5
This review covers the source as of Nov 11, 2026. The project has shipped 1 stable release(s) since, which have not been re-reviewed. The score and verdict describe the reviewed version only. Recent releases ↓
Trust 11/29
Reliability 8/14
Adaptability 10/18
Convention 10/18
Effectiveness 6/13
Verifiability 3/8
Why each dimension lost points
Trust11 / 29 · 1.9/5

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.

Reliability8 / 14 · 2.9/5

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.

Adaptability10 / 18 · 2.8/5

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.

Convention10 / 18 · 2.8/5

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.

Effectiveness6 / 13 · 2.3/5

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.

Verifiability3 / 8 · 1.9/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 11, 2026 Reviewed revision 20d23f4181f9 New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/zhangzhengeric-sage.svg)](https://followagents.com/en/agents/zhangzhengeric-sage)
<a href="https://followagents.com/en/agents/zhangzhengeric-sage"><img src="https://followagents.com/badge/zhangzhengeric-sage.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. 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 ↗
  2. 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 ↗
  3. 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?
No. RSI only produces candidate versions with grading evidence; adoption is your decision. The default workflow uses a fixed dev suite and an expanding train suite, with independent test measurements kept observational.
Does Sage cost anything?
The code is MIT-licensed and free to use, but you supply your own model provider API keys and pay that provider for usage. An offline RSI walkthrough is available if you want to try the loop without keys.
Can I serve multiple users?
Yes, via the Server build, which includes JWT auth and Agent Studio, but the docs state it currently supports one worker only and MySQL persistence does not enable horizontal scaling.
Does the built-in sandbox isolate untrusted code?
Not as a guarantee. The README states local process execution is not container isolation; sandbox providers and tool policies must be bound and configured by the host.
Can I cite the README's success-rate gain?
With caution. It comes from a τ²-bench v1.0.1 retail run with gpt-5.6-luna over 40 test tasks at four trials each, and the authors describe it as exploratory local measurement rather than an official leaderboard result.
Is Sage RSI Agent Harness open source?
Yes. The source code is on GitHub (ZHangZHengEric/Sage) under the MIT licence.
Is Sage RSI Agent Harness still maintained?
Yes. The latest commit on GitHub is from 2026-11-20, within the last 30 days. The latest release is v2.2.0 (2026-11-13).
Who makes Sage RSI Agent Harness?
Sage RSI Agent Harness is published on GitHub by the account ZHangZHengEric. FollowAgents has not verified which person or company is behind that account.
What is Sage RSI Agent Harness's official website?
The project's GitHub repository lists https://zhangzhengeric.github.io/Sage/ as its website. That link is set by the repository owner; the source code itself is on GitHub (ZHangZHengEric/Sage).
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts