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. Getting Started for local setup and first run
2. Core Concepts for the runtime model
3. Architecture for repository and subsystem boundaries
4. Configuration for environment variables and deployment knobs

Common Reading Paths

I want to run Sage locally

Read:

1. Getting Started
2. Applications
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. Getting Started
2. Configuration
3. API Reference
4. HTTP API Reference

Documentation Map

• Getting Started: install dependencies and run the CLI, server, web UI, or desktop build
• Core Concepts: sessions, agents, tools, skills, flows, and sandboxing
• Architecture: how the codebase is organized
• Configuration: runtime environment variables and storage settings
• Applications: which app surface to use for which job
• MCP Servers: built-in MCP servers and how they fit into the platform
• API Reference: main HTTP route groups and streaming endpoints
• HTTP API Reference: current backend HTTP endpoints, request and response bodies, and curl examples
• 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

• examples/sage_cli.py: terminal chat client
• 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.