Installation

Install the Sagewai SDK into an isolated environment and verify it works before writing your first agent.

Install the SDK

The fastest, most reliable way is uv — it creates the environment and installs in one step, and sidesteps the system-Python restrictions below:

uv venv && uv pip install sagewai
uv run sagewai --version

Using pip

A bare pip install is blocked on macOS/Homebrew and many Linux distros with error: externally-managed-environment (PEP 668). Create a virtualenv first:

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install sagewai
sagewai --version

If pip still errors inside an activated venv, your shell is resolving an old pip from its cache — run python -m pip install sagewai, or use the uv path above.

The only hard requirement is Python 3.10+. See Prerequisites for the full list of software and hardware requirements.

What a base install includes

pip install sagewai gives you four surfaces with no extras:

  • SDK — from sagewai.engines.universal import UniversalAgent; build agents in Python.
  • CLI — sagewai --help, sagewai doctor, sagewai init.
  • Admin API — sagewai admin serve --port 8000 starts the FastAPI control plane; interactive API docs at http://localhost:8000/docs.
  • Admin UI — the web panel is a separate container image, not part of the pip package. Run the full stack with docker compose up (UI on http://localhost:3008), or just dev-all from a source checkout.

Extras

The base install already bundles the admin API server (FastAPI + uvicorn) and the connection protocols. Add extras for optional capabilities:

ExtraWhat it adds
sagewai[memory]Milvus + NebulaGraph + Docling vector/graph memory
sagewai[intelligence]Local embeddings, entity extraction, language detection
sagewai[postgres]Durable workflow storage backed by PostgreSQL
sagewai[storage]S3 / GCS archival backends
sagewai[all]Everything above

By default Sagewai persists all state to SQLite at ~/.sagewai/db/sagewai.db — zero setup, durable across restarts. Set SAGEWAI_DATABASE_URL=postgresql://… for production scale (the sagewai[postgres] extra adds asyncpg and Alembic).

Released vs. pre-release versions

  • Stable (recommended): pip install sagewai installs the latest release from PyPI. pip never selects a pre-release/dev build unless you ask for it explicitly.

  • Release candidates are published to TestPyPI:

    pip install --index-url https://test.pypi.org/simple/ \
            --extra-index-url https://pypi.org/simple \
            "sagewai==X.Y.ZrcN"
# with uv, add: --index-strategy unsafe-best-match

    The --extra-index-url pulls Sagewai's dependencies from real PyPI while the package itself comes from TestPyPI.

Install from source

git clone https://github.com/sagewai/platform
cd platform
just bootstrap        # uv + pnpm + workspace sync (first-time setup)
just dev-all          # run the backend API + admin UI together

Just the SDK, editable, inside an activated venv: uv pip install -e packages/sdk.

Verify the install

sagewai --version                                        # CLI works
python -c "import sagewai; print(sagewai.__version__)"   # SDK imports

No API key is required for either check.

Next