createChatHandler

Creates the /api/chat endpoint as a web-standard function, (req: Request) => Promise<Response>, so it runs on Vercel, in any Node or edge server with web Request and Response, and in vite dev.

Creates the /api/chat endpoint as a web-standard function, (req: Request) => Promise<Response>, so it runs on Vercel, in any Node or edge server with web Request and Response, and in vite dev. One POST is one model step: the model’s tool calls stream back to the browser, which runs them on the live page. Use it on the server side of <AgentChat>.

Import

import { createChatHandler, DEFAULT_MODEL, turnstileVerify } from "@webmcp-agents/chat/server";
import type {
  AllowedTool,
  BeforeModelContext,
  TurnstileOptions,
  ChatHandlerOptions,
  ChatSessionOptions,
  ReasoningLevel,
} from "@webmcp-agents/chat/server";

Example

A handler for the page’s agents, a chosen model, sessions, a tool allowlist and a guard. The same file serves GET (is chat configured, and with which model) and POST.

import { createChatHandler } from "@webmcp-agents/chat/server";

import { agents } from "@/agents";

// A crude per-client limit; use a real store in production.
const seen = new Map<string, number>();

const handler = createChatHandler({
  // The same definitions the page passes to <AgentChat agent>.
  agents,
  model: "openai/gpt-5.5", // needs OPENAI_API_KEY
  reasoning: "low",
  maxSteps: 8,

  // The page's first GET starts a session (an httpOnly cookie signed
  // with WEB_AGENTS_SESSION_SECRET); a POST without one gets 401.
  session: true,
  // Only these tools reach the model.
  tools: ["search_products", "add_to_cart", "checkout"],

  // Runs first: a Response here ends the request.
  guard: (req) => {
    const who = req.headers.get("x-forwarded-for") ?? "local";
    const count = (seen.get(who) ?? 0) + 1;
    seen.set(who, count);
    return count > 100
      ? new Response("Too many requests", { status: 429 })
      : undefined;
  },
});

export const GET = handler;
export const POST = handler;

Options

createChatHandler(options?) takes a ChatHandlerOptions; every option is optional. Each POST is run by an AI SDK ToolLoopAgent built for the request from the registered WebAgent the page named (instructions, tool subset, sub-agents, model), or from the plain assistant prompt.

Sessions

session takes true or a ChatSessionOptions:

The cookie is HttpOnly; SameSite=Strict, its path is the endpoint’s, and it is Secure over https. The token is v1.<id>.<expires>.<born>.<signature>: 128 random bits and an HMAC-SHA256 signature, so the server keeps no store. The cloud adapter needs no change: its availability check is the GET, and a 401 session_required makes it start a session and retry once.

Turnstile

With turnstile on, a session starts only from a GET carrying a token Cloudflare accepts. The page gets one with turnstileHeaders only when it needs a session (the first message, or after one expired), so a visitor who never chats loads nothing. The server posts the token and the secret to Cloudflare’s siteverify and sets the cookie on success. A GET without the header never calls Cloudflare. A token is single-use, so it starts exactly one session; later messages ride on the cookie.

TurnstileOptions (also turnstileVerify(options, env), a plain verify function):

It fails closed: a missing token, a rejected one, a network error or a timeout starts no session. Cloudflare’s test keys work end to end: site key 1x00000000000000000000AA with secret 1x0000000000000000000000000000000AA always passes, secret 2x0000000000000000000000000000000AA always fails.

Returns

A handler. By method, in order:

Notes

• A public deployment needs guard, session and tools. Cross-site browser requests are refused, but anyone can still call the endpoint directly (requests without Origin pass).
• What a session proves, and what it doesn’t. A POST needs a cookie this server issued, and every request belongs to a session you can count. A script that keeps cookies can still GET first: only verify (a bot check) makes starting a session cost a real browser. Nothing can prove a request came from your page.
• What the allowlist covers. No tool reaches the model unless the server listed it, and listed defineWebTool tools can’t be redescribed by a request. The chat still works with no tools at all (the model just talks); the default system prompt keeps it to the site and has it decline anything unrelated. The messages themselves are the caller’s: limits and budgets bound what they cost.
• Page tools are declared without execute, with control characters stripped from descriptions and $schema and $id removed from schemas. Tool descriptions go in tool definitions only, never the system prompt.
• Of the page, only its path reaches the prompt, and only from a same-origin browser request.
• When the turn already has maxSteps assistant messages with tool calls, the request gets no tools and the system prompt asks for a summary.
• With a model id the request carries that provider’s reasoning options (Anthropic: effort and fallbacks: "default"). With a model instance none are set, and no provider SDK is loaded.
• A named agent: its instructions and the delegation note go into the system prompt, its tools filter and delegate tools shape the tool set (delegate descriptors sent by the page are ignored and rebuilt), its model is resolved with the server’s keys, and its maxSteps bounds the turn.
• Provider metadata on tool calls (Gemini thought signatures, OpenAI item ids) round-trips through the conversation like reasoning signatures.
• A call to an unknown tool, or with invalid input, goes back to the model as that call’s error (Error [unavailable]: …, Error [invalid_input]: …). Other model errors are logged and streamed as “The assistant had a problem answering. Try again.”
• The provider SDKs (@ai-sdk/anthropic, @ai-sdk/openai, …, @openrouter/ai-sdk-provider) are optional peer dependencies: install the one your model id needs on the server. The gateway needs none.
• The example apps wrap the handler with origin, rate-limit and budget guards through createVercelChatRoute.

See also

• Add the chat, the page that teaches it
• defineWebAgent, toToolLoopAgent and resolveModel
• webAgentsChatDev, the same endpoint in vite dev
• chatRequestSchema and LIMITS
• buildSystemPrompt and DEFAULT_SYSTEM_PROMPT
• createCloudAdapter, the client side
• Tool error codes