Sage — RSI Agent Harness
Sage is an RSI Agent Harness for improving agents through task feedback. RSI (Recursive Self-Improvement) starts from a goal or curated usage history, retains each version and its evidence, and leaves adoption in your hands.
Try RSI · Download Desktop · Python SDK · Docs
🔄 How RSI works
Workflow guide · Evaluation and selection rules · Editable diagram (SVG)
🚀 Get Started
Sage, Desktop, Server, and SAgents refer to the current v2 implementation by default. For the legacy version, use the separate Sage v1 guide.
- Download Sage 2.1.1 for macOS (arm64/x86_64), Windows (x86_64), or Linux (arm64/x86_64).
- Install and open Sage. Python and the backend are bundled; no repository checkout, system Python, or Flutter is needed. Linux still requires GTK and bubblewrap.
- Add your model in Settings → Configure an Agent → Start a conversation. Your model service may charge usage fees. See the Desktop guide.
- macOS packages are not notarized; Windows installers are not code-signed. See the release notes for package details.
Requires Python 3.12+ and Flutter with Dart ^3.12.2 and desktop support. On macOS:
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
Add a model → Configure an Agent → Start a conversation or open a project.
The app starts its local backend automatically. Settings and session data live in ~/sage/runtime; the default workspace is ~/sage/agent_workspace.
For Windows and Linux setup, see the Desktop guide. Sage 2.1 packages and the release boundary are documented in v2.1.1 release notes. GitHub Actions builds Flutter v2 installers with an embedded Python runtime; the legacy Tauri installers belong to v1.
Requires Python 3.12+, MySQL, and Node.js 22.12+. From the checkout root, with the Python environment active:
python -m pip install -e '.[server]'
cp .env.example app/v2/server/.env
Set the MySQL connection, JWT secret, and initial administrator credentials in .env, then run:
cd app/v2/server/web
npm install
npm run build
cd ../../..
python -m app.v2.server
Open localhost:8090. Add a model and an Agent to start chatting, or open /studio to manage Agent packages.
See the Server guide for configuration. Server currently supports one worker; MySQL persistence does not enable horizontal scaling.
One Python file; no sage.yaml required. After the Python setup above, save as quickstart.py and replace your-model with an available model:
"""Set MODEL_API_KEY and replace your-model below; no sage.yaml file is needed."""
from typing import cast
from sagents.v2.composition.loaded_agents import ApplicationEntrypoint
import asyncio
from uuid import uuid4
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
AGENT_YAML = """
schema_version: sage/v2
kind: application
metadata: {id: example.assistant, version: 1.0.0, name: Assistant}
agents:
main:
name: Assistant
instructions: {inline: "Be helpful and concise."}
models: {primary: primary}
entrypoint: {agent: main}
"""
MODELS_YAML = """
credentials:
api-key: {source: env, key: MODEL_API_KEY}
models:
primary:
provider: openai-responses
base_url: https://api.openai.com/v1
credential: api-key
model: your-model
"""
async def main(*, runtime=None, registrations=()):
from sagents.v2.composition.defaults import default_runtime
manifest = SageManifestLoader().loads(AGENT_YAML)
builder = SAgentBuilder()
for registration in registrations:
builder.register(registration)
app = await builder.build(runtime=runtime or default_runtime("runtime"), models_config_text=MODELS_YAML)
try:
agent = await app.load_agent(manifest)
context = RequestContext(actor=ActorRef(
principal_id="user-1", principal_type=PrincipalType.USER,
))
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()),
), context, agent=agent)
async for event in stream.events:
print(event.model_dump_json())
print((await stream.wait()).state)
finally:
await app.close()
if __name__ == "__main__":
asyncio.run(main())
export MODEL_API_KEY="your-api-key"
python quickstart.py
loads() parses YAML text; build() accepts the manifest object directly. This prints events and the final state, without file or shell tools. More configuration options →
🛠️ Harness capabilities
| Capability | What you can do |
|---|
| 📦 Packages and versions | Define instructions, Skills, tools, and resources in sage.yaml; retain candidates, diffs, and evaluation records. |
| 🧠 Models and context | Connect model providers and configure routes, memory, and context budgets. |
| 🔌 Tools, Skills, and MCP | Compose native tools, reusable Skills, and MCP services with host-managed authorization. |
| 💾 Stateful execution | Persist Sessions, stream output, and pause/resume for human input and approvals. |
| 🛡️ Sandbox and resources | Bind execution resources, sandbox providers, tool policies, and runtime budgets through the host. |
| 🤝 Multi-agent workflows and extensions | Orchestrate workflows and member messages; replace model, memory, storage, tool, and scheduling providers. |
| 🪟 Native interactive UI | Stream light/dark Glass interfaces, charts, inputs, and slides, with local calculations and editable PPTX export. Explore OpenUI. |
| 🖥️ Multiple hosts | Use Desktop, Server/Studio, or embed SAgents in your Python application. |
- Desktop RSI currently supports simple types and native tools; general MCP integration does not imply support in RSI bindings.
- Built-in configurations target one process or host; Server supports one worker. Local execution is not container isolation.
- Callers curate history into goals or suites. The default workflow uses fixed dev and expanding train; dev guides development and independent test measurements are observation-only.
- RSI produces candidates without activating them. Persistent state does not provide distributed job takeover or automatic checkpoint resume.
RSI support boundaries · Runtime architecture
τ²-bench v1.0.1 retail with gpt-5.6-luna as the target model. The baseline and frozen RSI candidate each completed 40 test tasks with four trials per task, for 320 measurements.
| Metric | Baseline | After RSI | Gain |
|---|
| Task success pass¹ | 75.000% | 83.125% | +8.125 percentage points |
| All-four success pass⁴ | 57.50% | 65.00% | +7.50 percentage points |
gpt-6.1-sol served as tuner, user simulator, and natural-language judge. Train/dev selected the candidate; test did not influence selection. Results retain 28 paired improvements and 15 regressions. This exploratory local measurement is not an official leaderboard result.
Experiment protocol · Per-trial measurements and statistics
flowchart TB
desktop["Desktop<br/>Flutter workspace"]
server["Server<br/>Web & Agent Studio"]
custom["Your application<br/>Python integration"]
runtime["SAgents<br/>Agent packages · Sessions · Runs"]
desktop --> runtime
server --> runtime
custom --> runtime
runtime --> intelligence["Models & context<br/>Providers · Memory"]
runtime --> capabilities["Tools & workflows<br/>Skills · MCP"]
runtime --> execution["Execution & state<br/>Storage · Sandbox · Events"]
- 📦 Agent package — Define what an agent can do.
- 💬 Session — Keep its conversation history across Runs.
- ⚡ Run — Execute a task with live progress and interaction.
Your application owns the UI, authentication, and credentials. Built-in runtime configurations target a single process or host; local process execution is not container isolation.
Explore the runtime → · Read the architecture →
- 2026-10-13 — Streaming UI: from an answer to a native interactive interface — Live generation, local calculations, Process Panel revisions, and editable PPTX export in Desktop 2.1.
- 2026-10-12 — MCP tools are visible, but calls fail: a five-step diagnostic
- 2026-10-12 — RSI: multi-round Agent package optimization, suite audits, semantic review, Desktop progress, and Agent-level version history. See the workflow guide for the current evaluation protocol. Python API · Desktop guide
- 2026-10-11 — OpenRouter free models: selection and limits
- 2026-10-11 — MCP engineering resources: protocols, SDKs, testing, and security
- 2026-10-11 — A read-only MCP smoke test through Sage
More agent resources and tutorials →
📚 Documentation
Model inference provider resources
Some component guides are currently in Chinese. Use the guide for your chosen entry point.
🛠️ Contributing
Your first PR is welcome! Documentation, translations, examples, tests, bug fixes, and model/tool integrations all help Sage grow. We welcome small, focused improvements and are happy to work with you to get useful, well-tested contributions merged.
Start with the contribution guide for setup, component checks, and a PR checklist. Browse open issues, or open an issue to discuss a larger change before building it. A small documentation fix can go straight to a PR.
Explore sagents/v2/ for the runtime, app/v2/desktop/ for the desktop app, and app/v2/server/ for the web platform.
💬 Community
💖 Sponsors
MIT License · Built with ❤️ by the Sage Team 🦌
