🌟 Experience Sage's Power

🧠 Sage Agent Platform

🎯 From Complex Work to Reliable Delivery

🌟 An open-source agent platform for project work, tool execution, and multi-agent collaboration — on your desktop, on the web, or in your own application.

✨ 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 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. Packaged releases follow their own release instructions; the existing release workflow builds the legacy Tauri app.

🌐 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  
Flutter workspace"]
    server["Server v2  
Web & Agent Studio"]
    custom["Your application  
Python integration"]

    runtime["SAgents v2  
Agent packages · Sessions · Runs"]

    desktop --> runtime
    server --> runtime
    custom --> runtime

    runtime --> intelligence["Models & context  
Providers · Memory"]
    runtime --> capabilities["Tools & workflows  
Skills · MCP"]
    runtime --> execution["Execution & state  
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

Explore sagents/v2/ for the runtime, app/v2/desktop/ for the desktop app, and app/v2/server/ for the web platform.

Contributions are welcome through Issues and pull requests. Include reproduction steps and run the affected component's checks: Python tests live in tests/; Desktop v2 uses flutter analyze and flutter test.

💬 Community

💖 Sponsors

MIT License · Built with ❤️ by the Sage Team 🦌