Expose your Cogitator agents, workflows, and swarms as REST APIs with built-in streaming, WebSocket, and OpenAPI support.

Cogitator ships four server adapters that turn your agent runtime into a production-ready HTTP API. Every adapter provides the same set of endpoints, streaming protocol, and OpenAPI generation — pick the one that matches your stack.

Available Adapters

Package	Framework	Min Version	Style
`@cogitator-ai/express`	Express	4.18+	Class-based `CogitatorServer`
`@cogitator-ai/fastify`	Fastify	5.x	Plugin `cogitatorPlugin`
`@cogitator-ai/hono`	Hono	4.x	Factory `cogitatorApp`
`@cogitator-ai/koa`	Koa	2.15+	Factory `cogitatorApp`

Common Endpoints

All adapters register the same route structure under a configurable base path (default: /cogitator):

Method	Path	Description
`GET`	`/health`	Health check
`GET`	`/ready`	Readiness probe
`GET`	`/agents`	List registered agents
`POST`	`/agents/:name/run`	Run an agent (JSON response)
`POST`	`/agents/:name/stream`	Run an agent (SSE stream)
`GET`	`/threads/:id`	Get thread messages
`POST`	`/threads/:id/messages`	Add a message to a thread
`DELETE`	`/threads/:id`	Delete a thread
`GET`	`/tools`	List all registered tools
`GET`	`/workflows`	List workflows
`POST`	`/workflows/:name/run`	Execute a workflow
`POST`	`/workflows/:name/stream`	Stream workflow execution
`GET`	`/swarms`	List swarms
`POST`	`/swarms/:name/run`	Execute a swarm
`POST`	`/swarms/:name/stream`	Stream swarm execution
`GET`	`/swarms/:name/blackboard`	Get swarm blackboard state
`GET`	`/openapi.json`	OpenAPI 3.0 spec
`GET`	`/docs`	Swagger UI

Streaming Protocol

Every adapter implements the same SSE streaming protocol. Events are sent as text/event-stream with the following event types:

event: start
data: {"id":"msg_abc123","type":"start"}

event: text_start
data: {"id":"txt_def456","type":"text_start"}

event: text_delta
data: {"id":"txt_def456","type":"text_delta","delta":"Hello"}

event: text_end
data: {"id":"txt_def456","type":"text_end"}

event: tool_call_start
data: {"id":"tool_ghi789","type":"tool_call_start","name":"get_weather"}

event: tool_call_end
data: {"id":"tool_ghi789","type":"tool_call_end"}

event: tool_result
data: {"id":"res_jkl012","type":"tool_result","callId":"tool_ghi789","result":{...}}

event: finish
data: {"id":"msg_abc123","type":"finish","usage":{"inputTokens":50,"outputTokens":120,"totalTokens":170}}

event: done
data: [DONE]

Shared Features

All adapters support:

Authentication — custom auth function receives the request and returns an AuthContext
Swagger / OpenAPI — auto-generated spec with Swagger UI at /docs
WebSocket — real-time bidirectional communication (subscribe, run, stop)
SSE Streaming — Server-Sent Events for agent, workflow, and swarm execution

Choosing an Adapter

Use case	Recommended
Existing Express codebase	`@cogitator-ai/express`
High-performance, schema validation	`@cogitator-ai/fastify`
Edge / multi-runtime (Workers, Bun, Deno)	`@cogitator-ai/hono`
Koa-based middleware stack	`@cogitator-ai/koa`

Quick Install

# pick one
pnpm add @cogitator-ai/express express
pnpm add @cogitator-ai/fastify fastify
pnpm add @cogitator-ai/hono hono
pnpm add @cogitator-ai/koa koa @koa/router

Next Steps

Express Adapter — class-based setup with middleware
Fastify Adapter — native Fastify plugin with schema validation
Hono Adapter — multi-runtime edge deployment
Koa Adapter — middleware-chain pattern
OpenAPI Generation — customizing the generated spec

Server Adapters