🌟 A production-ready, modular, and intelligent multi-agent orchestration framework for complex problem solving.
Visual Workbench |
Real-time Collaboration |
Multi-format Support |
📖 Detailed Documentation: https://wiki.sage.zavixai.com/
- 🧠 Multi-Agent Orchestration: Support for TaskExecutor (Sequential), FibreAgent (Parallel), and AgentFlow (Declarative) orchestration modes.
- 🎯 Maximized Model Capability: Stable execution of complex tasks even on smaller models like Qwen3.5 35B-A3B, with framework-level optimizations unlocking model potential.
- 🧩 Built-in High-Stability Skills: Pre-installed production-ready Skills that work out of the box, ensuring reliable execution for critical tasks.
- 🛡️ Secure Sandbox: Isolated execution environment (
sagents.utils.sandbox) for safe agent code execution. - 👁️ Full Observability: Integrated OpenTelemetry tracing to visualize agent thought processes and execution paths.
- 🧩 Modular Components: Plug-and-play architecture for Skills, Tools, and MCP Servers.
- 📊 Context Management: Advanced Context Budget controls for precise token optimization.
- 💻 Cross-Platform Desktop: Native desktop apps for macOS (Intel/Apple Silicon), Windows, and Linux.
- 🛠️ Visual Workbench: Unified workspace for file preview, tool results, and code execution with 15+ format support.
- 🔌 MCP Protocol: Model Context Protocol support for standardized tool integration.
git clone https://github.com/ZHangZHengEric/Sage.git
cd SageOption 1: One-Command Startup (Recommended for Development)
# 1. Optional: activate your environment first
# conda activate your-env
# 2. Set your LLM API Key
export SAGE_DEFAULT_LLM_API_KEY="your-api-key"
export SAGE_DEFAULT_LLM_API_BASE_URL="https://api.deepseek.com/v1"
export SAGE_DEFAULT_LLM_MODEL_NAME="deepseek-chat"
# 3. Run the startup script
./scripts/dev-up.shThe script will automatically:
- Check Python (>= 3.10) and Node.js (>= 18) versions
- Create configuration files (minimal mode: SQLite, no external dependencies)
- Install dependencies and start both backend and frontend services
- Create
logs/server.logautomatically - Honor
SAGE_PORTfrom.envfor backend startup and health checks
Optional overrides:
# Explicitly choose a Python executable
PYTHON_BIN=/path/to/python ./scripts/dev-up.sh
# Use uv instead of python -m pip / python -m ...
USE_UV=1 ./scripts/dev-up.shFirst time? The script will prompt you to choose between:
- Minimal mode: SQLite, no external dependencies (recommended for quick start)
- Full mode: MySQL + Elasticsearch + RustFS (for production-like environment)
After starting, open: http://localhost:5173
Option 2: Desktop Application (Recommended for Users)
Download the latest desktop package from GitHub Releases:
- macOS:
.dmg(Intel & Apple Silicon) - Windows:
.exe/.msi - Linux:
.deb(x86_64 / arm64)
macOS
- Download the
.dmgfor your CPU architecture and open it. - Drag
Sage.appinto theApplicationsfolder. - The current macOS build is not yet signed/notarized by Apple. If you see a warning that the developer cannot be verified or Apple cannot check the app for malicious software, open
Applications, right-clickSage.app, chooseOpen, and then clickOpenagain in the dialog. - If macOS still blocks the app, go to
System Settings -> Privacy & Security, find the Sage warning near the bottom, and clickOpen Anyway. - If macOS says the app is damaged or still refuses to launch, run the following command and try again:
xattr -dr com.apple.quarantine /Applications/Sage.appWindows
- Download the
.exeinstaller and run it. - Follow the setup wizard to finish installation.
- If Windows SmartScreen shows a warning, click
More info->Run anyway.
Linux
- Download the
.debpackage for your architecture from GitHub Releases. - On Debian/Ubuntu, you can install it directly by double-clicking it, or by running:
sudo apt install ./Sage-<version>-<arch>.debIf you prefer to build the desktop app from source, use the commands below.
# macOS/Linux
app/desktop/scripts/build.sh release
# Windows
./app/desktop/scripts/build_windows.ps1 releaseCommand Line Interface (CLI):
python examples/sage_cli.py \
--default_llm_api_key YOUR_API_KEY \
--default_llm_api_base_url https://api.deepseek.com/v1 \
--default_llm_model_name deepseek-chatWeb Application (FastAPI + Vue3):
# Start backend
python -m app.server.main
# Start frontend (in another terminal)
cd app/server/web
npm install
npm run devgraph TD
User[User/Client] --> Desktop[💻 Desktop App]
User --> Web[🌐 Web UI]
Desktop --> API[Sage Server API]
Web --> API
subgraph Core[Core Engine]
API --> Orch[🧠 Agent Orchestrator]
Orch -- "Dispatch" --> Flow[📋 AgentFlow]
Flow -- "Execute" --> Agents["🤖 Agents<br/>Fibre / Simple / Multi"]
Agents -- "Use" --> RAG[📚 RAG Engine]
Agents -- "Use" --> Tools[🛠️ Tools & Skills]
Agents -- "Use" --> MCP[🔌 MCP Servers]
Agents -- "Run in" --> Box[📦 Security Sandbox]
end
subgraph Infra[Enterprise Infrastructure]
RAG <--> ES[(Elasticsearch)]
Tools <--> RustFS[(RustFS)]
Orch <--> DB[(SQL Database)]
end
Core -.-> Obs["👁️ Observability<br/>OpenTelemetry"]
Core -.-> Workbench["🛠️ Visual Workbench"]
- Session Management Refactor: Global
SessionManagerwith parent-child session tracking - AgentFlow Engine: Declarative workflow orchestration with Router → DeepThink → Mode Switch → Suggest flow
- Fibre Mode Optimization:
- Dynamic sub-agent spawning with
sys_spawn_agent - Parallel task delegation with
sys_delegate_task - Hour-level long-running task support
- 4-level hierarchy depth control
- Recursive orchestration capabilities
- Dynamic sub-agent spawning with
- Lock Management: Global
LockManagerfor session-level isolation - Observability: OpenTelemetry integration with performance monitoring
- Visual Workbench:
- 20+ rendering components
- 15+ file format support (PDF, DOCX, PPTX, XLSX, etc.)
- List/Single view dual mode
- Timeline navigation
- Session-isolated state management
- Cross-Platform Desktop:
- macOS (Intel/Apple Silicon) - DMG
- Windows - NSIS Installer
- Linux - DEB support
- Real-time Collaboration:
- Message stream optimization
- File reference extraction
- Code block highlighting
- Disconnect detection & resume
- MCP Support: Model Context Protocol for external tool integration
- Tauri 2.0: Upgraded to stable version with new permission system
- Build Optimization: Rust caching, parallel builds, auto-signing
- State Management: Pinia store with session isolation
- 📖 Full Documentation: https://wiki.sage.zavixai.com/
- 📝 Release Notes: release_notes/
- 🏗️ Architecture: See
sagents/directory for core framework - 🔧 Configuration: Environment variables and config files in
app/desktop/
Sage/
├── sagents/ # Core Agent Framework
│ ├── agent/ # Agent implementations
│ │ ├── fibre/ # Fibre multi-agent orchestration
│ │ ├── simple_agent.py # Simple mode agent
│ │ └── ...
│ ├── flow/ # AgentFlow engine
│ ├── context/ # Session & message management
│ ├── tool/ # Tool system
│ └── session_runtime.py # Session manager
├── app/desktop/ # Desktop Application
│ ├── core/ # Python backend (FastAPI)
│ ├── ui/ # Vue3 frontend
│ └── tauri/ # Tauri 2.0 desktop shell
└── skills/ # Built-in skills
We welcome contributions! Please see our GitHub Issues for tasks and discussions.
We are grateful to our sponsors for their support in making Sage better:
|
|
|
Built with ❤️ by the Sage Team 🦌