Cogitator
Integrations

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/core

Server: 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 memory on Cogitator). Without a threadId the handler opens a new thread and names it in start, finish repeats it, and useCogitatorChat adopts it automatically.
  • Request metadata is passed to the run as context, but only the keys acceptContext allows: the run sends context to the model as data the application supplied, so by default a request with metadata is refused with 400. Pass acceptContext: ['plan'] for those keys, or true for clients you trust like your own code.
  • While the run is silent the stream writes a : keep-alive comment every sseHeartbeatMs (5 s by default, 0 turns it off), so a proxy or the platform's idle timeout does not cut it.
  • The run is aborted when the client disconnects, unless resumableStreams is on: then it goes on and the client reconnects, see Resumable streams.
  • An agent with reasoning: { summary: true } streams its summary as reasoning-start / reasoning-delta / reasoning-end; a reasoning or text block is closed before the other kind, a tool call or finish starts.
  • 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 message 400.
  • A failed run ends the stream with an error event — see Errors.
app/api/chat/route.ts
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);
  },
});
OptionTypeDescription
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:

app/api/agent/route.ts
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:

app/api/chat/route.ts
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:

  • 413 for bodies over 1 MB, 415 for a body that is not JSON, 400 for invalid JSON, a body that fails the default parser (with code: "INVALID_INPUT"), or an error thrown by parseInput.
  • An error thrown by beforeRun with a client error status (400 to 499) answers with that status, its message and its code. A CogitatorError answers as a failed run. Any other error is logged and answered 401 Unauthorized without 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:

OptionTypeDescription
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) => unknownThe 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:

app/api/chat/resume/route.ts
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.

components/chat.tsx
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:

lib/cogitator.ts
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) }),
});
app/api/triggers/[id]/[route]/route.ts
import { createTriggerHandler } from '@cogitator-ai/next';
import { cog } from '@/lib/cogitator';

export const POST = createTriggerHandler(cog.experimental_triggers!);
app/api/inbox/route.ts
export const { GET } = inbox;
app/api/inbox/[id]/route.ts
export const { PATCH } = inbox;
RouteAuthBody
POST /api/triggers/:id/fireThe trigger's own bearer token{ "text": "..." }, read raw
POST /api/triggers/:id/webhookThe sender's signature (HMAC, GitHub, Mailgun, Postmark, SendGrid, Slack)Any content type, read raw
GET /api/inboxauth and anonymous?status=unread&kind=failure&routineId=...&limit=20&before=<ms>&beforeId=<id>
PATCH /api/inbox/:idauth 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.

components/chat.tsx
'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

OptionTypeDescription
apistringAPI endpoint URL (required)
threadIdstringInitial thread ID for conversation context
initialMessagesChatMessage[]Pre-populate the message list
headersRecord<string, string>Custom headers sent with each request
onError(error: Error) => voidError callback
onFinish(message: ChatMessage) => voidCalled when assistant message is complete (not after an error event)
onToolCall(toolCall: ToolCall) => voidCalled when a tool is invoked, and again with the new arguments when the server corrects them (a tool-update with arguments)
onToolResult(result: ToolResultEvent) => voidCalled when a tool returns a result, with its details and presentation when it has them
onToolCallDropped(toolCallId: string) => voidA 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) => voidCalled with each piece of the reasoning summary, the pieces collect in message.reasoning
onApprovalRequired(approvals: PendingApproval[]) => voidCalled when the run pauses for approvals
onData(part: DataEvent) => voidEvery data part the stream sends, transient ones included, which never reach the message's data
onStateChange(state: unknown) => voidThe run's state each time a state-snapshot or state-delta changes it
resumeApistringEndpoint of a createResumeHandler, for resume, approve and deny
retryRetryConfigRetry on network failures and 408/429/502/503/504
reconnectfalse | { 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

FieldTypeDescription
messagesChatMessage[]All messages including live streaming
inputstringCurrent input value
setInput(value: string) => voidUpdate input
send(input?, metadata?) => Promise<void>Send a message (input defaults to the input field)
isLoadingbooleanWhether agent is running
errorError | nullLast error
stop() => voidAbort the current stream (the partial reply is kept)
reload() => Promise<void>Re-send the last user message
threadIdstring | undefinedCurrent thread ID
setThreadId(id: string) => voidSwitch conversation thread
appendMessage(msg: ChatMessage) => voidAdd a message to the list
clearMessages() => voidReset conversation
setMessages(msgs: ChatMessage[]) => voidReplace message list
pendingApprovalsPendingApproval[]Tool calls the paused run waits on
stateunknownThe 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>
  );
}
OptionTypeDescription
apistringEndpoint of a createAgentHandler (required)
resumeApistringEndpoint of a createResumeHandler, for resume
headersRecord<string, string>Custom headers sent with each request
onSuccess(result: AgentResponse) => voidCalled with each successful result
onError(error: Error) => voidError callback
retryRetryConfigRetry 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:

app/actions.ts
'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 };
}

On this page