Koa Adapter
Integrate Cogitator into your Koa application using the middleware-chain pattern with @koa/router.
The @cogitator-ai/koa package provides cogitatorApp, a factory function that returns a @koa/router instance with all Cogitator routes, middleware, and error handling pre-configured. It follows Koa's middleware-chain philosophy — body parsing, context injection, auth, and error handling are composed as middleware layers.
Installation
pnpm add @cogitator-ai/koa koa @koa/routerBasic Setup
import Koa from 'koa';
import { Cogitator, Agent, tool } from '@cogitator-ai/core';
import { cogitatorApp } from '@cogitator-ai/koa';
import { z } from 'zod';
const app = new Koa();
const cogitator = new Cogitator({
llm: {
defaultModel: 'openai/gpt-6.1-sol',
providers: {
openai: { apiKey: process.env.OPENAI_API_KEY! },
},
},
});
const translator = tool({
name: 'translate',
description: 'Translate text to a target language',
parameters: z.object({
text: z.string(),
targetLanguage: z.string(),
}),
execute: async ({ text, targetLanguage }) => ({
translated: `[${targetLanguage}] ${text}`,
}),
});
const agent = new Agent({
name: 'translator',
description: 'Translates text between languages',
model: 'openai/gpt-6.1-sol',
instructions: 'You translate text between languages. Use the translate tool.',
tools: [translator],
});
const cogitatorRouter = cogitatorApp({
cogitator,
agents: { translator: agent },
enableSwagger: true,
});
app.use(cogitatorRouter.routes());
app.listen(3000, () => {
console.log('Koa server running on http://localhost:3000');
console.log('Swagger UI: http://localhost:3000/docs');
});App Options
interface CogitatorAppOptions {
cogitator: Cogitator;
agents?: Record<string, Agent>;
workflows?: Record<string, Workflow>;
swarms?: Record<string, SwarmConfig>;
auth?: AuthFunction;
enableSwagger?: boolean;
swagger?: SwaggerConfig;
bodyLimit?: number; // max JSON body size in bytes, default 1 MiB
sseHeartbeatMs?: number; // SSE heartbeat interval in ms, default 5000, 0 turns it off
acceptContext?: boolean | string[]; // context keys clients may send: none by default, a list, or true for any
threadMessageRoles?: ('user' | 'assistant' | 'system')[]; // roles of POST /threads/:id/messages, default user and assistant
limits?: RunLimits; // { swarmTimeout?, workflowMaxIterations?, workflowMaxConcurrency? }, caps on swarm and workflow runs
anonymous?: 'allow' | 'deny'; // callers without a userId, default 'allow', 'deny' answers 401 UNAUTHORIZED
authorizeThread?: (auth, threadId) => boolean | Promise<boolean>; // false answers 403 THREAD_FORBIDDEN
deps?: (ctx) => unknown | Promise<unknown>; // the deps agent runs pass to their tools, never from the body
workflowCheckpoints?: CheckpointStore; // workflow checkpoints and /workflows/:name/resume, none by default
triggers?: TriggersHost; // experimental: the trigger manager, serves /triggers/:id/fire, /webhook and /inbox
}With triggers the router serves the trigger and inbox routes, the two trigger routes before auth, the JSON body parser and bodyLimit.
WebSocket support is attached to the HTTP server with setupWebSocket, not through router options.
The router answers OPTIONS for its own paths with 204 and the methods they serve in Allow, so it needs no router.allowedMethods(). A CORS middleware (such as @koa/cors) goes before the router, so it answers preflight requests itself.
Request Handling
- Bodies are validated before anything reaches the runtime:
inputmust contain more than whitespace (""and" "are refused before the model is called),contextan object,threadIda non-empty string, swarmtimeouta positive number of at mostMAX_RUN_TIMEOUT_MS(2147483647, the longest delay a timer can hold). Invalid bodies return400 INVALID_INPUT. - Workflow
optionsare limited tomaxConcurrency,maxIterations(positive integers) andcheckpoint(boolean), other options are dropped and wrongly typed ones return400 INVALID_INPUT. The body itself is optional.checkpoint: trueneedsworkflowCheckpoints, which also servesPOST /workflows/:name/resumeand/resume/stream, see Workflow checkpoints. - Thread messages accept the roles
user,assistantandsystem;metadatais stored with the entry. - Unknown agents, workflows and swarms return
404 NOT_FOUND; workflow and swarm routes return501 UNIMPLEMENTEDwhen@cogitator-ai/workflowsor@cogitator-ai/swarmsis not installed.GET /swarms/:name/blackboardreturns the configuredblackboard.sections, or400when the blackboard is disabled. - The thread routes use
cogitator.getMemory()and return503 UNAVAILABLEwithout memory; another user's thread returns403 THREAD_ACCESS_DENIED. GET /threads/:idanswers the whole thread, or a page of it with?limit=50: the newest 50 messages, oldest first within the page, and anextCursor. Send?limit=50&cursor=<nextCursor>for the 50 before them, until an answer has nonextCursor. Alimitoutside 1 to 1000 or a cursor the server did not give answers400 INVALID_INPUT.- Every error answer is the envelope
{ error: { message, code } }. ACogitatorErrorkeeps its message, HTTP status and code (for example429 LLM_RATE_LIMITED) and addsRetry-Afterin whole seconds when the provider said when to retry. A swarm that ran out of time answers504 RUN_TIMEOUT. Other errors with a 4xxstatuskeep it (413 PAYLOAD_TOO_LARGE, otherwise codeHTTP_ERROR), and everything else is logged and returned as500with the messageInternal server error, in JSON answers, streamerrorevents and WebSocket errors alike. A workflow that ends with an error is answered like the error itself. - Disconnecting clients abort the running agent, workflow or swarm. Agent streams can go on instead with
resumableStreams, see Resumable Streams. GET /agentsexposes each agent'sdescription, never itsinstructions;GET /toolsreturns parameters as JSON Schema.
Middleware Chain
The returned router applies middleware in this order:
- Error handler, catches errors and returns structured JSON responses
- Body parser, parses JSON request bodies up to
bodyLimit(413above it) and reuses a body already parsed by upstream middleware such askoa-bodyparser - Context middleware, injects
CogitatorStateintoctx.state - Auth middleware, optional, runs your auth function
- Public routes: health and ready, and with
enableSwaggerthe/openapi.jsonand/docsroutes, generated per request by the shared@cogitator-ai/server-sharedgenerator - Anonymous policy: with
anonymous: 'deny', answers401to callers without auserId - API routes: agents, threads, tools, workflows, swarms
- Unmatched paths: a request no route of the router serves skips steps 1 to 4 and 6 and goes on to the middleware after the router, so other routers and middleware get it as it came. What none of them answers goes through auth and the anonymous policy and gets
404 NOT_FOUNDin the error envelope,401underanonymous: 'deny'for a caller without auserId. A method a path does not take is answered the same way. Mounted under a prefix, the router only answers paths under it
Authentication
The auth function receives a Koa Context and returns an AuthContext. Throwing rejects the request with 401 UNAUTHORIZED (errors with a status >= 500 are treated as server errors instead); returning undefined lets the request through anonymously.
const cogitatorRouter = cogitatorApp({
cogitator,
agents: { translator: agent },
auth: async (ctx) => {
const token = ctx.headers.authorization?.replace('Bearer ', '');
if (!token) throw new Error('Missing token');
const user = await verifyToken(token);
return { userId: user.id, roles: user.roles, permissions: user.permissions };
},
});The auth result is stored in ctx.state.auth for use in downstream middleware, and its userId reaches agent and swarm runs and scopes the thread routes. Auth runs on every Cogitator route, including /health and /ready. Errors thrown by routes after a successful auth check are handled by the error handler, never reported as 401.
Anonymous callers
With anonymous: 'deny' a caller without a userId gets 401 UNAUTHORIZED on every API route, and on every path under the router that nothing answers, so an anonymous caller cannot tell which paths exist. /health, /ready, /openapi.json and /docs stay open. The default, 'allow', lets such callers in as before, and answers a path nothing serves with 404 NOT_FOUND in the error envelope. WebSocket connections take the anonymous option of setupWebSocket, or the anonymous of its route context when the option is not set.
Thread authorization
Core lets a caller touch only the threads they own. authorizeThread adds a rule of your own on top, a tenant check for example:
const cogitatorRouter = cogitatorApp({
cogitator,
agents: { translator: agent },
auth,
authorizeThread: (auth, threadId) => tenants.ownsThread(auth?.metadata?.tenant, threadId),
});It gets what auth returned and the thread a request names: the body threadId of agent runs, streams and resumes and of swarm runs and streams, and the :id of GET, DELETE and POST /threads/:id/messages. It runs after the body is validated and before the owner check. false answers 403 THREAD_FORBIDDEN, and no run starts. For WebSocket runs, put authorizeThread in the route context of setupWebSocket.
Run deps
deps builds what an agent's tools read as context.deps for a request, such as a database handle or the tenant. The model never sees them, and they never come from the body.
const cogitatorRouter = cogitatorApp({
cogitator,
agents: { translator: agent },
deps: async (ctx) => ({ db: await pool.connect(), tenant: ctx.get('x-tenant') }),
});Agent runs, streams and resumes call it once per run. WebSocket runs take the deps option of setupWebSocket, which gets the upgrade request.
Run Limits
limits caps what a request may ask a run for. A request that asks for more is held to the cap, and one that asks for nothing gets it, over HTTP and SSE:
const cogitatorRouter = cogitatorApp({
cogitator,
swarms: { research },
workflows: { pipeline },
limits: {
swarmTimeout: 120_000, // ms
workflowMaxIterations: 50,
workflowMaxConcurrency: 4,
},
});Each limit must be a positive integer, or cogitatorApp throws. The OpenAPI spec shows each limit as the default of its request field. WebSocket runs take the limits of the route context given to setupWebSocket.
Mounting Under a Prefix
Use @koa/router's prefix feature to nest the Cogitator routes:
import Router from '@koa/router';
const root = new Router();
root.get('/', (ctx) => {
ctx.body = { message: 'Welcome' };
});
const cogitatorRouter = cogitatorApp({
cogitator,
agents: { translator: agent },
enableSwagger: true,
});
const prefixed = new Router({ prefix: '/api/v1' });
prefixed.use(cogitatorRouter.routes());
app.use(root.routes());
app.use(prefixed.routes());All Cogitator routes are now under /api/v1/agents/..., /api/v1/docs, etc.
Streaming
The KoaStreamWriter manages SSE responses through Koa's raw ctx.res object:
const response = await fetch('http://localhost:3000/agents/translator/stream', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
input: 'Translate "good morning" to Japanese, French, and Spanish.',
}),
});
const reader = response.body!.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
process.stdout.write(decoder.decode(value));
}WebSocket
WebSocket support requires the ws package. After creating your Koa app, call setupWebSocket with the HTTP server, the route context and the WebSocket options:
import { createServer } from 'http';
import { setupWebSocket } from '@cogitator-ai/koa';
const httpServer = createServer(app.callback());
await setupWebSocket(
httpServer,
{
runtime: cogitator,
agents: { translator: agent },
workflows: {},
swarms: {},
limits: { swarmTimeout: 120_000 },
authorizeThread: (auth, threadId) => tenants.ownsThread(auth?.metadata?.tenant, threadId),
},
{
path: '/ws',
pingInterval: 30_000,
pingTimeout: 10_000,
maxPayloadSize: 1024 * 1024,
auth: (req) => {
if (req.headers.authorization !== `Bearer ${process.env.API_TOKEN}`) {
throw new Error('Unauthorized');
}
return { userId: 'api' };
},
anonymous: 'deny',
deps: (req) => ({ tenant: req.headers['x-tenant'] }),
}
);
httpServer.listen(3000);The second argument is a RouteContext, { runtime, agents, workflows, swarms, limits?, authorizeThread?, anonymous?, deps? }, independent of the router. WebSocket runs and resumes follow its limits and authorizeThread, and the handshake its anonymous unless the anonymous option is set, which wins. Its deps builds the deps of HTTP runs from a Koa Context, which an upgrade request does not have, so setupWebSocket ignores it and takes the deps option instead. The router's prefix does not apply to path, which is matched against the full request path. pingInterval (default 30 s) and pingTimeout (default pingInterval) drop clients that stop answering pings, and maxPayloadSize defaults to 1 MiB. setupWebSocket resolves to the WebSocketServer, or null when ws is not installed.
The router's auth option does not apply to WebSocket connections. The auth option of setupWebSocket receives the upgrade request and rejects the handshake with 401 when it throws (500 when the error carries a status of 500 or more). With anonymous: 'deny', set here or on the route context, a connection without a userId is refused with 401 as well. deps builds the deps of each agent run on the connection from its upgrade request, called for each run. Upgrades on other paths are left to other upgrade listeners, or rejected with 404 when there are none.
Clients send:
runwithpayload: { type: 'agent' | 'workflow' | 'swarm', name, input, context?, threadId? }— a workflow gets{ input }as its input state;resumewithpayload: { name, threadId, decisions?, defaultDecision? }to continue an agent run paused for approval;stopto abort the active run, andping.
The server answers with event frames (token, reasoning, tool-call, tool-result for agents, then complete with the result or cancelled), error frames ({ type: 'error', id, error }, also for a thread authorizeThread refused) and pong. Workflow and swarm runs over the socket are held to the limits of the route context. Each connection runs one thing at a time: a second run or resume answers A run is already in progress. There are no subscribe channels. Closing the connection aborts its active run.
State Type
The router is typed with CogitatorState, which provides full type safety in custom middleware:
import type { CogitatorState } from '@cogitator-ai/koa';
import Router from '@koa/router';
const custom = new Router<CogitatorState>();
custom.get('/custom', async (ctx) => {
const { cogitator: routeCtx } = ctx.state;
const { agents, workflows, swarms } = routeCtx;
ctx.body = { agentCount: Object.keys(agents).length };
});Exported Utilities
import {
cogitatorApp,
createContextMiddleware,
createAuthMiddleware,
createAnonymousMiddleware,
createBodyParser,
createErrorHandler,
createHealthRoutes,
createAgentRoutes,
createThreadRoutes,
createToolRoutes,
createWorkflowRoutes,
createSwarmRoutes,
createSwaggerRoutes,
KoaStreamWriter,
setupSSEHeaders,
setupWebSocket,
} from '@cogitator-ai/koa';Each create*Routes() function returns a @koa/router instance that you can mount individually.
Hono Adapter
Deploy Cogitator agents to any JavaScript runtime — Node.js, Bun, Deno, and Cloudflare Workers — using the lightweight Hono adapter.
Tetsu Adapter
Serve Cogitator agents, threads, workflows and swarms from a Tetsu application on Bun — one controller with validated requests, SSE, WebSocket and an OpenAPI document.