Getting Started
Getting Started
Install @maniac-ai/agents, run your first agent, and choose between one-shot runs and the Maniac app pattern.
@maniac-ai/agents is the TypeScript Maniac agents SDK — a port of the Python SDK with native model adapters, toolsets, durable memory, streaming, and background tasks.
This section walks through installation, a minimal runAgent quickstart, the long-lived Maniac app pattern for multi-turn chat, and the bundled terminal-chat example.
What you need
- Node.js ≥ 22.5 (required by the package
enginesfield; SQLite memory needsnode:sqlite, unflagged from Node 23.5+) - ESM — the package is
"type": "module"with no CommonJSrequireentry - A provider API key for live models (
OPENAI_API_KEY,OPENROUTER_API_KEY, orAI_GATEWAY_API_KEYdepending on adapter)
Two entry points
| Pattern | When to use |
|---|---|
runAgent | Single-turn scripts, tests, and stateless calls |
Maniac | Multi-turn chat, persistent threads, memory tiers, background tasks |
Both accept the same Agent spec shape. The Maniac class registers agents once and routes chat / chatStream through a ConversationStore.
Next steps
- Install — npm, ESM, and Node version requirements
- Quickstart —
runAgentwithStaticModeland a custom tool - Maniac app — register agents and call
chat - Terminal chat — streaming multi-turn CLI example