docs: 4.8.0 follow-ups for agent examples, MCP secrets and self-hosted webhooks

Docs updates for 4.8.0: `chat.agent` examples use the `streamText`
passed to `run()`, the webhook secret MCP tools document
`previousSecretTtlSeconds`, self-hosting docs cover turning on webhooks
and `KUBERNETES_POD_RESERVED_SOURCE_PORTS`, and the agents overview
introduces channels.

Mono-RevId: 3eb1ed33ef2e0e21cd1197391b71a3a7c57e9785

Author: ericallam

docs/ai-chat/chat-local.mdx

@@ -16,7 +16,7 @@ Declare locals at module level with a unique `id`, then initialize them inside a
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, tool, stepCountIs } from "ai";
+import { tool, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 import { db } from "@/lib/db";
@@ -44,7 +44,7 @@ export const myChat = chat.agent({
       messageCount: user.messageCount,
     });
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     userContext.messageCount++;
 
     return streamText({
@@ -88,7 +88,7 @@ When you use `ai.toolExecute()` inside AI SDK `tool()` to expose a subtask, chat
 ```ts
 import { chat, ai } from "@trigger.dev/sdk/ai";
 import { schemaTask } from "@trigger.dev/sdk";
-import { streamText, tool } from "ai";
+import { tool, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -115,7 +115,7 @@ export const myChat = chat.agent({
   onBoot: async ({ clientData }) => {
     userContext.init({ name: "Alice", plan: "pro" });
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,

docs/ai-chat/fast-starts.mdx

@@ -80,7 +80,7 @@ export const myChat = chat.agent({
     if (preloaded) return; // Already initialized in onPreload
     // ... fallback initialization for non-preloaded runs
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });

docs/ai-chat/overview.mdx

@@ -56,11 +56,12 @@ See [Quick Start](/ai-chat/quick-start) for the matching server actions and a ru
 
 ## How it fits together
 
-Three primitives, related but distinct:
+Four primitives, related but distinct:
 
 - **Chat agents** — the SDK surface you define with [`chat.agent()`](/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](/ai-chat/sessions).
 - **Sub-agents** — Delegate work from one agent to another via [`AgentChat`](/ai-chat/patterns/sub-agents). The sub-agent runs as its own durable agent on its own session; its response streams back through the parent as preliminary tool results, 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()`](/webhooks/slack) and [`linear()`](/webhooks/linear) turn an agent into a Slack or Linear agent, and [`chat.channels.custom()`](/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
 

docs/ai-chat/patterns/database-persistence.mdx

@@ -226,7 +226,7 @@ export const myChat = chat.agent({
       }),
     ]);
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -254,7 +254,7 @@ End-to-end implementation across the three files involved: agent task, server ac
 <CodeGroup>
 ```ts trigger/chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs } from "ai";
+import { stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 import { db } from "@/lib/db";
@@ -296,7 +296,7 @@ export const myChat = chat.agent({
       }),
     ]);
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,

docs/ai-chat/patterns/native-compaction.mdx

@@ -31,7 +31,7 @@ The fix: read the `appliedEdits` counts as they stream in `onStepFinish`, then a
 
 ```ts /trigger/native-persist.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs, tool, type UIMessage } from "ai";
