Next.js
First-class Next.js integration with streaming API route handlers and React hooks for building chat interfaces.
Overview
The @cogitator-ai/next package provides everything you need to build AI-powered Next.js applications: server-side route handlers that stream responses via SSE, and client-side React hooks that consume them with full tool call support.
pnpm add @cogitator-ai/next @cogitator-ai/coreServer: Chat Handler
createChatHandler turns a Cogitator agent into a streaming API route handler. It accepts a standard Request, runs the agent with token streaming enabled, and returns an SSE stream of typed events (start, text-*, reasoning-*, tool-call-*, tool-update, tool-result, approval-required, finish, error) ending with data: [DONE]. The events are the server adapters' streaming protocol from @cogitator-ai/server-shared, with the thread in start and finish: consume them with useCogitatorChat. finish carries the run's usage, the same object createAgentHandler answers: inputTokens, outputTokens, totalTokens, and reasoningTokens, cachedInputTokens and cacheWriteTokens when the model reported them. The handlers are plain (req: Request) => Promise<Response> functions, so they also work in other fetch-based runtimes.
The default body is { messages, threadId?, metadata? }.
- The last user message is the run input, history lives in the thread (configure
memoryonCogitator). Without athreadIdthe handler opens a new thread and names it instart,finishrepeats it, anduseCogitatorChatadopts it automatically. - Request
metadatais passed to the run ascontext, but only the keysacceptContextallows: the run sendscontextto the model as data the application supplied, so by default a request withmetadatais refused with400. PassacceptContext: ['plan']for those keys, ortruefor clients you trust like your own code. - While the run is silent the stream writes a
: keep-alivecomment everysseHeartbeatMs(5 s by default,0turns it off), so a proxy or the platform's idle timeout does not cut it. - The run is aborted when the client disconnects, unless
resumableStreamsis on: then it goes on and the client reconnects, see Resumable streams. - An agent with
reasoning: { summary: true }streams its summary asreasoning-start/reasoning-delta/reasoning-end; a reasoning or text block is closed before the other kind, a tool call orfinishstarts. - Bodies over 1 MB get
413, bodies that are not JSON (text/plain, forms, which browsers send across origins without a preflight)415, and malformed bodies or a request without a user message400. - A failed run ends the stream with an
errorevent — see Errors.
import { Cogitator, Agent } from '@cogitator-ai/core';
import { createChatHandler } from '@cogitator-ai/next';
const cog = new Cogitator({
llm: {
defaultProvider: 'openai',
providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
},
});
const agent = new Agent({
name: 'assistant',
model: 'openai/gpt-6.1-sol',
instructions: 'You are a helpful assistant.',
});
const handler = createChatHandler(cog, agent);
export const POST = handler;ChatHandlerOptions
You can pass options to customize parsing, authentication, and post-processing:
const handler = createChatHandler(cog, agent, {
beforeRun: async (req, input) => {
const token = req.headers.get('authorization');
if (!token) throw new Error('Unauthorized');
const user = await verifyToken(token);
return { userId: user.id };
},
afterRun: async (result) => {
await db.saveChatMessage(result.threadId, result.output);
},
});| Option | Type | Description |
|---|---|---|
parseInput | (req: Request) => Promise<ChatInput> | Custom request body parser |
beforeRun | (req: Request, input: ChatInput) => Promise<object | void> | Auth hook; the returned object is merged into the run options (userId, threadId, ...) but cannot replace stream, signal or the streaming callbacks. Throw an error with a status property to reject with that status (default 401) |
afterRun | (result: RunResult) => Promise<void> | Post-processing hook (save to DB, log, etc.). Runs before finish; a failure is reported as an error event |
Server: Agent Handler
For non-streaming use cases, createAgentHandler returns a JSON response with the full result including tool calls, traces, and usage. The default parser requires a non-blank string input (plus optional object context and string threadId) and answers 400 otherwise:
import { createAgentHandler } from '@cogitator-ai/next';
const handler = createAgentHandler(cog, agent, {
beforeRun: async (req, input) => {
return { userId: 'user-123' };
},
});
export const POST = handler;The response shape:
interface AgentResponse {
output: string;
threadId: string;
usage: {
inputTokens: number;
outputTokens: number;
totalTokens: number;
reasoningTokens?: number;
cachedInputTokens?: number;
cacheWriteTokens?: number;
};
toolCalls: { id: string; name: string; arguments: Record<string, unknown> }[];
reasoning?: string;
status: 'completed' | 'paused';
pendingApprovals?: PendingApproval[];
structured?: unknown;
structuredError?: string;
truncated?: true;
blocked?: 'content_filter' | 'refusal';
iterationLimitReached?: true;
traceId: string;
}It is the object every Cogitator adapter answers (toAgentRunResponse()), never the system prompt, the history or trace spans with raw tool arguments and errors. afterRun receives the whole RunResult. createAgentHandler reads its default body with the validator the adapters share, so context takes only the keys acceptContext allows there too.
Resumable streams
resumableStreams on createChatHandler (and createResumeHandler with stream: true) keeps the stream of each run, so a run outlives a dropped connection:
const handler = createChatHandler(cog, agent, {
beforeRun: async (req) => ({ userId: await userIdFrom(req) }),
resumableStreams: { owner: (req) => (req ? userIdFrom(req) : undefined) },
});
export const POST = handler;
export const DELETE = handler;Every event then carries an SSE id (<streamId>:<seq>), and a client that disconnects no longer stops the run (the signal beforeRun returns still does). The same request again with Last-Event-ID reconnects instead of starting a run: it replays the events after the id, then follows the run to finish or error. ?lastEventId= works too, but it puts the id into URLs and logs, so prefer the header. DELETE on the route with ?streamId= cancels the run, which ends its stream with STREAM_CANCELLED: export the handler as DELETE too.
A reconnect and a cancel read no body and run neither beforeRun nor deps, so their side effects do not repeat. The stream is bound to owner(req), and only a request with the same owner may reconnect or cancel, after authorizeThread(req, threadId) on the stream's thread: others get 404 STREAM_NOT_FOUND or 403 THREAD_FORBIDDEN. With beforeRun the handler needs an owner and throws without one, without beforeRun every caller is anonymous. useCogitatorChat reconnects by itself and cancels on stop(), see Reconnecting.
true keeps the events in the memory of the handler. A platform that serves the route from several instances, or stops a function once its response ends, needs a shared store and a runtime that keeps the run going: see Resumable Streams for the limits, detached runs and stores.
Errors
Every handler answers request problems before running the agent, as JSON { "error": { "message": "<message>", "code": "<code>" } }, the envelope every Cogitator adapter uses:
413for bodies over 1 MB,415for a body that is not JSON,400for invalid JSON, a body that fails the default parser (withcode: "INVALID_INPUT"), or an error thrown byparseInput.- An error thrown by
beforeRunwith a client errorstatus(400to499) answers with that status, its message and itscode. ACogitatorErroranswers as a failed run. Any other error is logged and answered401 Unauthorizedwithout its text.
A failed run answers in the same envelope, or, in a stream, with an error event carrying the same message and code. A CogitatorError keeps its message, code and status (for example 403 THREAD_ACCESS_DENIED, 429 LLM_RATE_LIMITED) and sends Retry-After when the provider said when to retry. Any other error is logged on the server and reported as 500 with Internal server error and code INTERNAL_ERROR, so its text never reaches the client.
Every handler takes the server contract options of the other adapters too:
| Option | Type | Description |
|---|---|---|
anonymous | 'allow' | 'deny' | 'deny' answers 401 UNAUTHORIZED when beforeRun returned no userId. Default 'allow' |
authorizeThread | (req: Request, threadId: string) => boolean | Promise<boolean> | Asked about the thread a request names before the run, false answers 403 THREAD_FORBIDDEN |
deps | (req: Request) => unknown | The run's deps for its tools, never read from the body. A deps from beforeRun wins |
Approvals
A tool with requiresApproval pauses the run before it executes. The runtime keeps the checkpoint on the server, per thread; clients only see the calls waiting for a decision (toolCallId, toolName, arguments, description, sideEffects). createAgentHandler answers with status: 'paused' and pendingApprovals, and createChatHandler streams { type: 'approval-required', threadId, approvals } right before finish.
createResumeHandler continues the run. Its body is { threadId, decisions?, defaultDecision? }, a decision being { approved: true } or { approved: false, reason? } by tool call id. Approved calls run, declined ones answer the model with the reason, and undecided ones pause the run again:
import { createResumeHandler } from '@cogitator-ai/next';
export const POST = createResumeHandler(cog, agent, {
stream: true,
beforeRun: async (req) => ({ userId: await getUserId(req) }),
});It answers like createAgentHandler, or streams like createChatHandler with stream: true. Return the caller's userId from beforeRun: only the user the run belongs to may resume it (403 THREAD_ACCESS_DENIED), and a thread without a paused run answers 409 RUN_NOT_PAUSED.
const { pendingApprovals, approve, deny, resume } = useCogitatorChat({
api: '/api/chat',
resumeApi: '/api/chat/resume',
onApprovalRequired: (approvals) => console.log('Waiting for', approvals),
});
return (
<>
{pendingApprovals.map((call) => (
<p key={call.toolCallId}>
{call.toolName}: {JSON.stringify(call.arguments)}
<button onClick={() => resume({ decisions: { [call.toolCallId]: { approved: true } } })}>
Approve this one
</button>
</p>
))}
<button onClick={() => approve()}>Approve all</button>
<button onClick={() => deny('Over the refund limit')}>Deny all</button>
</>
);The rest of the run streams into a new assistant message (a JSON resumeApi is appended as one message). pendingApprovals clears once the resume is accepted, when the server has nothing paused anymore (409), or when the user sends a new message, which declines the waiting calls. useCogitatorAgent({ api, resumeApi }) exposes the pendingApprovals of its last result and resume(decisions).
Triggers and inbox
createTriggerHandler and createInboxHandler (experimental) serve the routes of API triggers, webhooks and the inbox of their results from the runtime's trigger manager, as the server adapters do. Start the manager yourself:
import { Cogitator } from '@cogitator-ai/core';
import { createInboxHandler } from '@cogitator-ai/next';
export const cog = new Cogitator({ experimental_triggers: { agents, routines } });
await cog.experimental_triggers?.start();
export const inbox = createInboxHandler(cog.experimental_triggers!, {
auth: async (req) => ({ userId: await getUserId(req) }),
});import { createTriggerHandler } from '@cogitator-ai/next';
import { cog } from '@/lib/cogitator';
export const POST = createTriggerHandler(cog.experimental_triggers!);export const { GET } = inbox;export const { PATCH } = inbox;| Route | Auth | Body |
|---|---|---|
POST /api/triggers/:id/fire | The trigger's own bearer token | { "text": "..." }, read raw |
POST /api/triggers/:id/webhook | The sender's signature (HMAC, GitHub, Mailgun, Postmark, SendGrid, Slack) | Any content type, read raw |
GET /api/inbox | auth and anonymous | ?status=unread&kind=failure&routineId=...&limit=20&before=<ms>&beforeId=<id> |
PATCH /api/inbox/:id | auth and anonymous | { "status": "read" | "unread" | "archived" } |
The trigger handler runs no auth of its own: a trigger checks the token or the signature over the body exactly as it came, read raw for any content type up to 10 MiB and never parsed or re-serialized. A larger body answers 413 PAYLOAD_TOO_LARGE, a route other than fire and webhook 404, and everything else is the trigger manager's answer. The inbox handlers take the caller from auth ({ userId }, undefined for an anonymous caller). A caller without a user id, which is every caller without auth, gets 401 UNAUTHORIZED unless anonymous: 'allow' is set, then they see the items without one. A caller sees and changes only the items of its userId, and another user's item answers 404 NOT_FOUND. params may be a promise (Next 15 and later) or the object itself.
Client: useCogitatorChat
The useCogitatorChat hook manages the entire chat lifecycle -- sending messages, processing the SSE stream, handling tool calls, and tracking loading state.
'use client';
import { useCogitatorChat } from '@cogitator-ai/next/client';
export function Chat() {
const { messages, input, setInput, send, isLoading, stop, reload, error } = useCogitatorChat({
api: '/api/chat',
onToolCall: (toolCall) => {
console.log(`Tool invoked: ${toolCall.name}`, toolCall.arguments);
},
onFinish: (message) => {
console.log('Assistant replied:', message.content);
},
retry: { maxRetries: 2, backoff: 'exponential' },
});
return (
<div>
{messages.map((msg) => (
<div key={msg.id}>
<strong>{msg.role}:</strong> {msg.content}
</div>
))}
{error && <p>Error: {error.message}</p>}
<input
value={input}
onChange={(e) => setInput(e.target.value)}
onKeyDown={(e) => e.key === 'Enter' && send()}
disabled={isLoading}
/>
{isLoading && <button onClick={stop}>Stop</button>}
</div>
);
}UseChatOptions
| Option | Type | Description |
|---|---|---|
api | string | API endpoint URL (required) |
threadId | string | Initial thread ID for conversation context |
initialMessages | ChatMessage[] | Pre-populate the message list |
headers | Record<string, string> | Custom headers sent with each request |
onError | (error: Error) => void | Error callback |
onFinish | (message: ChatMessage) => void | Called when assistant message is complete (not after an error event) |
onToolCall | (toolCall: ToolCall) => void | Called when a tool is invoked, and again with the new arguments when the server corrects them (a tool-update with arguments) |
onToolResult | (result: ToolResultEvent) => void | Called when a tool returns a result, with its details and presentation when it has them |
onToolCallDropped | (toolCallId: string) => void | A call the stream announced never runs (Streaming Tool Input), it is gone from the message's toolCalls, onToolCall may have reported it before |
onReasoning | (delta: string) => void | Called with each piece of the reasoning summary, the pieces collect in message.reasoning |
onApprovalRequired | (approvals: PendingApproval[]) => void | Called when the run pauses for approvals |
onData | (part: DataEvent) => void | Every data part the stream sends, transient ones included, which never reach the message's data |
onStateChange | (state: unknown) => void | The run's state each time a state-snapshot or state-delta changes it |
resumeApi | string | Endpoint of a createResumeHandler, for resume, approve and deny |
retry | RetryConfig | Retry on network failures and 408/429/502/503/504 |
reconnect | false | { attempts?, delayMs? } | Resume a stream that drops mid-run with Last-Event-ID, see Reconnecting. Default { attempts: 3, delayMs: 1000 }, effective only when the server sends event ids |
Reconnecting
Against a handler with resumableStreams, whose events carry ids, the hook keeps the id of the last event it got. When the stream drops in the middle of a run (the network fails, or the body ends before finish or error), it sends the same request again with Last-Event-ID, and the assistant message goes on in place with no event lost or repeated. It waits delayMs before the first reconnect and twice as long before each next one, and gives up after attempts reconnects in a row that failed or brought no event, with the last error, or The stream ended before the run finished when the stream kept ending early: a cut answer never finishes as if it were whole. STREAM_NOT_FOUND (the server no longer keeps the stream) and STREAM_RESUME_GAP (it lost events after the id) end the request with that error, so reload the thread from your own route to catch up. stop(), reload() and a new message that interrupts the current one abort the fetch and also cancel the run on the server (DELETE with ?streamId=), so a stopped answer stops spending tokens and does not land in the thread. A stream without ids ends as before.
Return Values
| Field | Type | Description |
|---|---|---|
messages | ChatMessage[] | All messages including live streaming |
input | string | Current input value |
setInput | (value: string) => void | Update input |
send | (input?, metadata?) => Promise<void> | Send a message (input defaults to the input field) |
isLoading | boolean | Whether agent is running |
error | Error | null | Last error |
stop | () => void | Abort the current stream (the partial reply is kept) |
reload | () => Promise<void> | Re-send the last user message |
threadId | string | undefined | Current thread ID |
setThreadId | (id: string) => void | Switch conversation thread |
appendMessage | (msg: ChatMessage) => void | Add a message to the list |
clearMessages | () => void | Reset conversation |
setMessages | (msgs: ChatMessage[]) => void | Replace message list |
pendingApprovals | PendingApproval[] | Tool calls the paused run waits on |
state | unknown | The run's state, as its tools changed it |
resume | (decisions: ResumeDecisions) => Promise<void> | Continue the paused run with these decisions |
approve | () => Promise<void> | Approve every pending call |
deny | (reason?: string) => Promise<void> | Decline every pending call |
An assistant message keeps the data parts its tools sent in data, the latest of each id, and a step the server takes back (reset-step) leaves the message: its text, reasoning and tool calls are removed before the step streams anew.
HTTP failures surface as HttpError (exported from @cogitator-ai/next/client) with a status field and a message such as Request failed: 400 - No user message provided.
Client: useCogitatorAgent
For non-streaming agent calls (task execution, one-shot questions), use useCogitatorAgent:
'use client';
import { useCogitatorAgent } from '@cogitator-ai/next/client';
export function AgentRunner() {
const { run, result, isLoading, error, reset } = useCogitatorAgent({
api: '/api/agent',
onSuccess: (res) => console.log('Done:', res.output),
});
return (
<div>
<button onClick={() => run({ input: "Summarize today's news" })} disabled={isLoading}>
Run Agent
</button>
{result && <pre>{JSON.stringify(result, null, 2)}</pre>}
</div>
);
}| Option | Type | Description |
|---|---|---|
api | string | Endpoint of a createAgentHandler (required) |
resumeApi | string | Endpoint of a createResumeHandler, for resume |
headers | Record<string, string> | Custom headers sent with each request |
onSuccess | (result: AgentResponse) => void | Called with each successful result |
onError | (error: Error) => void | Error callback |
retry | RetryConfig | Retry on network failures and 408/429/502/503/504 |
It returns run(input), result, reasoning, pendingApprovals, resume(decisions), isLoading, error and reset().
createAgentHandler returns the run's reasoning summary as reasoning (also exposed by the hook as reasoning), and usage carries reasoningTokens, cachedInputTokens and cacheWriteTokens when the provider reports them. Starting a new run() aborts the previous request, and reset() cancels the in-flight one.
AG-UI
createAGUIHandler serves an agent to AG-UI clients such as CopilotKit: it takes a RunAgentInput and streams AG-UI events, runs the last user message in the request's thread, or resumes the paused run with its resume entries. beforeRun returns run options such as { userId }, and authorizeThread, anonymous and deps work as on the other handlers.
// app/api/agui/route.ts
import { createAGUIHandler } from '@cogitator-ai/next';
export const POST = createAGUIHandler(cog, agent, {
beforeRun: async (req) => ({ userId: await userIdFrom(req) }),
});Server Actions
You can also use Cogitator directly inside Next.js Server Actions without the HTTP layer:
'use server';
import { Cogitator, Agent } from '@cogitator-ai/core';
const cog = new Cogitator({/* ... */});
const agent = new Agent({
name: 'summarizer',
model: 'openai/gpt-6-luna',
instructions: 'Summarize the given text concisely.',
});
export async function summarize(text: string) {
const result = await cog.run(agent, { input: text });
return { summary: result.output, usage: result.usage };
}