A TypeScript framework for reliable AI agents with full transparency and control. Inspired by the Finnish concept of sisu calm determination under pressure.
No surprises. Explicit middleware, typed tools, deterministic control flow. Full control. Compose planning, routing, and safety like Express apps. Total visibility. Built-in tracing, logging, and debugging out of the box. Provider-agnostic. OpenAI, Anthropic, Ollama, or bring your own.
pnpm add @sisu-ai/core @sisu-ai/adapter-openai \
@sisu-ai/mw-register-tools \
@sisu-ai/mw-conversation-buffer @sisu-ai/mw-trace-viewer \
@sisu-ai/mw-error-boundary zod dotenvimport "dotenv/config";
import { Agent, createCtx, execute, getExecutionResult, type Tool } from "@sisu-ai/core";
import { registerTools } from "@sisu-ai/mw-register-tools";
import { inputToMessage, conversationBuffer } from "@sisu-ai/mw-conversation-buffer";
import { errorBoundary } from "@sisu-ai/mw-error-boundary";
import { openAIAdapter } from "@sisu-ai/adapter-openai";
import { traceViewer } from "@sisu-ai/mw-trace-viewer";
import { z } from "zod";
const weather: Tool<{ city: string }> = {
name: "getWeather",
description: "Get weather for a city",
schema: z.object({ city: z.string() }),
handler: async ({ city }) => ({ city, tempC: 21, summary: "Sunny" }),
};
const ctx = createCtx({
model: openAIAdapter({ model: "gpt-5.4" }),
input: "What is the weather in Stockholm?",
systemPrompt: "You are a helpful assistant.",
});
const app = new Agent()
.use(errorBoundary())
.use(traceViewer())
.use(registerTools([weather]))
.use(inputToMessage)
.use(conversationBuffer({ window: 8 }))
.use(execute);
await app.handler()(ctx);
console.log(getExecutionResult(ctx)?.text);Open traces/viewer.html to see exactly what happened.
| You're dealing with... | Sisu gives you... |
|---|---|
| "Where did my tokens go?" | A trace viewer showing every token, cost, and decision |
| "The tool loop broke and I can't debug it" | Explicit control flow you can read, test, and step through |
| "Can't swap providers without rewriting" | Provider-agnostic adapters — change one line |
| "Secrets keep leaking into my logs" | Automatic redaction of API keys and sensitive data |
| "Production bugs are impossible to trace" | Structured logging and HTML traces for every run |
Every run auto-generates an interactive HTML trace: token usage and costs, tool calls with timing, full conversation history, and error details when things break.
Structured, color-coded terminal output. No more parsing walls of JSON.
Compose your agent pipeline like an Express app. Each middleware does one thing well.
const app = new Agent()
.use(errorBoundary())
.use(traceViewer())
.use(registerTools([...]))
.use(inputToMessage)
.use(execute);Everything flows through a single typed ctx. No hidden state, no side channels.
(ctx, next) => {
ctx.messages.push(...) // Modify state
await next() // Pass to next middleware
console.log(ctx.result) // React to changes
}Zod schemas validate tool inputs automatically. Define once, use safely everywhere.
const tool: Tool = {
name: "searchDocs",
schema: z.object({ query: z.string() }),
handler: async ({ query }) => { /* ... */ },
};Sequence, branch, loop, run in parallel, or define a DAG. Readable, testable, no hidden behavior.
import { sequence, branch, parallel, graph } from '@sisu-ai/mw-control-flow';
.use(sequence([
classifyIntent,
branch({
'search': searchPipeline,
'chat': conversationPipeline
})
]))const model = openAIAdapter({ model: "gpt-5.4" });
// const model = anthropicAdapter({ model: 'claude-sonnet-4' });
// const model = ollamaAdapter({ model: 'gemma4:e4b' });The OpenAI adapter works with any compatible API (LM Studio, vLLM, OpenRouter):
const model = openAIAdapter({
model: "gpt-5.4",
baseUrl: "http://localhost:1234/v1",
});| Provider | Package | Tools | Streaming | Vision |
|---|---|---|---|---|
| OpenAI | @sisu-ai/adapter-openai |
✓ | ✓ | ✓ |
| Anthropic | @sisu-ai/adapter-anthropic |
✓ | ✓ | ✓ |
| Ollama | @sisu-ai/adapter-ollama |
✓ | ✓ | ✓ |
| Category | Packages |
|---|---|
| Control Flow | sequence · branch · parallel · graph |
| Tool Management | registerTools · core execute / executeStream |
| Conversation | conversationBuffer · contextCompressor |
| Safety | errorBoundary · guardrails · invariants |
| Observability | traceViewer · usageTracker |
| Advanced | rag · reactParser · skills · orchestration |
| Category | Packages |
|---|---|
| Web | webFetch · webSearch · wikipedia |
| Cloud | awsS3 · azureBlob |
| Dev | terminal · githubProjects |
| Data | ragTools · extractUrls · summarizeText |
| Category | Packages |
|---|---|
| RAG & Vector | ragCore · vectorCore · vectorChromaAdapter · vectorVectraAdapter |
Sisu keeps RAG split into small layers:
@sisu-ai/vector-coredefines theVectorStorecontract@sisu-ai/vector-chromaimplements that contract for Chroma@sisu-ai/vector-vectraimplements that contract for local file-backed Vectra indexes@sisu-ai/rag-corehandles chunking, record prep, and direct store/retrieve helpers@sisu-ai/tool-ragexposes model-facing retrieval/storage tools@sisu-ai/mw-ragsupports deterministic middleware-driven RAG flows
That keeps backend code, reusable mechanics, tool-calling, and middleware composition separate.
# OpenAI
cp examples/openai-hello/.env.example examples/openai-hello/.env
pnpm run ex:openai:hello
open examples/openai-hello/traces/trace.html
# OpenAI orchestration
pnpm run ex:openai:orchestration
pnpm run ex:openai:orchestration-adaptive
pnpm run ex:openai:orchestration-custom
pnpm run ex:openai:orchestration-remote
# Ollama (local, no API key needed)
ollama serve && ollama pull gemma4:e4b
pnpm run ex:ollama:hello
# Desktop macOS app (starts local runtime + SwiftUI app)
pnpm run ex:desktop:macos25+ examples covering streaming, vision, RAG, control flow, orchestration, guardrails, and more in /examples.
Agent skill users can install the Sisu reference bundle with:
npx @sisu-ai/skill-installFramework users can also inspect maintained packages and scaffold starters with:
npx @sisu-ai/cli list tools
npx @sisu-ai/cli info mw-rag
npx @sisu-ai/cli create chat-agent my-app
npx @sisu-ai/cli install skill# LLM Providers
API_KEY=sk-...
BASE_URL=http://localhost:11434 # optional, when overriding provider defaults
MODEL=gpt-5.4 # optional, example/provider dependent
# Logging
LOG_LEVEL=info # debug | info | warn | error
DEBUG_LLM=1 # log adapter requests on errors
# Tracing
TRACE_HTML=1 # auto-generate HTML traces
TRACE_JSON=1 # auto-generate JSON traces
TRACE_STYLE=dark # light | darkpnpm install # install dependencies
pnpm build # build all packages (Turbo-cached)
pnpm test # run all tests
pnpm test:coverage # run with coverage (target ≥80%)
pnpm dev # watch mode
pnpm lint:fix # fix lint issues
pnpm typecheck # type check all packagesBuilt with Turbo, pnpm workspaces, Vitest, and Changesets.
Core — Package docs · Error types
Adapters — OpenAI · Anthropic · Ollama
All middleware packages
- @sisu-ai/mw-agent-run-api
- @sisu-ai/mw-context-compressor
- @sisu-ai/mw-control-flow
- @sisu-ai/mw-conversation-buffer
- @sisu-ai/mw-cors
- @sisu-ai/mw-error-boundary
- @sisu-ai/mw-guardrails
- @sisu-ai/mw-invariants
- @sisu-ai/mw-orchestration
- @sisu-ai/mw-rag
- @sisu-ai/mw-react-parser
- @sisu-ai/mw-register-tools
- @sisu-ai/mw-tool-calling (legacy compatibility)
- @sisu-ai/mw-trace-viewer
- @sisu-ai/mw-usage-tracker
All tool packages
- @sisu-ai/tool-aws-s3
- @sisu-ai/tool-azure-blob
- @sisu-ai/tool-extract-urls
- @sisu-ai/tool-github-projects
- @sisu-ai/tool-rag
- @sisu-ai/tool-summarize-text
- @sisu-ai/tool-terminal
- @sisu-ai/tool-web-fetch
- @sisu-ai/tool-web-search-duckduckgo
- @sisu-ai/tool-web-search-google
- @sisu-ai/tool-web-search-linkup
- @sisu-ai/tool-web-search-openai
- @sisu-ai/tool-wikipedia
RAG packages
All skill packages
CLI packages
Vector packages
All examples
Anthropic — hello · control-flow · stream · vision · weather · linkup-web-search
Ollama — hello · stream · vision · weather · web-search · linkup-web-search
OpenAI — hello · weather · stream · vision · reasoning · react · control-flow · branch · parallel · graph · orchestration · orchestration-adaptive · orchestration-custom-executor · orchestration-remote-executor · guardrails · error-handling · rag-chroma · rag-vectra · web-search · linkup-web-search · web-fetch · wikipedia · terminal · github-projects · server · aws-s3 · azure-blob
We build Sisu in the open. Contributions welcome.
Contributing Guide · Report a Bug · Request a Feature · Code of Conduct
Star on GitHub if Sisu helps you build better agents.
Quiet, determined, relentlessly useful.