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-tool-calling \
@sisu-ai/mw-conversation-buffer @sisu-ai/mw-trace-viewer \
@sisu-ai/mw-error-boundary zod dotenvimport "dotenv/config";
import { Agent, createCtx, 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 { toolCalling } from "@sisu-ai/mw-tool-calling";
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-4o-mini" }),
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(toolCalling);
await app.handler()(ctx);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(toolCalling);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-4o-mini" });
// const model = anthropicAdapter({ model: 'claude-sonnet-4' });
// const model = ollamaAdapter({ model: 'llama3.1' });The OpenAI adapter works with any compatible API (LM Studio, vLLM, OpenRouter):
const model = openAIAdapter({
model: "gpt-4o-mini",
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 · toolCalling |
| 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 | vectorChroma · extractUrls · summarizeText |
# 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
# Ollama (local, no API key needed)
ollama serve && ollama pull llama3.1
pnpm run ex:ollama:hello25+ examples covering streaming, vision, RAG, control flow, orchestration, guardrails, and more in /examples.
# LLM Providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434 # default
# 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
- @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-summarize-text
- @sisu-ai/tool-terminal
- @sisu-ai/tool-vec-chroma
- @sisu-ai/tool-web-fetch
- @sisu-ai/tool-web-search-duckduckgo
- @sisu-ai/tool-web-search-google
- @sisu-ai/tool-web-search-openai
- @sisu-ai/tool-wikipedia
All examples
Anthropic — hello · control-flow · stream · weather
Ollama — hello · stream · vision · weather · web-search
OpenAI — hello · weather · stream · vision · reasoning · react · control-flow · branch · parallel · graph · orchestration · orchestration-adaptive · guardrails · error-handling · rag-chroma · 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.

