Integrate with Next.js

Install

Bash

pnpm add @kestrel-agents/next@0.7.0 @kestrel-agents/sdk@0.7.0

Create the agent in a server-only module using the reference profile, as in the first Build step. Resolve the actor and tenant from the authenticated server session for each request.

JSON route

Create app/api/agent/run/route.ts:

TypeScript

import { createJsonRunRouteHandler } from "@kestrel-agents/next";
import { agent } from "@/lib/reference-agent";
import { resolveKestrelContext } from "@/lib/auth";
 
export const POST = createJsonRunRouteHandler({
  agent,
  resolveContext: resolveKestrelContext,
});

The default request body is:

JSON

{
  "sessionId": "reference-session-001",
  "message": "Summarize the current project."
}

The handler validates the body, runs the agent, returns the terminal event as JSON, and adds x-kestrel-request-id and x-kestrel-correlation-id.

Streaming route

TypeScript

import { createStreamRunRouteHandler } from "@kestrel-agents/next";
import { agent } from "@/lib/reference-agent";
import { resolveKestrelContext } from "@/lib/auth";
 
export const POST = createStreamRunRouteHandler({
  agent,
  resolveContext: resolveKestrelContext,
});

This handler returns server-sent events and passes request.signal to the SDK. Closing the response cancels the exact upstream run.

Webhook route

Use a webhook helper when the incoming payload does not already have the Kestrel turn shape:

TypeScript

import { createWebhookRunRouteHandler } from "@kestrel-agents/next";
import { agent } from "@/lib/reference-agent";
import { resolveKestrelContext } from "@/lib/auth";
 
export const POST = createWebhookRunRouteHandler<{
  conversationId: string;
  prompt: string;
}>({
  agent,
  resolveContext: resolveKestrelContext,
  mapPayload(payload) {
    return {
      sessionId: payload.conversationId,
      message: payload.prompt,
    };
  },
});

Authenticate and validate the webhook before treating its fields as actor, tenant, session, or approval context.

Correlation ownership

The Next.js helpers read x-request-id and x-correlation-id, generate missing values, and return x-kestrel-request-id and x-kestrel-correlation-id. Session and run headers belong to upstream OpenAI-compatible responses; they are not generated by these route helpers.

Use the route cookbook for request and response details or OpenAI-compatible HTTP for an existing OpenAI client.

Install

JSON route

Streaming route

Webhook route

Correlation ownership

Next steps

Next.js route cookbook

Environment and auth