Language

English 简体中文

Sage Documentation

This site documents the current repository as it exists today. It is organized around the real entry points in examples/, app/server/, app/desktop/, sagents/, and mcp_servers/.

Who This Is For

• Users who want to run Sage locally
• Contributors who need to understand the runtime and application layout
• Integrators extending Sage through tools, skills, APIs, or MCP servers

Start Here

1. Applications for getting started, Web (incl. Docker), Desktop, CLI, TUI, and Chrome extension
2. Core Concepts for the runtime model
3. Architecture for repository and subsystem boundaries
4. Configuration for environment variables and deployment knobs
5. API documentation for HTTP and runtime interfaces

Common Reading Paths

I want to run Sage locally

Read:

1. Applications
2. Configuration
3. Troubleshooting

I want to extend the runtime

Read:

1. Core Concepts
2. Architecture
3. MCP Servers
4. Development

I want to integrate with the server

Read:

1. Applications
2. Configuration
3. API documentation (includes HTTP API Reference and the legacy Python notes)
4. OAuth2 Lage Integration Guide

Documentation Map

• Applications: getting started, Web, Desktop, CLI, TUI, Chrome extension
  • Getting Started
  • Web Application (manual stack + Docker Compose)
  • Desktop
  • CLI Guide · TUI Guide
  • Chrome extension
• Core Concepts: sessions, agents, tools, skills, flows, and sandboxing
• Architecture: how the codebase is organized (with sub-chapters)
  • App layer: Server · Desktop · Other entries
  • sagents core: Overview · Agent / Flow · Session / Context · Tool / Skill · Sandbox / LLM / Obs
• Configuration: runtime environment variables and storage settings
• MCP Servers: built-in MCP servers and how they fit into the platform
• API documentation: navigation hub for HTTP vs legacy Python API
  • HTTP API Reference: backend endpoints aligned with register_routes; the sidebar lists subpages
    • Subpages: Auth and users · Chat and streaming · Agent extras · Knowledge base (RAG) · Tools, skills, and MCP · Planner /tasks · Platform and observability
  • Python runtime API: SAgent and related types aligned with sagents/, not the main HTTP app
• Knowledge Base Guide: knowledge base module architecture, ingestion, retrieval, and Agent integration
• Memory: memory, retrieval, and memory-search workstream
• Solution Playbooks: presales documents for concrete business scenarios
• OAuth2 Lage Integration Guide: restored OAuth2 integration guide from historical docs
• Development: contributor workflow and source locations
• Troubleshooting: common startup and environment issues

Current Product Surfaces

Lightweight examples

• sage run / sage chat / sage doctor: development CLI entry points
• examples/sage_demo.py: Streamlit demo
• examples/sage_server.py: standalone FastAPI example service

Main application server

• app/server/main.py: primary FastAPI application entry point
• app/server/web/: Vue 3 + Vite web client

Use this path when you want the full product surface instead of a demo.

Desktop app

• app/desktop/entry.py: desktop bootstrap entry
• app/desktop/core/main.py: desktop-local FastAPI backend
• app/desktop/ui/: desktop UI

Use this path when you need the packaged desktop experience rather than the browser-based app.

Core runtime

• sagents/sagents.py: SAgent streaming runtime entry
• sagents/agent/: agent implementations
• sagents/tool/: tool system and MCP proxy support
• sagents/skill/: skill loading and execution
• sagents/utils/sandbox/: sandbox abstractions and providers

Documentation Principles

• This documentation prefers current source accuracy over historical completeness.
• Historical migration notes and duplicate site pages have been removed from the primary doc set.
• The root repository README.md remains the marketing and project overview document; this site is the technical source of truth.