+import { stepCountIs, tool, type UIMessage } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -75,7 +75,7 @@ export const nativePersist = chat.agent({
   id: "native-persist",
   idleTimeoutInSeconds: 120,
   tools: { fetchRecord },
-  run: async ({ messages, chatId, tools, signal }) => {
+  run: async ({ messages, chatId, tools, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,
@@ -132,7 +132,7 @@ OpenAI's `store: true` keeps the thread server-side and returns a `responseId`.
 
 ```ts /trigger/openai-store.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs, type ModelMessage } from "ai";
+import { stepCountIs, type ModelMessage } from "ai";
 import { openai } from "@ai-sdk/openai";
 
 // Persist the stored-response handle between turns. Replace with your database.
@@ -151,7 +151,7 @@ function messagesSinceLastAssistant(messages: ModelMessage[]): ModelMessage[] {
 export const openaiStore = chat.agent({
   id: "openai-store",
   idleTimeoutInSeconds: 120,
-  run: async ({ messages, chatId, signal }) => {
+  run: async ({ messages, chatId, signal, streamText }) => {
     const native = nativeStore.get(chatId);
     const outbound = native ? messagesSinceLastAssistant(messages) : messages;
 
@@ -186,7 +186,7 @@ A native handle is a per-provider cache. An OpenAI `previousResponseId` means no
 
 ```ts /trigger/resilient-chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, generateText, stepCountIs, generateId, type ModelMessage } from "ai";
+import { generateText, stepCountIs, generateId, type ModelMessage } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { openai } from "@ai-sdk/openai";
 
@@ -241,7 +241,7 @@ export const resilientChat = chat.agent({
     if (chatId) nativeStore.delete(chatId);
   },
 
-  run: async ({ messages, chatId, signal }) => {
+  run: async ({ messages, chatId, signal, streamText }) => {
     let lastError: unknown;
     for (const providerId of FALLBACK_ORDER) {
       const native = nativeStore.get(chatId);

docs/ai-chat/patterns/sub-agents.mdx

@@ -275,7 +275,7 @@ const tools = { research: researchTool };
 export const myAgent = chat.agent({
   id: "orchestrator",
   tools, // declare here so toModelOutput survives across turns
-  run: async ({ messages, tools, stopSignal }) => {
+  run: async ({ messages, tools, stopSignal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-6"),
       messages,

docs/ai-chat/patterns/version-upgrades.mdx

@@ -100,7 +100,7 @@ On the agent side, declare which versions the current code supports:
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText } from "ai";
+
 import { anthropic } from "@ai-sdk/anthropic";
 
 // The set of frontend protocol versions this agent code supports.
@@ -121,7 +121,7 @@ export const myChat = chat
         chat.requestUpgrade();
       }
     },
-    run: async ({ messages, signal }) => {
+    run: async ({ messages, signal, streamText }) => {
       return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
     },
   });
@@ -183,7 +183,7 @@ export const myChat = chat
         chat.requestUpgrade();
       }
     },
-    run: async ({ messages, signal }) => {
+    run: async ({ messages, signal, streamText }) => {
       return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
     },
   });

docs/ai-chat/side-channels.mdx

@@ -38,12 +38,12 @@ Inside a `chat.agent` run, `chat.channel(...)` opens a channel on the current ru
 
 ```ts /trigger/browser-agent.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText } from "ai";
+
 import { screenshots } from "./channels";
 
 export const browserAgent = chat.agent({
   id: "browser-agent",
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     const frames = chat.channel(screenshots);
 
     frames.in.on((control) => setPaused(control.paused)); // control: ViewportControl

docs/ai-chat/types.mdx

@@ -56,7 +56,7 @@ Call `withUIMessage` **once**, then chain `.agent({ ... })` instead of `chat.age
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, tool } from "ai";
+import { tool } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 import type { MyChatUIMessage } from "./my-chat-types";
@@ -90,7 +90,7 @@ export const myChat = chat
         data: { status: "preparing" },
       });
     },
-    run: async ({ messages, tools, signal }) => {
+    run: async ({ messages, tools, signal, streamText }) => {
       // `tools` is myTools, typed, handed back on the payload
       return streamText({
         model: anthropic("claude-sonnet-4-5"),
@@ -156,7 +156,7 @@ export const myChat = chat
       // clientData is typed as { userId: string; model?: string }
       await initUser(clientData.userId);
     },
-    run: async ({ messages, clientData, signal }) => {
+    run: async ({ messages, clientData, signal, streamText }) => {
       return streamText({
         model: getModel(clientData.model),
         messages,
@@ -193,7 +193,7 @@ export const myChat = chat
   })
   .agent({
     id: "my-chat",
-    run: async ({ messages, signal }) => {
+    run: async ({ messages, signal, streamText }) => {
       return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
     },
   });
@@ -218,7 +218,7 @@ chat
       // Runs second — task-specific logic
       await createChatRecord(event.chatId);
     },
-    run: async ({ messages, signal }) => {
+    run: async ({ messages, signal, streamText }) => {
       return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
     },
   });

docs/ai/prompts.mdx

@@ -219,8 +219,9 @@ Prompts integrate with `chat.agent()` via `chat.prompt` — a run-scoped store f
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
 import { prompts } from "@trigger.dev/sdk";
-import { streamText, createProviderRegistry } from "ai";
+import { createProviderRegistry, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
 
 const registry = createProviderRegistry({ anthropic });
 
@@ -234,13 +235,14 @@ const systemPrompt = prompts.define({
 
 export const myChat = chat.agent({
   id: "my-chat",
+  registry,
+  clientDataSchema: z.object({ name: z.string() }),
   onChatStart: async ({ clientData }) => {
     const resolved = await systemPrompt.resolve({ name: clientData.name });
     chat.prompt.set(resolved);
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
-      ...chat.toStreamTextOptions({ registry }),
       messages,
       abortSignal: signal,
       stopWhen: stepCountIs(15),
@@ -249,9 +251,11 @@ export const myChat = chat.agent({
 });
 ```
 
+The `streamText` passed to `run()` applies the stored prompt: its system text, its model (resolved through the agent's `registry`), its `config`, and telemetry that links each generation to the prompt version. Options you pass at the call site win, apart from `system`, which throws when a prompt already sets one.
+
 ### chat.toStreamTextOptions()
 
-Returns an options object ready to spread into `streamText()`. When a prompt is stored via `chat.prompt.set()`, it includes:
+Inside a `chat.agent` you don't need this: the `streamText` passed to `run()` applies the same options. Use `chat.toStreamTextOptions()` when you call `streamText` yourself, as in a [custom agent](/ai-chat/custom-agents). It returns an options object ready to spread into `streamText()`. When a prompt is stored via `chat.prompt.set()`, it includes:
 
 - `system` — the compiled prompt text
 - `model` — resolved via the `registry` when provided
@@ -277,14 +281,13 @@ const options = chat.toStreamTextOptions();
 Access the stored prompt from anywhere in the run:
 
 ```ts
-run: async ({ messages, signal }) => {
+run: async ({ messages, signal, streamText }) => {
   const prompt = chat.prompt(); // Throws if not set
   console.log(prompt.text);     // The compiled prompt
   console.log(prompt.model);    // "anthropic:claude-sonnet-4-5"
   console.log(prompt.version);  // 3
 
   return streamText({
-    ...chat.toStreamTextOptions({ registry }),
     messages,
     abortSignal: signal,
     stopWhen: stepCountIs(15),