docs(ai-agents): add chat.agent guide and refresh the AI agent guides

docs/docs.json

@@ -472,6 +472,7 @@
  },
  "pages": [
  "guides/ai-agents/overview",
+ "guides/ai-agents/chat-agent",
  "guides/ai-agents/generate-translate-copy",
  "guides/ai-agents/route-question",
  "guides/ai-agents/respond-and-check-content",

docs/guides/ai-agents/chat-agent.mdx

@@ -0,0 +1,124 @@
+---
+title: "Build a chat agent"
+sidebarTitle: "Chat agent"
+description: "Create a durable, multi-turn chat agent with chat.agent(), then add tools to it like any AI SDK agent."
+---
+
+## Overview
+
+Build a **durable, multi-turn chat agent**. A durable session owns the conversation, streams tokens to your UI, and stays alive across many back-and-forth messages. The other guides in this section are one-shot workflows (trigger a task, run a fixed sequence of LLM calls, return a result); a chat agent instead owns the session for its whole lifetime.
+
+[`chat.agent()`](/ai-chat/overview) handles the queuing, retries, resumability and streaming for you. You write the model call, Trigger.dev owns the session. For the full feature set (sessions, fast starts, compaction, sub-agents, the frontend transport), see the [AI chat docs](/ai-chat/overview).
+
+## A minimal agent
+
+Define an agent with `chat.agent()`. The `run` function receives the conversation `messages` (already converted from the frontend's `UIMessage[]`) and an abort `signal`. Return a `StreamTextResult` and it's piped to the frontend automatically.
+
+```typescript trigger/chat.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { streamText, stepCountIs } from "ai";
+
+export const myChat = chat.agent({
+ id: "my-chat",
+ run: async ({ messages, signal }) => {
+ return streamText({
+ // Spread chat.toStreamTextOptions() FIRST: it wires up prepareStep
+ // (compaction, steering, background injection) and telemetry.
+ ...chat.toStreamTextOptions(),
+ model: anthropic("claude-sonnet-4-5"),
+ messages,
+ abortSignal: signal,
+ stopWhen: stepCountIs(15),
+ });
+ },
+});
+```
+
+<Warning>
+ Always spread `chat.toStreamTextOptions()` into your `streamText` call, and spread it first. It
+ wires up the `prepareStep` callback that drives compaction, mid-turn steering and background
+ injection. Those features silently no-op if the spread is missing.
+</Warning>
+
+## Add tools
+
+A chat agent uses tools exactly like any other AI SDK agent. Declare them on the config so their results survive across turns, then pass the `tools` you receive in `run` straight to `streamText`:
+
+```typescript trigger/chat.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { streamText, stepCountIs, tool } from "ai";
+import { z } from "zod";
+
+const getCurrentTime = tool({
+ description: "Get the current server time as an ISO string.",
+ inputSchema: z.object({}),
+ execute: async () => ({ now: new Date().toISOString() }),
+});
+
+export const myChat = chat.agent({
+ id: "my-chat",
+ // Declared here so tool results survive history re-conversion across turns.
+ tools: { getCurrentTime },
+ run: async ({ messages, tools, signal }) => {
+ return streamText({
+ // Pass tools INTO toStreamTextOptions (not separately to streamText):
+ // this is what detects tool calls needing HITL approval and merges any
+ // auto-injected skill tools. It sets streamText's `tools` for you.
+ ...chat.toStreamTextOptions({ tools }),
+ model: anthropic("claude-sonnet-4-5"),
+ messages,
+ stopWhen: stepCountIs(15),
+ abortSignal: signal,
+ });
+ },
+});
+```
+
+Swap `getCurrentTime` for whatever your agent needs to do: query a database, call an API, or trigger another Trigger.dev task. See [Tools](/ai-chat/tools) for how tool results are persisted and replayed across turns.
+
+## Wire up the frontend
+
+The browser talks to Trigger.dev directly through the [chat transport](/ai-chat/frontend), so there's no API route to maintain. Expose two server actions (one to start the session, one to mint a session-scoped token) and pass them to `useTriggerChatTransport`, then hand the transport to the AI SDK's `useChat`:
+
+```typescript app/actions.ts
+"use server";
+
+import { auth } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+
+export const startChatSession = chat.createStartSessionAction("my-chat");
+
+export async function mintChatAccessToken(chatId: string) {
+ // Authorize the caller for this chatId before minting: confirm the logged-in
+ // user owns this session (e.g. look it up in your database). Otherwise anyone
+ // who learns a session ID could mint read/write access to it.
+ return auth.createPublicToken({
+ scopes: { read: { sessions: chatId }, write: { sessions: chatId } },
+ expirationTime: "1h",
+ });
+}
+```
+
+See the [Quick Start](/ai-chat/quick-start) for the complete frontend component.
+
+## A full example
+
+For a complete, real-world chat agent, see the ClickHouse chat agent example. It builds on everything above with generative UI, a versioned system prompt, and real tools against a live database.
+
+<CardGroup cols={2}>
+ <Card title="ClickHouse chat agent" icon="chart-column" href="/guides/example-projects/clickhouse-chat-agent">
+ A full example project: a chat agent that answers questions about your data with charts, tables
+ and maps.
+ </Card>
+ <Card title="AI chat overview" icon="message-bot" href="/ai-chat/overview">
+ How chat agents, sessions and the turn loop work.
+ </Card>
+ <Card title="Tools" icon="wrench" href="/ai-chat/tools">
+ Declaring tools on your agent and how they persist across turns.
+ </Card>
+ <Card title="Fast starts" icon="bolt" href="/ai-chat/fast-starts">
+ Cut first-turn latency with preload and head start.
+ </Card>
+</CardGroup>

docs/guides/ai-agents/generate-translate-copy.mdx

@@ -16,14 +16,14 @@ In this example, we'll create a workflow that generates and translates copy. Thi
 
 **This task:**
 
-- Uses `generateText` from [Vercel's AI SDK](https://sdk.vercel.ai/docs/introduction) to interact with OpenAI models
-- Uses `experimental_telemetry` to provide LLM logs
+- Uses `generateText` from the [AI SDK](https://ai-sdk.dev/) to call Anthropic's Claude models
+- Uses `experimental_telemetry` to surface each LLM call on the Run page in the dashboard
 - Generates marketing copy based on subject and target word count
 - Validates the generated copy meets word count requirements (±10 words)
 - Translates the validated copy to the target language while preserving tone
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
+import { anthropic } from "@ai-sdk/anthropic";
 import { task } from "@trigger.dev/sdk";
 import { generateText } from "ai";
 
@@ -39,7 +39,7 @@ export const generateAndTranslateTask = task({
  run: async (payload: TranslatePayload) => {
  // Step 1: Generate marketing copy
  const generatedCopy = await generateText({
- model: openai("o1-mini"),
+ model: anthropic("claude-sonnet-4-5"),
  messages: [
  {
  role: "system",
@@ -72,7 +72,7 @@ export const generateAndTranslateTask = task({
 
  // Step 2: Translate to target language
  const translatedCopy = await generateText({
- model: openai("o1-mini"),
+ model: anthropic("claude-sonnet-4-5"),
  messages: [
  {
  role: "system",
@@ -103,9 +103,9 @@ On the Test page in the dashboard, select the `generate-and-translate-copy` task
 
 ```json
 {
- marketingSubject: "The controversial new Jaguar electric concept car",
- targetLanguage: "Spanish",
- targetWordCount: 100,
+"marketingSubject": "The controversial new Jaguar electric concept car",
+"targetLanguage": "Spanish",
+"targetWordCount": 100
 }
 ```
 

docs/guides/ai-agents/overview.mdx

@@ -22,6 +22,14 @@ description: "Real world AI agent example tasks using Trigger.dev"
  Generate and maintain GitHub wiki documentation with Claude-powered analysis.
  </Card>
 
+ <Card
+ icon="chart-column"
+ title="ClickHouse chat agent"
+ href="/guides/example-projects/clickhouse-chat-agent"
+ >
+ Build a chat agent that answers questions about your ClickHouse data with charts, tables and maps
+ using `chat.agent()` and generative UI.
+ </Card>
  <Card
  icon="hand"
  title="Human-in-the-loop workflow"
@@ -68,6 +76,20 @@ description: "Real world AI agent example tasks using Trigger.dev"
  </Card>
 </CardGroup>
 
+## Chat agents
+
+Build a durable, multi-turn chat agent with [`chat.agent()`](/ai-chat/overview). A durable session per conversation, with streaming and resumability handled for you.
+
+<CardGroup cols={2}>
+ <Card
+ title="Chat agent"
+ icon="message-bot"
+ href="/guides/ai-agents/chat-agent"
+ >
+ Create a durable, multi-turn chat agent with `chat.agent()`, then add tools to it.
+ </Card>
+</CardGroup>
+
 ## Agent fundamentals
 
 These guides will show you how to set up different types of AI agent workflows with Trigger.dev. The examples take inspiration from Anthropic's blog post on [building effective agents](https://www.anthropic.com/research/building-effective-agents).

docs/guides/ai-agents/respond-and-check-content.mdx

@@ -15,14 +15,14 @@ In this example, we'll create a workflow that simultaneously checks content for
 
 **This task:**
 
-- Uses `generateText` from [Vercel's AI SDK](https://sdk.vercel.ai/docs/introduction) to interact with OpenAI models
-- Uses `experimental_telemetry` to provide LLM logs
+- Uses `generateText` from the [AI SDK](https://ai-sdk.dev/) to call Anthropic's Claude models
+- Uses `experimental_telemetry` to surface each LLM call on the Run page in the dashboard
 - Uses [`batch.triggerByTaskAndWait`](/triggering#batch-triggerbytaskandwait) to run customer response and content moderation tasks in parallel
-- Generates customer service responses using an AI model
+- Answers with `claude-sonnet-4-5` and moderates with the faster, cheaper `claude-haiku-4-5`
 - Simultaneously checks for inappropriate content while generating responses
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
+import { anthropic } from "@ai-sdk/anthropic";
 import { batch, task } from "@trigger.dev/sdk";
 import { generateText } from "ai";
 
@@ -31,7 +31,7 @@ export const generateCustomerResponse = task({
  id: "generate-customer-response",
  run: async (payload: { question: string }) => {
  const response = await generateText({
- model: openai("o1-mini"),
+ model: anthropic("claude-sonnet-4-5"),
  messages: [
  {
  role: "system",
@@ -54,7 +54,7 @@ export const checkInappropriateContent = task({
  id: "check-inappropriate-content",
  run: async (payload: { text: string }) => {
  const response = await generateText({
- model: openai("o1-mini"),
+ model: anthropic("claude-haiku-4-5"),
  messages: [
  {
  role: "system",

docs/guides/ai-agents/route-question.mdx

@@ -16,78 +16,57 @@ In this example, we'll create a workflow that routes a question to a different A
 
 **This task:**
 
-- Uses `generateText` from [Vercel's AI SDK](https://sdk.vercel.ai/docs/introduction) to interact with OpenAI models
-- Uses `experimental_telemetry` in the source verification and historical analysis tasks to provide LLM logs
-- Routes questions using a lightweight model (`o1-mini`) to classify complexity
-- Directs simple questions to `gpt-4o` and complex ones to `gpt-o3-mini`
+- Uses `generateObject` from the [AI SDK](https://ai-sdk.dev/) to classify the question into a typed routing decision
+- Uses `experimental_telemetry` to surface each LLM call on the Run page in the dashboard
+- Classifies complexity with a fast, cheap model (`claude-haiku-4-5`)
+- Directs simple questions to `claude-haiku-4-5` and complex ones to `claude-sonnet-4-5`
 - Returns both the answer and metadata about the routing decision
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
+import { anthropic } from "@ai-sdk/anthropic";
 import { task } from "@trigger.dev/sdk";
-import { generateText } from "ai";
+import { generateObject, generateText } from "ai";
 import { z } from "zod";
 
-// Schema for router response
+// The router's structured decision. generateObject validates the model
+// output against this schema, so there's no manual JSON parsing.
 const routingSchema = z.object({
- model: z.enum(["gpt-4o", "gpt-o3-mini"]),
+ model: z.enum(["claude-haiku-4-5", "claude-sonnet-4-5"]),
  reason: z.string(),
 });
 
-// Router prompt template
-const ROUTER_PROMPT = `You are a routing assistant that determines the complexity of questions.
-Analyze the following question and route it to the appropriate model:
-
-- Use "gpt-4o" for simple, common, or straightforward questions
-- Use "gpt-o3-mini" for complex, unusual, or questions requiring deep reasoning
-
-Respond with a JSON object in this exact format:
-{"model": "gpt-4o" or "gpt-o3-mini", "reason": "your reasoning here"}
-
-Question: `;
-
 export const routeAndAnswerQuestion = task({
  id: "route-and-answer-question",
  run: async (payload: { question: string }) => {
- // Step 1: Route the question
- const routingResponse = await generateText({
- model: openai("o1-mini"),
- messages: [
- {
- role: "system",
- content:
- "You must respond with a valid JSON object containing only 'model' and 'reason' fields. No markdown, no backticks, no explanation.",
- },
- {
- role: "user",
- content: ROUTER_PROMPT + payload.question,
- },
- ],
- temperature: 0.1,
+ // Step 1: Classify the question and pick a model
+ const { object: routing } = await generateObject({
+ model: anthropic("claude-haiku-4-5"),
+ schema: routingSchema,
+ system:
+ "You are a routing assistant. Pick the model best suited to answer the question:\n" +
+ "- claude-haiku-4-5 for simple, common, or straightforward questions\n" +
+ "- claude-sonnet-4-5 for complex, unusual, or questions needing deep reasoning",
+ prompt: payload.question,
  experimental_telemetry: {
  isEnabled: true,
- functionId: "route-and-answer-question",
+ functionId: "route-question",
  },
  });
 
- // Add error handling and cleanup
- let jsonText = routingResponse.text.trim();
- if (jsonText.startsWith("```")) {
- jsonText = jsonText.replace(/```json\n|\n```/g, "");
- }
-
- const routingResult = routingSchema.parse(JSON.parse(jsonText));
-
- // Step 2: Get the answer using the selected model
- const answerResult = await generateText({
- model: openai(routingResult.model),
- messages: [{ role: "user", content: payload.question }],
+ // Step 2: Answer with the selected model
+ const answer = await generateText({
+ model: anthropic(routing.model),
+ prompt: payload.question,
+ experimental_telemetry: {
+ isEnabled: true,
+ functionId: "answer-question",
+ },
  });
 
  return {
- answer: answerResult.text,
- selectedModel: routingResult.model,
- routingReason: routingResult.reason,
+ answer: answer.text,
+ selectedModel: routing.model,
+ routingReason: routing.reason,
  };
  },
 });
@@ -97,7 +76,7 @@ export const routeAndAnswerQuestion = task({
 
 ## Run a test
 
-Triggering our task with a simple question shows it routing to the gpt-4o model and returning the answer with reasoning:
+Triggering our task with a simple question shows it routing to the `claude-haiku-4-5` model and returning the answer with reasoning:
 
 ```json
 {