Fast starts

import { useEffect } from "react";
import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
import { useChat } from "@ai-sdk/react";

export function Chat({ chatId }) {
  const transport = useTriggerChatTransport({
    task: "my-chat",
    accessToken: ({ chatId }) => mintChatAccessToken(chatId),
    startSession: ({ chatId, clientData }) =>
      startChatSession({ chatId, clientData }),
    clientData: { userId: currentUser.id },
  });

  // Preload on mount: run starts before the user types anything.
  // Trigger config (idleTimeoutInSeconds, machine, tags) lives in the
  // server action that wraps `chat.createStartSessionAction`.
  useEffect(() => {
    transport.preload(chatId);
  }, [chatId]);

  const { messages, sendMessage } = useChat({ id: chatId, transport });
  // ...
}

export const myChat = chat.agent({
  id: "my-chat",
  onPreload: async ({ chatId, clientData }) => {
    // Eagerly initialize: runs before the first message
    userContext.init(await loadUser(clientData.userId));
    await db.chat.create({ data: { id: chatId } });
  },
  onChatStart: async ({ preloaded }) => {
    if (preloaded) return; // Already initialized in onPreload
    // ... fallback initialization for non-preloaded runs
  },
  run: async ({ messages, signal }) => {
    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
  },
});

if (payload.trigger === "preload") {
  // Initialize early...
  const result = await chat.messages.waitWithIdleTimeout({
    idleTimeoutInSeconds: 60,
    timeout: "1h",
  });
  if (!result.ok) return;
  currentPayload = result.output;
}

sequenceDiagram
    autonumber
    participant B as Browser
    participant H as Route handler
(your warm server)
    participant T as chat.agent run
(Trigger.dev)

    B->>H: POST first message
(headStart URL)

    par Step 1 + agent boot in parallel
        H->>H: streamText step 1
(your model, schema-only tools)
        H-->>B: SSE: step 1 chunks
    and
        H->>T: createSession + trigger run
        T->>T: boot → wait on session.in
    end

    alt finishReason: tool-calls
        H->>T: handover signal
(partial assistant message)
        T->>T: execute tools, run step 2 LLM
        T-->>H: chunks via session.out
        H-->>B: SSE: step 2 chunks
        T-->>H: trigger:turn-complete
    else finishReason: stop (pure text)
        H->>T: handover-skip signal
        T->>T: exit (no LLM call)
    end

    H-->>B: SSE close
    Note over B,T: Subsequent turns bypass the handler:
browser writes directly to session.in

```ts lib/chat-tools/schemas.ts
// ⚠️ This file MUST NOT import anything heavier than `ai` and `zod`.
// Any import here lands in the route-handler bundle.
import { tool } from "ai";
import { z } from "zod";

export const fetchPage = tool({
  description: "Fetch a URL and return text",
  inputSchema: z.object({ url: z.string().url() }),
  // No execute — agent task adds it elsewhere.
});

export const headStartTools = { fetchPage };
```

```ts trigger/chat-tools.ts
// Heavy deps live here. Only the trigger task imports this module.
import { tool } from "ai";
import TurndownService from "turndown";
import { fetchPage as fetchPageSchema } from "@/lib/chat-tools/schemas";

const turndown = new TurndownService();

export const fetchPage = tool({
  ...fetchPageSchema,
  execute: async ({ url }) => {
    const res = await fetch(url);
    return { body: turndown.turndown(await res.text()) };
  },
});

export const chatTools = { fetchPage };
```

```ts trigger/chat.ts
import { chat } from "@trigger.dev/sdk/ai";
import { streamText, stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { chatTools } from "./chat-tools";

export const myChat = chat.agent({
  id: "my-chat",
  run: async ({ messages, signal }) =>
    streamText({
      ...chat.toStreamTextOptions({ tools: chatTools }),
      model: anthropic("claude-sonnet-4-6"),
      messages,
      stopWhen: stepCountIs(10),
      abortSignal: signal,
    }),
});
```

```ts lib/chat-handler.ts
import { chat } from "@trigger.dev/sdk/chat-server";
import { streamText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { headStartTools } from "@/lib/chat-tools/schemas";

export const chatHandler = chat.headStart({
  agentId: "my-chat",
  run: async ({ chat: helper }) =>
    streamText({
      ...helper.toStreamTextOptions({ tools: headStartTools }),
      model: anthropic("claude-sonnet-4-6"),
      system: "You are a helpful assistant.",
      stopWhen: stepCountIs(15),
    }),
});
```

