Fast starts

Documentation Index

Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Picking an approach

​

Preload

​

Frontend

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 });
  // ...
}

​

Backend

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;
}

​

Head Start

​

Measured TTFC

​

How it works

​

Setup

// ⚠️ 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 };

// 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 };

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,
    }),
});

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),
    }),
});

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

​

Mounting in your framework

​

Web Fetch frameworks (recommended)

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

​

Edge / standalone runtimes

// 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 });
  },
};

​

Node-only frameworks

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);

​

Streaming response timeouts

• Pure-text first turns: ~LLM TTFB (1–3 s typically).
• Tool-calling first turns: LLM step 1 + agent boot + tool execution + step 2 LLM call. Usually 5–15 s; longer for multi-step tool use.
• Vercel: default function timeout is 10 s on Hobby, 60 s on Pro. Set export const maxDuration = N; on the route segment.
• Cloudflare Workers: default 30 s CPU time (paid plans up to 5 min). Streaming wall time is generally not the bottleneck.
• AWS Lambda behind API Gateway: 29 s API Gateway hard limit; Lambda Function URL allows up to 15 min.

​

What gets routed where

​

The chat.headStart API

chat.headStart<TTools>({
  agentId: string,                       // The chat.agent({ 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
}): (req: Request) => Promise<Response>

• messages: UIMessage[] — user messages parsed from the request body.
• signal: AbortSignal — fires when the request closes or the SDK times out the handover.
• chat: HeadStartChatHelper<TTools> — exposes chat.toStreamTextOptions({ tools }) and a chat.session escape hatch for power users.

​

The transport option

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

​

Limitations

• First turn only. Step 2+ and turn 2+ run on the trigger side. There’s no per-turn “head start every turn” mode — the win comes from amortizing agent boot across the LLM call once.
• Single step on the warm-server side. The handler runs stopWhen: stepCountIs(1). Multi-step handover (handler does step 1 + step 2 + …) is out of scope.
• Your server needs an LLM provider key. The first-turn LLM call runs in your warm process, so that environment needs whatever keys the model requires. The agent’s executes still run on the Trigger.dev side with whatever environment variables they need there.
• Browser-only chat surfaces don’t apply. Without a warm server process, there’s nowhere to run step 1 ahead of the agent run. Use Preload or eat the cold-start tax.
• Streaming-capable runtime required. Your framework / runtime has to support streaming HTTP responses (Web Fetch Response body or equivalent). Most modern hosts do — Next.js, Hono, SvelteKit, Workers, Bun, Deno, Vercel, etc. Some legacy platforms that buffer full responses won’t deliver chunks until the turn is over, which negates the TTFC benefit (correctness still holds).
• Non-useChat chat surfaces (Slack bots, Discord bots, custom protocols) don’t fit the chat.headStart shape — the API expects the AI SDK transport’s wire payload on input. For those, trigger the chat.agent directly from your bot handler.

​

Reference

• chat.headStart factory and types — full signatures for HeadStartRunArgs, HeadStartChatHelper, HeadStartSession, HeadStartHandlerOptions.
• headStart transport option — alongside accessToken, startSession, etc.
• onPreload hook — the backend hook that fires when a run is preloaded.