✨ Why Sage

• 🧩 Plugin-based architecture — Compose model, memory, storage, tool, and scheduling providers with explicit contracts and managed lifecycles.
• 📦 Declarative Agent packages — Define instructions, capabilities, and runtime configuration in sage.yaml; manage immutable versions in Server Studio.
• 🔄 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.

🚀 Get Started

📦 Desktop installer

1. Download Sage 2.0.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.0 packages and the release boundary are documented in v2.0.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

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