<Tip>
  Use the **same model** on both sides (route handler and `chat.agent`) to avoid a tone or style shift between step 1 and step 2+. Your LLM provider keys stay server-side in your warm process — Trigger.dev never holds them in this design.
</Tip>

Mount the handler in whatever framework you use — see [Mounting in your framework](#mounting-in-your-framework) below.

```tsx components/chat.tsx
const transport = useTriggerChatTransport<typeof myChat>({
  task: "my-chat",
  accessToken: ({ chatId }) => mintChatAccessToken(chatId),
  startSession: ({ chatId, clientData }) =>
  startChatSession({ chatId, clientData }),
  headStart: "/api/chat",
});
```

// app/api/chat/route.ts
import { chatHandler } from "@/lib/chat-handler";

export const POST = chatHandler;
// Default function timeout on Vercel is 10s. Bump if your turns
// run long (multi-step tool use, slow models):
// export const maxDuration = 60;

// src/index.ts
import { Hono } from "hono";
import { chatHandler } from "./chat-handler";

const app = new Hono();

app.post("/api/chat", (c) => chatHandler(c.req.raw));

export default app;

// src/routes/api/chat/+server.ts
import type { RequestHandler } from "./$types";
import { chatHandler } from "$lib/chat-handler";

export const POST: RequestHandler = ({ request }) => chatHandler(request);

// app/routes/api.chat.ts
import type { ActionFunctionArgs } from "@remix-run/node";
import { chatHandler } from "~/lib/chat-handler";

export async function action({ request }: ActionFunctionArgs) {
  return chatHandler(request);
}

// app/routes/api/chat.ts
import { createAPIFileRoute } from "@tanstack/start/api";
import { chatHandler } from "~/lib/chat-handler";

export const Route = createAPIFileRoute("/api/chat")({
  POST: ({ request }) => chatHandler(request),
});

// src/pages/api/chat.ts
import type { APIRoute } from "astro";
import { chatHandler } from "../../lib/chat-handler";

export const POST: APIRoute = ({ request }) => chatHandler(request);

// server/api/chat.post.ts
import { chatHandler } from "~/lib/chat-handler";

export default defineEventHandler((event) => chatHandler(toWebRequest(event)));

// src/index.ts
import { Elysia } from "elysia";
import { chatHandler } from "./chat-handler";

new Elysia()
  .post("/api/chat", ({ request }) => chatHandler(request))
  .listen(3000);

// src/index.ts
import { chatHandler } from "./chat-handler";

export default {
  async fetch(req: Request): Promise<Response> {
    const url = new URL(req.url);
    if (req.method === "POST" && url.pathname === "/api/chat") {
      return chatHandler(req);
    }
    return new Response("Not found", { status: 404 });
  },
};

// server.ts
import { chatHandler } from "./chat-handler";

Bun.serve({
  port: 3000,
  async fetch(req) {
    const url = new URL(req.url);
    if (req.method === "POST" && url.pathname === "/api/chat") {
      return chatHandler(req);
    }
    return new Response("Not found", { status: 404 });
  },
});

// server.ts
import { chatHandler } from "./chat-handler.ts";

Deno.serve({ port: 3000 }, async (req) => {
  const url = new URL(req.url);
  if (req.method === "POST" && url.pathname === "/api/chat") {
    return chatHandler(req);
  }
  return new Response("Not found", { status: 404 });
});

import express from "express";
import { chat } from "@trigger.dev/sdk/chat-server";
import { chatHandler } from "./chat-handler";

const app = express();
app.post("/api/chat", chat.toNodeListener(chatHandler));
app.listen(3000);

import Fastify from "fastify";
import { chat } from "@trigger.dev/sdk/chat-server";
import { chatHandler } from "./chat-handler";

const fastify = Fastify();
const listener = chat.toNodeListener(chatHandler);

fastify.post("/api/chat", (req, reply) => {
  // Hand the raw Node request/response to the adapter and tell
  // Fastify we'll handle the response ourselves (no auto-reply).
  reply.hijack();
  return listener(req.raw, reply.raw);
});

fastify.listen({ port: 3000 });

import Koa from "koa";
import Router from "@koa/router";
import { chat } from "@trigger.dev/sdk/chat-server";
import { chatHandler } from "./chat-handler";

const app = new Koa();
const router = new Router();
const listener = chat.toNodeListener(chatHandler);

router.post("/api/chat", async (ctx) => {
  ctx.respond = false; // Tell Koa not to send the response itself.
  await listener(ctx.req, ctx.res);
});

app.use(router.routes()).listen(3000);

import http from "node:http";
import { chat } from "@trigger.dev/sdk/chat-server";
import { chatHandler } from "./chat-handler";

const listener = chat.toNodeListener(chatHandler);

http
  .createServer((req, res) => {
    if (req.method === "POST" && req.url === "/api/chat") {
      return listener(req, res);
    }
    res.statusCode = 404;
    res.end();
  })
  .listen(3000);

for await (const turn of session) {
  // Pure-text handover (isFinal): step 1 already IS the response.
  const result = turn.handover?.isFinal
    ? undefined
    : streamText({
        model: anthropic("claude-sonnet-4-6"),
        messages: turn.messages,
        abortSignal: turn.signal,
        stopWhen: stepCountIs(10),
      });

  await turn.complete(result); // no source on a final handover
}

// Turn 0, gated on a head-start run:
if (turn === 0 && payload.trigger === "handover-prepare") {
  const { isFinal, skipped } = await conversation.consumeHandover({ payload });
  if (skipped) return; // not a head-start run, or the warm handler aborted — exit
  if (!isFinal) {
    // The partial carries a pending tool call. Run step 2 to execute it,
    // passing originalMessages so the tool output merges into the
    // handed-over assistant instead of starting a new message.
    const result = streamText({
      model: anthropic("claude-sonnet-4-6"),
      messages: conversation.modelMessages,
      stopWhen: stepCountIs(10),
    });
    const response = await chat.pipeAndCapture(result, {
      originalMessages: conversation.uiMessages,
    });
    if (response) await conversation.addResponse(response);
  }
  await chat.writeTurnComplete(); // on isFinal the warm partial is already the response
  return;
}

chat.headStart<TTools>({
  agentId: string,                       // The chat.agent / chat.customAgent id you're handing off to
  run: (args: HeadStartRunArgs<TTools>) => Promise<StreamTextResult<any, any>>,
  idleTimeoutInSeconds?: number,         // How long the agent waits for the handover signal. Default: 60
  triggerConfig?: Partial<SessionTriggerConfig>, // Run options for the handover-prepare run
}): (req: Request) => Promise<Response>

export const chatHandler = chat.headStart({
  agentId: "my-chat",
  triggerConfig: { tags: ["org:acme"], queue: "chat", machine: "small-2x" },
  run: async ({ chat: helper }) =>
    streamText({ ...helper.toStreamTextOptions({ tools: headStartTools }), model, system }),
});

useTriggerChatTransport({
  // ... task, accessToken, startSession, ...
  headStart?: string,  // URL of your chat.headStart route handler
});

import { chat } from "@trigger.dev/sdk/chat-server";
import { streamText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { after } from "next/server";
// Schema-only tools; same bundle-isolation rule as chat.headStart.
import { headStartTools } from "@/lib/chat-tools/schemas";

export async function POST(req: Request) {
  const { chatId, messages } = await req.json();
  // Persist your own chat row + the first user message here.

  const { completion } = await chat.startHeadStart({
    agentId: "my-chat",
    chatId, // session externalId; reuse it on the destination page
    messages, // first-turn user history
    run: async ({ chat: helper }) =>
      streamText({
        ...helper.toStreamTextOptions({ tools: headStartTools }),
        model: anthropic("claude-sonnet-4-6"),
        system: "You are a helpful assistant.",
      }),
  });

  // Keep the function warm until step 1 drains and the handover dispatches.
  after(completion);

  return Response.json({ chatId });
}

import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
import { useChat } from "@ai-sdk/react";

const transport = useTriggerChatTransport({
  task: "my-chat",
  accessToken: ({ chatId }) => mintChatAccessToken(chatId),
});

const { messages } = useChat({ id: chatId, transport, resume: true });

chat.startHeadStart<TTools>({
  agentId: string,                               // chat.agent / chat.customAgent / chat.createSession id
  chatId: string,                                // session externalId; reuse on the destination page
  messages: UIMessage[],                         // first-turn user history
  run: (args: HeadStartRunArgs<TTools>) => Promise<StreamTextResult<any, any>>,
  idleTimeoutInSeconds?: number,                 // how long the agent waits for the handover signal. Default: 60
  triggerConfig?: Partial<SessionTriggerConfig>, // tags, queue, machine, …
  apiClient?: ApiClientConfiguration,            // when the agent lives in another project/env
  metadata?: Record<string, unknown>,            // merged into the run payload; never sent to the browser
}): Promise<{ chatId: string; completion: Promise<void> }>