> ## 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.

# AI Agents

> Durable multi-turn AI chats — one Trigger.dev task per conversation, surviving refreshes, deploys, and crashes.

An AI chat isn't a request — it's a session. `chat.agent` runs every conversation as a single long-lived Trigger.dev task: you write the loop, it wakes up when a message arrives, freezes when none do, and the same in-memory state and on-disk workspace survive across page refreshes, deploys, idle gaps, and crashes. The substrate handles the parts most teams stitch together by hand — turn lifecycle, mid-stream resume, recovery from cancel/crash/OOM, HITL approvals, deploy upgrades — so your code is the loop you'd write anyway: messages in, `streamText` out.

## A minimal example

A `chat.agent` task takes `messages`, calls `streamText`, and returns the result. The frontend wires the [Vercel AI SDK's `useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) to a `TriggerChatTransport`. No API routes.

```ts trigger/chat.ts theme={"theme":"css-variables"}
import { chat } from "@trigger.dev/sdk/ai";
import { stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";

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

```tsx app/components/Chat.tsx theme={"theme":"css-variables"}
import { useChat } from "@ai-sdk/react";
import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";

export function Chat() {
  const transport = useTriggerChatTransport<typeof myChat>({
    task: "my-chat",
    accessToken: ({ chatId }) => mintChatAccessToken(chatId),
    startSession: ({ chatId, clientData }) =>
      startChatSession({ chatId, clientData }),
  });
  const { messages, sendMessage } = useChat({ transport });
  // ... render UI
}
```

See [Quick Start](https://trigger.dev/docs/ai-chat/quick-start.md) for the matching server actions and a runnable project.

## Why use AI Agents on Trigger.dev

* **Resume across refreshes, deploys, and crashes.** A chat in progress keeps streaming through a redeploy, pinned to the version it started on. Move it onto new code when you choose with a [version upgrade](https://trigger.dev/docs/ai-chat/patterns/version-upgrades.md). Mid-stream refreshes pick up where they left off.
* **Native AI SDK support.** Text, tool calls, reasoning, and custom `data-*` parts all flow through `useChat` over a custom `ChatTransport`. No custom protocol to maintain.
* **Multi-turn for free.** Each turn is a step inside the same durable task; conversation history accumulates server-side, so clients only ship the new message.
* **Fast cold starts.** Opt-in [Head Start](https://trigger.dev/docs/ai-chat/fast-starts.md#head-start) runs the first `streamText` step in your warm Next.js / Hono / SvelteKit server while the agent boots in parallel — cuts time-to-first-chunk roughly in half.
* **Production primitives ship in the box.** Stop generation, steering, edits, branching, sub-agents, HITL tool approvals, version upgrades, recovery from cancel/crash/OOM — all first-class.
* **Observable.** Every turn is a span in the Trigger.dev dashboard. Sessions are queryable via `sessions.list` for inbox-style UIs.

## How it fits together

Four primitives, related but distinct:

* **Chat agents** — the SDK surface you define with [`chat.agent()`](https://trigger.dev/docs/ai-chat/backend#chat-agent). Owns the turn loop, lifecycle hooks, and the response stream.
* **Sessions** — the durable, bi-directional channel keyed on `chatId` that holds the conversation across run boundaries. A chat agent runs *on top of* a [Session](https://trigger.dev/docs/ai-chat/sessions.md).
* **Sub-agents**: delegate work from one agent to another via [`AgentChat`](https://trigger.dev/docs/ai-chat/patterns/sub-agents). The sub-agent runs as its own durable agent on its own session; [`chat.forwardSubAgent`](https://trigger.dev/docs/ai-chat/patterns/sub-agents) streams its reply through the parent's tool call, so the frontend sees the sub-agent working inside the parent's tool card.
* **Channels** connect an agent to a surface other than your frontend. [`slack()`](https://trigger.dev/docs/webhooks/slack) and [`linear()`](https://trigger.dev/docs/webhooks/linear) turn an agent into a Slack or Linear agent, and [`chat.channels.custom()`](https://trigger.dev/docs/webhooks/channels) connects any chat surface that sends webhooks. Each conversation there is still a durable session, and the reply posts back to the surface.

## Next steps

> [card] [Quick Start](https://trigger.dev/docs/ai-chat/quick-start.md)
>
> Get a working chat in three steps — agent, token, frontend.

> [card] [How it works](https://trigger.dev/docs/ai-chat/how-it-works.md)
>
> Sessions, the turn loop, durable streams, and what survives a refresh.

> [card] [Backend](https://trigger.dev/docs/ai-chat/backend.md)
>
> `chat.agent` options, lifecycle hooks, and the raw-task primitives.

> [card] [Tools](https://trigger.dev/docs/ai-chat/tools.md)
>
> Declare tools so `toModelOutput` survives across turns, typed in `run()`.

> [card] [Patterns](https://trigger.dev/docs/ai-chat/patterns/sub-agents.md)
>
> HITL approvals, branching, sub-agents, OOM/crash recovery.

> [card] [Database connections](https://trigger.dev/docs/database-connections.md)
>
> Size and release connection pools so agents don't exhaust your database.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.