SDK — Build agents in Python

The Sagewai SDK is a Python library for adding AI agents to your product. This page introduces what you can build with pip install sagewai alone — agents, tool calls, memory, workflows, and model swap — and points you at the right next step depending on what you're shipping. It's for developers who want to wire an LLM into a Python codebase today.

Before you start

Python 3.10 or later
A working LLM API key (Anthropic, OpenAI, or a local model via Ollama / LM Studio)
Comfort with async/await (most agent calls are async)

Install

pip install sagewai

That's the whole baseline. The library runs without the admin server, without a worker fleet, and without any other Sagewai component. You can layer those on later when you need them.

What you get

The SDK exposes a small set of classes that compose. You can use any of them on their own.

Capability	Class / API	Use it for
Run an LLM	`Agent` (alias `UniversalAgent`)	Single-turn or multi-turn chat against any LLM via LiteLLM.
Call tools	`@agent.tool` decorator + MCP servers	Register Python tools, or attach an MCP-compliant tool server (Anthropic's open standard).
Remember things	`RAGEngine`, `VectorMemory`, `GraphMemory`	Vector recall, graph-structured memory, semantic-checkpoint retrieval.
Run multi-step jobs	`DurableWorkflow`	Compose agents into multi-step flows that survive process restarts.
Resolve dynamic prompts	Directives (`@datetime`, `@context`, `@memory`, `/tool.name`)	Inject context, memory hits, or tool output into a prompt at resolution time.
Run untrusted code	`Sandbox` API	Execute agent steps in an isolated container with scoped credentials.
Swap models	`model="..."` constructor arg	Same code targets Anthropic, OpenAI, Ollama, LM Studio, Modal, Vast.ai, and more.

Hello agent

The smallest useful program:

import asyncio
from sagewai import Agent

agent = Agent(name="hello", model="claude-3-5-sonnet-20241022")

async def main():
    reply = await agent.chat("Write a haiku about Python.")
    print(reply)

asyncio.run(main())

Set ANTHROPIC_API_KEY (or whichever provider matches model=) and run it. That's the SDK on its own — no server, no worker, no admin UI.

Where to go next

Learn the core building blocks

Quickstart — 60-second hello-world.
Getting started — the longer "build a portfolio site with Claude Code" tour.
Core concepts: Agents — Agent composition patterns.
Core concepts: Memory & RAG — the memory subsystem.
Core concepts: Workflows — DurableWorkflow and approval gates.
Core concepts: Directives — directive-library deep dive.
API reference: Agents — full agent API.

Runnable examples

The Foundation section walks through every SDK feature with a runnable script. The most common starting points:

02 — tool_agent — registering Python tools.
03 — multi_model, 13 — model_routing, 18 — local_llm_routing — swapping models.
04 — memory_agent — memory basics.
05 — workflow — multi-step workflows.
06 — guardrails — safety filters.
07 — mcp_tools — attaching an MCP server.
08 — directives — directive library.

For larger patterns:

See it under load

Moderation and classification — three HuggingFace classifiers running in an isolated sandbox container, judged by a small LLM, with audit on every call.
Memory and retrieval — semantic checkpoint recall (Example 37) and graph-vs-vector retrieval for incident response (Example 41).