Assistant (Kitt)
Assistant (Kitt)
Section titled “Assistant (Kitt)”Kitt is the toolkit’s zero-dependency, provider-agnostic assistant, built on
the OpenAI-compatible protocol (it works with DashScope, OpenAI and any
compatible endpoint). It uses native fetch, so no SDK is required, and every
fallible call returns a Safe Result that never throws.
Three levels, pick the one you need:
- One-shot chat —
useChat()answers a single conversation turn. - Tool-calling agent —
useRunAgent()runs an autonomous loop that can read, write and execute through the tools you hand it. - Session-aware bots —
useInitAssistant()+useReply()add sessions over the REST channel (below).
When to use Kitt — and when not
Section titled “When to use Kitt — and when not”Kitt stays small (zero dependencies) because it does one thing well: chat completions with tool calls against any OpenAI-compatible endpoint.
| Need | Use instead |
|---|---|
| Streaming token-by-token | Vercel AI SDK |
| RAG with embeddings | LangChain.js |
| Multi-agent orchestration | CrewAI |
| Full chatbot framework | Botpress |
1. Configure the provider
Section titled “1. Configure the provider”import { useInitAgent } from "katanakit-js";
// Register once. apiKey falls back to process.env.DASHSCOPE_API_KEY.useInitAgent({ model: "qwen3.8-max" });The Kitt preset is exported as sensible defaults: KITT_SYSTEM_PROMPT,
kittPreset, KITT_BASE_URL and KITT_DEFAULT_MODEL (qwen3.8-max).
Override any of them per call: useInitAgent({ systemPrompt, model, baseUrl }).
2. One-shot chat
Section titled “2. One-shot chat”import { useChat } from "katanakit-js";
const review = await useChat([ { role: "user", content: "Summarize the benefits of solar energy in three bullet points.", },]);if (review.ok) console.log(review.data);3. Tool-calling agent
Section titled “3. Tool-calling agent”Each tool is { name, description, parameters (JSON Schema), execute(input) }.
The agent loops until it answers or maxSteps is reached:
import { useRunAgent } from "katanakit-js";import fs from "node:fs/promises";
const result = await useRunAgent("Fix the type errors in src/", { tools: [ { name: "readFile", description: "Returns file contents", parameters: { type: "object", properties: { path: { type: "string" } } }, execute: ({ path }) => fs.readFile(path, "utf8"), }, ], maxSteps: 12,});4. Sessions
Section titled “4. Sessions”import { useInitAssistant, useReply } from "katanakit-js";
useInitAssistant({ // apiKey — process.env.DASHSCOPE_API_KEY // baseUrl — KITT_BASE_URL // model — "qwen3.8-max" // systemPrompt — KITT_SYSTEM_PROMPT // store — in-memory (useCreateMemoryStore) // tools — AiTool[] // maxSteps — number});
const result = await useReply(undefined, "What are your hours?");if (result.ok) { console.log(result.data.reply, result.data.sessionId);} else { console.error(result.error.message);}useReply(sessionId | undefined, text) creates a session when sessionId is
omitted; pass result.data.sessionId on later turns. Also on the main barrel:
| Helper | Signature |
|---|---|
useCreateSession |
(channel?) => Promise<string> |
useGetHistory |
(sessionId) => Promise<AiMessage[]> |
useResetSession |
(sessionId) => Promise<void> |
useCreateMemoryStore |
() => ConversationStore |
5. REST channel
Section titled “5. REST channel”katanakit-js/adapters/assistant mounts on Express, so it declares express
(>=5), cors (>=2.8) and express-rate-limit (>=8) as optional peer
dependencies. Install the ones you use — the assistant itself needs none of
them for the in-process helpers above.
import { useStartAssistant, useCreateAssistantRouter,} from "katanakit-js/adapters/assistant";
useStartAssistant(); // port?, host?, mountPath = "/assistant", options?// or mount useCreateAssistantRouter() on an existing Express app| Method | Path | Body | Response |
|---|---|---|---|
POST |
/assistant/chat |
{ sessionId?, message } |
{ ok, data: { reply, sessionId }, error } |
GET |
/assistant/sessions/:id |
— | { sessionId, messages } or 404 |
DELETE |
/assistant/sessions/:id |
— | 204 or 404 |
The endpoints are public by default. In production, pass an auth guard
(applied to every route). Unknown session ids return 404, and useReply
rejects a sessionId that does not exist.
useStartAssistant(3000, "localhost", "/assistant", { guard: (req, res, next) => req.header("authorization") === `Bearer ${process.env.ASSISTANT_API_KEY}` ? next() : res.status(401).end(),});curl -X POST http://localhost:3000/assistant/chat \ -H 'Content-Type: application/json' \ -d '{"message":"What are your hours?"}'POST /chat is rate-limited by default (20 req/min per IP). Override through the router options:
app.use( "/assistant", useCreateAssistantRouter({ rateLimit: rateLimit({ windowMs: 60_000, max: 30 }), }),);6. Persistence
Section titled “6. Persistence”Memory by default (useCreateMemoryStore()); history is lost on process
restart. For a database, install the optional Prisma peer — it is not part of
the core package:
bun add @prisma/orm-postgresWith DATABASE_URL set (Bun reads .env; on Node run node --env-file=.env),
use Prisma — the Conversation and Message models ship in
dist/prisma/schema.prisma (source: src/prisma/schema.prisma):
import { useInitAssistant } from "katanakit-js";import { useCreatePrismaStore, PrismaConversationStore,} from "katanakit-js/prisma";
useInitAssistant({ store: useCreatePrismaStore() });// or: { store: PrismaConversationStore }If your app owns the database, copy that schema into your project, then run
prisma contract emit and prisma db init there.
Drizzle instead of Prisma
Section titled “Drizzle instead of Prisma”The Drizzle adapter ships the same conversations and messages tables for
drizzle-orm + pg:
bun add drizzle-orm pgimport { useInitAssistant } from "katanakit-js";import { useCreateDrizzleStore, DrizzleConversationStore,} from "katanakit-js/adapters/drizzle";
useInitAssistant({ store: useCreateDrizzleStore() });// or: { store: DrizzleConversationStore }Push the tables with drizzle-kit
(drizzle-kit push) or generate migrations from
src/adapters/drizzle/schema.ts.
7. Try it in this repo
Section titled “7. Try it in this repo”examples/assistant/
is a generic digital assistant with two demo tools: readFile on
knowledge-base.md and saveNote to notes.jsonl. Copy .env keys from
.env.example:
DASHSCOPE_API_KEY=PORT=3000KITT_CHANNEL=restDATABASE_URL=KITT_CHANNEL=rest bun run examples/assistant/demo.ts# POST http://localhost:3000/assistant/chat { "message": "What are your hours?" }Swap the system prompt, the knowledge base and the tool execute() functions
for your product FAQ, CRM or ticket system — keep the
{ name, description, parameters, execute } shape.
Related
Section titled “Related”- Express Server — the reference server the REST channel mounts on.