🌟 Experience Sage's Power

🧠 Sage · Custom, Self-Evolving Agents

🎯 Define Your Agent. Evaluate. Evolve.

🌟 An open-source platform for building custom, self-evolving AI agents. Define an Agent package, evaluate it, and improve it through multiple RSI rounds — with version history and your choice of which version to adopt.

---

New to RSI? Inspect your first run: a scripted Python walkthrough with no model API key.

✨ Why Sage

• 📦 Custom Agent packages — Define your agent's instructions, Skills, tools, and runtime configuration in sage.yaml; reuse packages in Desktop, Server, or your Python application.
• 🧬 Self-evolution with RSI — Test and refine packages over configurable rounds using evaluation, tuning, and review agents in separate Sessions. Retain every iteration and choose which version to use.
• 🧩 Plugin-based architecture — Compose model, memory, storage, tool, and scheduling providers with explicit contracts and managed lifecycles.
• 🪟 Native streaming UI (Desktop 2.1) — Uses the official OpenUI parser with Sage’s Flutter Glass renderer. Assistant openui blocks render as output arrives, with light/dark themes and 31 native component types: charts, metrics, tabs, diagrams, rich inputs, and immediate local calculations. Local-only interfaces need no submit button or model round-trip; a submit button explicitly hands values back to the assistant. Users can ask naturally without mentioning OpenUI. Enable Prefer interactive UI in the composer plus menu, or set Settings → General → Interactive UI on by default for new chats; enabling it preloads the complete built-in Skill without a tool call. Presentations stream as native 16:9 slides and export editable PPTX from the same document. This is a supported component subset, not the upstream Web renderer; included in the 2.1.0 desktop packages. Integration details.
• 🔄 Stateful, interactive execution — Durable Session history, streamed events, and pause/resume with human input and approvals.
• 🤝 Multi-agent orchestration — Coordinate Studio members through directed messages, or compose Agent Flows in the runtime.
• 🔌 An extensible tool ecosystem — Bring built-in tools, reusable Skills, and MCP services into the same agent workflow.
• 🏗️ One runtime, multiple hosts — Use SAgents v2 through Desktop and Server, or embed it in your own Python application.

---

🧬 RSI: From Custom Agents to Self-Evolution

Supply an Agent package, choose a goal, round count, and editable scope, and run an independent RSI (Recursive Self-Improvement) loop.

• Control what evolves — Optimize only Skills, or allow instruction guidance, tool enablement, and step budgets. Supply your own test suite or generate one with a test-design agent; test single-turn tasks and conversations with bounded turn counts.
• Evaluate and review independently — A separate audit Session checks test-suite alignment with the authorized goal before any target execution. Evaluation and candidate semantic review then check completion, memorization, and goal drift in separate Sessions. An independent final suite is sealed before baseline evaluation.
• Inspect every iteration — Retain the original package, every iteration's complete package, test responses, evaluations, and review results. Desktop shows background progress and RSI run histories. Agent settings separately retain saved and applied configuration versions; unapplied candidates stay in their RSI runs.
• Choose what to adopt — Optimization produces candidates without replacing your configuration. Inspect the comparison, select a version, and explicitly confirm before Desktop applies it. Keep the original when no better candidate emerges.

See the RSI workflow guide. Use AgentPackageOptimizer through the Python API, or open RSI from Desktop Agent settings. Desktop RSI currently supports simple Agents and native tools; installer availability follows each release's notes.

---

📰 Latest updates

• 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, test-suite alignment audits, independent final tests and semantic review, plus Desktop progress and Agent-level version history. 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 →

---

🚀 Get Started

Choose your path	Start here
💻 Desktop v2 — Configure agents, run RSI, and choose versions	Desktop guide
🌐 Server v2 — Multi-user web access and Agent Studio	Server guide
🧠 SAgents v2 — Build and optimize agents through Python	Runtime quick start
📦 Desktop installers — Available release builds	Downloads & release instructions

📦 Desktop installer

1. Download Sage 2.1.0 for macOS (arm64/x86_64), Windows (x86_64), or Linux (arm64/x86_64).
2. 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.
3. Add your model in Settings → Configure an Agent → Start a conversation. Your model service may charge usage fees. See the Desktop guide.
4. macOS packages are not notarized; Windows installers are not code-signed. See the release notes for package details.

💻 Desktop from source

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 .
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.0 release notes. GitHub Actions builds Flutter v2 installers with an embedded Python runtime; the legacy Tauri installers belong to v1.

🌐 Server from source

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-v2]'
cp app/v2/server/.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 v2 currently supports one worker; MySQL persistence does not enable horizontal scaling.

🧑‍💻 Run your first SAgents v2 agent

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."""

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}
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
agents:
  main:
    name: Assistant
    instructions: {inline: "Be helpful and concise."}
    models: {primary: primary}
entrypoint: {agent: main}
"""


async def main():
    manifest = SageManifestLoader().loads(AGENT_YAML)
    app = await SAgentBuilder().with_defaults(session_root="runtime").build(manifest)
    try:
        context = RequestContext(actor=ActorRef(
            principal_id="user-1", principal_type=PrincipalType.USER,
        ))
        stream = await app.entrypoint().run_stream(StartRun(
            agent_id="main",
            input=(InputItem(role="user", content=(TextBlock(text="Say hello!"),)),),
            resolved_spec_hash=app.composition_hash,
            idempotency_key=str(uuid4()),
        ), context)
        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 →

---

🧠 Built on SAgents v2

flowchart TB
    desktop["Desktop v2<br/>Flutter workspace"]
    server["Server v2<br/>Web & Agent Studio"]
    custom["Your application<br/>Python integration"]

    runtime["SAgents v2<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 →

---

📚 Documentation

Learn	Build
Documentation index	Runtime integration manual
Desktop v2	Server Agent platform
Server v2	Deployment
Versioned source layout	v1 directories and import migration
Release notes	Development changelog

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 🦌