Content
<div align="center">
# 🌟 **Experience Sage's Power**
[](README.md)
[](README_CN.md)
[](LICENSE)
[-blue.svg?logo=python)](https://python.org)
[](https://github.com/ZHangZHengEric/Sage)
[](https://deepwiki.com/ZHangZHengEric/Sage)
[](https://join.slack.com/t/sage-b021145/shared_invite/zt-3t8nabs6c-qCEDzNUYtMblPshQTKSWOA)
# 🧠 **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.**
</div>
---
## ✨ **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](https://modelcontextprotocol.io/) 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**
| Choose your path | Start here |
| --- | --- |
| 💻 **Desktop v2** — Local projects and agent collaboration | [Desktop guide](app/v2/desktop/README.md) |
| 🌐 **Server v2** — Multi-user web access and Agent Studio | [Server guide](app/v2/server/README.md) |
| 🧠 **SAgents v2** — Build agents into your own application | [Runtime quick start](sagents/v2/README.md#quick-start) |
| 📦 **Desktop installers** — Available release builds | [Downloads & release instructions](https://github.com/ZHangZHengEric/Sage/releases/tag/v2.0.0) |
### 📦 Desktop installer
1. Download [Sage 2.0.0](https://github.com/ZHangZHengEric/Sage/releases/tag/v2.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](docs/en/applications/DESKTOP.md#first-task).
4. macOS packages are not notarized; Windows installers are not code-signed. See the [release notes](release_notes/v2.0.0.md) for package details.
### 💻 Desktop from source
Requires **Python 3.12+** and **[Flutter](https://flutter.dev/)** with Dart `^3.12.2` and desktop support. On macOS:
```bash
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](app/v2/desktop/README.md). Sage 2.0 packages and the release boundary are documented in [v2.0.0 release notes](release_notes/v2.0.0.md). 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:
```bash
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:
```bash
cd app/v2/server/web
npm install
npm run build
cd ../../..
python -m app.v2.server
```
Open **[localhost:8090](http://localhost:8090)**. Add a model and an Agent to start chatting, or open **`/studio`** to manage Agent packages.
See the [Server guide](app/v2/server/README.md) 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:
```python
"""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())
```
```bash
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 →](docs/en/applications/GETTING_STARTED.md)
---
## 🧠 **Built on SAgents v2**
```mermaid
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 →](sagents/v2/README.md) · [Read the architecture →](sagents/v2/ARCHITECTURE.md)
---
## 📚 **Documentation**
| Learn | Build |
| --- | --- |
| [Documentation index](docs/en/README.md) | [Runtime integration manual](sagents/v2/使用手册.md) |
| [Desktop v2](app/v2/desktop/README.md) | [Server Agent platform](docs/zh/architecture/SERVER_V2_AGENT_PLATFORM.md) |
| [Server v2](app/v2/server/README.md) | [Deployment](deploy/README.md) |
| [Versioned source layout](docs/VERSIONED_LAYOUT.md) | v1 directories and import migration |
| [Release notes](release_notes/) | [Development changelog](change_log.md) |
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](CONTRIBUTING.md) for setup, component checks, and a PR checklist. Browse [open issues](https://github.com/ZHangZHengEric/Sage/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/`](sagents/v2/) for the runtime, [`app/v2/desktop/`](app/v2/desktop/) for the desktop app, and [`app/v2/server/`](app/v2/server/) for the web platform.
## 💬 **Community**
<div align="center">
[](https://join.slack.com/t/sage-b021145/shared_invite/zt-3t8nabs6c-qCEDzNUYtMblPshQTKSWOA)
[](https://github.com/ZHangZHengEric/Sage/issues)
</div>
## 💖 **Sponsors**
<p align="center">
<img src="assets/sponsors/xunhuanzhineng_logo.svg" height="40" align="middle" alt="RcrAI" />
<img src="assets/sponsors/idata_mark.png" height="64" align="middle" alt="Data" />
</p>
---
<div align="center">
[MIT License](LICENSE) · Built with ❤️ by the Sage Team 🦌
</div>
Connection Info
You Might Also Like
No recommendations available