@trigger.dev/sdk 4.5.0-rc.5 → 4.5.0-rc.7

package/docs/ai-chat/tools.mdx

@@ -0,0 +1,191 @@
+---
+title: "Tools"
+sidebarTitle: "Tools"
+description: "Declare tools on chat.agent so toModelOutput survives across turns, get them back typed in run(), and type your messages from them."
+---
+
+import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
+
+<RcBanner />
+
+`chat.agent` doesn't call the model for you. Your tools still go to [`streamText`](https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling) inside `run()`. But you should **also declare them on the agent config**:
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { streamText, stepCountIs, tool } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
+
+const tools = {
+  searchDocs: tool({
+    description: "Search the docs.",
+    inputSchema: z.object({ query: z.string() }),
+    execute: async ({ query }) => searchIndex(query),
+  }),
+};
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  tools, // ← declare here
+  run: async ({ messages, tools, signal }) =>
+    streamText({
+      ...chat.toStreamTextOptions({ tools }), // ← the same set, handed back on the payload
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+      stopWhen: stepCountIs(15),
+    }),
+});
+```
+
+Declaring `tools` on the config does two things you can't get by passing them to `streamText` alone:
+
+- It threads your tools into the SDK's internal message conversion, so each tool's [`toModelOutput`](https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling#tomodeloutput) is re-applied when prior-turn history is re-converted (see [`toModelOutput` across turns](#tomodeloutput-across-turns)).
+- It hands the resolved set back, typed, on the `run()` payload as `tools`, so you declare them once and don't re-import the map.
+
+## Where tools go
+
+There are three places a tool set shows up. Declare once, reuse:
+
+| Surface | What it's for |
+| --- | --- |
+| `chat.agent({ tools })` | Re-applies `toModelOutput` on prior-turn history; hands the set back typed on the `run()` payload. |
+| `chat.toStreamTextOptions({ tools })` | Detects which tool calls need [HITL approval](/ai-chat/patterns/human-in-the-loop) (`needsApproval`) and merges any auto-injected [skill](/ai-chat/patterns/skills) tools. |
+| `streamText({ tools })` | What the model actually calls. `chat.toStreamTextOptions({ tools })` already sets this, so spread it instead of passing `tools` twice. |
+
+The canonical pattern: declare `tools` on the config, read them back from the `run()` payload, and pass that to `chat.toStreamTextOptions({ tools })`. One declaration flows everywhere.
+
+<Tip>
+  Conversion only reads each tool's `inputSchema` and `toModelOutput`, never `execute`. If you keep heavy `execute` dependencies out of a module (for bundle reasons), you can declare a lightweight schema-only tool map on the config and add the executes where you call `streamText`.
+</Tip>
+
+## `toModelOutput` across turns
+
+`toModelOutput` transforms a tool's result before it enters the model's context, turning raw image bytes into an image content part, or compressing a long sub-agent transcript into a one-line summary. The full result still streams to the frontend; the model only sees the transformed version.
+
+The catch is multi-turn. After each turn, `chat.agent` persists the conversation as `UIMessage[]` and re-converts it to model messages at the start of the next turn. That conversion needs your tools to find each `toModelOutput`. **If you only pass tools to `streamText` and not to the config, the transform runs on turn 1 but is skipped on every later turn.** The raw output gets stringified back into the prompt instead, and the model loses the transformed view.
+
+Declaring `tools` on the config fixes this: the SDK threads them into the conversion, so `toModelOutput` is re-applied on every turn.
+
+```ts
+const tools = {
+  renderChart: tool({
+    description: "Render a chart and return it as an image.",
+    inputSchema: z.object({ spec: z.string() }),
+    execute: async ({ spec }) => renderToPng(spec), // raw bytes
+    // The model should see an image part, not base64 bytes:
+    toModelOutput: ({ output }) => ({
+      type: "content",
+      value: [{ type: "media", mediaType: "image/png", data: output.base64 }],
+    }),
+  }),
+};
+
+export const chartChat = chat.agent({
+  id: "chart-chat",
+  tools, // ← without this, the image is "remembered" on turn 1 and gone from turn 2
+  run: async ({ messages, tools, signal }) =>
+    streamText({
+      ...chat.toStreamTextOptions({ tools }),
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+      stopWhen: stepCountIs(15),
+    }),
+});
+```
+
+## Static or per-turn tools
+
+`tools` accepts either a static `ToolSet` or a function that returns one per turn, for tools that depend on the user, a feature flag, or anything in the turn context:
+
+```ts
+export const myChat = chat
+  .withClientData({ schema: z.object({ userId: z.string(), plan: z.string() }) })
+  .agent({
+    id: "my-chat",
+    tools: ({ clientData }) => ({
+      searchDocs,
+      ...(clientData?.plan === "pro" ? { deepResearch } : {}),
+    }),
+    run: async ({ messages, tools, signal }) =>
+      streamText({
+        ...chat.toStreamTextOptions({ tools }),
+        model: anthropic("claude-sonnet-4-5"),
+        messages,
+        abortSignal: signal,
+        stopWhen: stepCountIs(15),
+      }),
+  });
+```
+
+The function receives a `ResolveToolsEvent` and runs once per turn (after `clientData` is parsed):
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `chatId` | `string` | The chat session ID. |
+| `turn` | `number` | The current turn number (0-indexed). |
+| `continuation` | `boolean` | Whether this run is continuing an existing chat. |
+| `clientData` | `TClientData` | Parsed client data from the frontend. |
+
+The resolved set is what lands on the `run()` payload's `tools`.
+
+## Typed tools in `run()`
+
+The `run()` payload's `tools` is typed to whatever you declared, so you can pass it straight through without re-importing the map:
+
+```ts
+run: async ({ messages, tools, signal }) => {
+  // `tools` is typed as your tool set, not a broad `ToolSet`
+  return streamText({
+    ...chat.toStreamTextOptions({ tools }),
+    model: anthropic("claude-sonnet-4-5"),
+    messages,
+    abortSignal: signal,
+  });
+};
+```
+
+When no `tools` are declared, the payload's `tools` is an empty object and behaves exactly as before, so declaring tools is fully opt-in.
+
+## Typing messages from your tools
+
+To get typed tool parts (`tool-${name}` with typed input/output) on your `UIMessage`, in hooks like `onTurnComplete` and on the frontend, derive the message type from your tool set with `InferChatUIMessageFromTools`:
+
+```ts
+import type { InferChatUIMessageFromTools } from "@trigger.dev/sdk/ai";
+
+const tools = { searchDocs, renderChart };
+
+export type ChatUiMessage = InferChatUIMessageFromTools<typeof tools>;
+```
+
+This is shorthand for `UIMessage<unknown, UIDataTypes, InferUITools<typeof tools>>`. Pin it on the agent with [`chat.withUIMessage<ChatUiMessage>()`](/ai-chat/types#custom-uimessage-with-chat-withuimessage) and reuse it on the client. If you also have custom `data-*` parts, build the `UIMessage` generic directly instead. See [Types](/ai-chat/types).
+
+## Skills
+
+[Agent skills](/ai-chat/patterns/skills) are auto-injected as tools (`loadSkill`, `readFile`, `bash`) by `chat.toStreamTextOptions()`. They're separate from your config `tools`: declare your own tools on the config (so their `toModelOutput` survives across turns), and let `toStreamTextOptions` merge the skill tools on top at call time. Skill tools don't define `toModelOutput`, so they don't need to be on the config.
+
+## Manual turn loops (`chat.customAgent`)
+
+The `tools` config option belongs to the managed [`chat.agent`](/ai-chat/backend#chat-agent). When you drive the loop yourself with [`chat.customAgent`](/ai-chat/custom-agents#chat-customagent) (or build messages from `chat.history`), you own the conversion, so pass your tools to `convertToModelMessages` directly to get the same cross-turn `toModelOutput` behavior:
+
+```ts
+import { convertToModelMessages, streamText } from "ai";
+
+// Inside your loop, with `tools` in scope:
+const uiMessages = chat.history.all();
+const messages = await convertToModelMessages(uiMessages, {
+  tools,
+  ignoreIncompleteToolCalls: true,
+});
+
+return streamText({ model: anthropic("claude-sonnet-4-5"), messages, tools });
+```
+
+## Learn more
+
+- [Human-in-the-loop](/ai-chat/patterns/human-in-the-loop): tools that pause for approval.
+- [Sub-agents](/ai-chat/patterns/sub-agents): tools that delegate to other agents and compress their output with `toModelOutput`.
+- [Tool result auditing](/ai-chat/patterns/tool-result-auditing): logging tool results as they resolve.
+- [AI SDK: Tools and tool calling](https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling).

package/docs/ai-chat/types.mdx

@@ -0,0 +1,242 @@
+---
+title: "Types"
+sidebarTitle: "Types"
+description: "TypeScript types for AI Agents, UI messages, and the frontend transport."
+---
+
+import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
+
+<RcBanner />
+
+TypeScript patterns for [AI Chat](/ai-chat/overview). This page covers how to pin a custom AI SDK [`UIMessage`](https://sdk.vercel.ai/docs/reference/ai-sdk-core/ui-message) subtype with `chat.withUIMessage`, fix a typed `clientData` schema with `chat.withClientData`, chain builder-level hooks, and align types on the client.
+
+## Custom `UIMessage` with `chat.withUIMessage`
+
+`chat.agent()` types the wire payload with the base AI SDK `UIMessage`. That is enough for many apps.
+
+When you add **custom `data-*` parts** (via `chat.stream` / `writer`) or a **typed tool map** (e.g. `InferUITools<typeof tools>`), you want a **narrower** `UIMessage` generic so that:
+
+- `onTurnStart`, `onTurnComplete`, and similar hooks expose correctly typed `uiMessages`
+- Stream options like `sendReasoning` align with your message shape
+- The frontend can treat `useChat` messages as the same subtype end-to-end
+
+`chat.withUIMessage<YourUIMessage>(config?)` returns a [ChatBuilder](#chatbuilder) where `.agent(...)` accepts the **same options as** [`chat.agent()`](/ai-chat/backend#chat-agent) but fixes `YourUIMessage` as the UI message type for that chat agent.
+
+### Defining a `UIMessage` subtype
+
+Build the type from AI SDK helpers and your tools object:
+
+```ts
+import type { InferUITools, UIDataTypes, UIMessage } from "ai";
+import { tool, stepCountIs } from "ai";
+import { z } from "zod";
+
+const myTools = {
+  lookup: tool({
+    description: "Look up a record",
+    inputSchema: z.object({ id: z.string() }),
+    execute: async ({ id }) => ({ id, label: "example" }),
+  }),
+};
+
+type MyChatTools = InferUITools<typeof myTools>;
+
+type MyChatDataTypes = UIDataTypes & {
+  "turn-status": { status: "preparing" | "streaming" | "done" };
+};
+
+export type MyChatUIMessage = UIMessage<unknown, MyChatDataTypes, MyChatTools>;
+```
+
+<Tip>
+  If you don't need custom `data-*` parts, [`InferChatUIMessageFromTools<typeof myTools>`](/ai-chat/tools#typing-messages-from-your-tools) from `@trigger.dev/sdk/ai` collapses the tools half into one line (it's shorthand for `UIMessage<unknown, UIDataTypes, InferUITools<typeof myTools>>`).
+</Tip>
+
+Task-backed tools should use AI SDK [`tool()`](https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling) with `execute: ai.toolExecute(schemaTask)` where needed — see [Task-backed AI tools](/tasks/schemaTask#task-backed-ai-tools).
+
+### Backend: `chat.withUIMessage(...).agent(...)`
+
+Call `withUIMessage` **once**, then chain `.agent({ ... })` instead of `chat.agent({ ... })`. You can also chain `.withClientData()` and hook methods before `.agent()`:
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { streamText, tool } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
+import type { MyChatUIMessage } from "./my-chat-types";
+
+const myTools = {
+  lookup: tool({
+    description: "Look up a record",
+    inputSchema: z.object({ id: z.string() }),
+    execute: async ({ id }) => ({ id, label: "example" }),
+  }),
+};
+
+export const myChat = chat
+  .withUIMessage<MyChatUIMessage>({
+    streamOptions: {
+      sendReasoning: true,
+      onError: (error) =>
+        error instanceof Error ? error.message : "Something went wrong.",
+    },
+  })
+  .withClientData({
+    schema: z.object({ userId: z.string() }),
+  })
+  .agent({
+    id: "my-chat",
+    tools: myTools,
+    onTurnStart: async ({ uiMessages, writer }) => {
+      // uiMessages is MyChatUIMessage[] — custom data parts are typed
+      writer.write({
+        type: "data-turn-status",
+        data: { status: "preparing" },
+      });
+    },
+    run: async ({ messages, tools, signal }) => {
+      // `tools` is myTools, typed, handed back on the payload
+      return streamText({
+        model: anthropic("claude-sonnet-4-5"),
+        messages,
+        tools,
+        abortSignal: signal,
+        stopWhen: stepCountIs(15),
+      });
+    },
+  });
+```
+
+### Default stream options
+
+The optional `streamOptions` object becomes the **default** [`uiMessageStreamOptions`](/ai-chat/reference#chatagentoptions) for `toUIMessageStream()`.
+
+If you also set `uiMessageStreamOptions` on the inner `.agent({ ... })`, the two objects are **shallow-merged** — keys on the **agent** win on conflicts. Per-turn overrides via [`chat.setUIMessageStreamOptions()`](/ai-chat/backend#stream-options) still apply on top.
+
+### Frontend: `InferChatUIMessage`
+
+Import the helper type and pass it to `useChat` so `messages` and render logic match the backend:
+
+```tsx
+import { useChat } from "@ai-sdk/react";
+import { useTriggerChatTransport, type InferChatUIMessage } from "@trigger.dev/sdk/chat/react";
+import type { myChat } from "./myChat";
+
+type Msg = InferChatUIMessage<typeof myChat>;
+
+export function Chat() {
+  const transport = useTriggerChatTransport<typeof myChat>({
+    task: "my-chat",
+    accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+    startSession: ({ chatId, clientData }) =>
+      startChatSession({ chatId, clientData }),
+  });
+
+  const { messages } = useChat<Msg>({ transport });
+
+  return messages.map((m) => (
+    <div key={m.id}>{/* m.parts narrowed for your UIMessage subtype */}</div>
+  ));
+}
+```
+
+You can also import `InferChatUIMessage` from `@trigger.dev/sdk/ai` in non-React modules.
+
+## Typed client data with `chat.withClientData`
+
+`chat.withClientData({ schema })` returns a [ChatBuilder](#chatbuilder) that fixes the client data schema. All hooks and `run` receive typed `clientData` without needing `clientDataSchema` in `.agent()` options.
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { z } from "zod";
+
+export const myChat = chat
+  .withClientData({
+    schema: z.object({ userId: z.string(), model: z.string().optional() }),
+  })
+  .agent({
+    id: "my-chat",
+    onPreload: async ({ clientData }) => {
+      // clientData is typed as { userId: string; model?: string }
+      await initUser(clientData.userId);
+    },
+    run: async ({ messages, clientData, signal }) => {
+      return streamText({
+        model: getModel(clientData.model),
+        messages,
+        abortSignal: signal,
+        stopWhen: stepCountIs(15),
+      });
+    },
+  });
+```
+
+## ChatBuilder
+
+Both `chat.withUIMessage()` and `chat.withClientData()` return a **ChatBuilder** — a chainable object that accumulates configuration before creating the agent with `.agent()`.
+
+Builder methods can be chained in any order:
+
+```ts
+export const myChat = chat
+  .withUIMessage<MyChatUIMessage>({
+    streamOptions: { sendReasoning: true },
+  })
+  .withClientData({
+    schema: z.object({ userId: z.string() }),
+  })
+  .onChatSuspend(async ({ ctx }) => {
+    await disposeCodeSandbox(ctx.run.id);
+  })
+  .onChatResume(async ({ ctx }) => {
+    warmCache(ctx.run.id);
+  })
+  .agent({
+    id: "my-chat",
+    run: async ({ messages, signal }) => {
+      return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
+    },
+  });
+```
+
+### Builder-level hooks
+
+All [lifecycle hooks](/ai-chat/lifecycle-hooks) can be set on the builder: `onPreload`, `onChatStart`, `onTurnStart`, `onBeforeTurnComplete`, `onTurnComplete`, `onCompacted`, `onChatSuspend`, `onChatResume`.
+
+Builder hooks and task-level hooks **coexist**. When both are defined for the same event, the builder hook runs first, then the task hook:
+
+```ts
+chat
+  .withUIMessage<MyChatUIMessage>()
+  .onPreload(async (event) => {
+    // Runs first — shared setup across tasks using this builder
+    await initializeSharedState(event.chatId);
+  })
+  .agent({
+    id: "my-chat",
+    onPreload: async (event) => {
+      // Runs second — task-specific logic
+      await createChatRecord(event.chatId);
+    },
+    run: async ({ messages, signal }) => {
+      return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
+    },
+  });
+```
+
+<Tip>
+  Set types first (`.withUIMessage()`, `.withClientData()`), then hooks. Hook parameters are typed based on the builder's current generics — so hooks registered after `.withClientData()` get typed `clientData`.
+</Tip>
+
+### When plain `chat.agent()` is enough
+
+If you do not rely on custom `UIMessage` generics (only default text, reasoning, and built-in tool UI types), **`chat.agent()` alone is fine** — no need for `withUIMessage`.
+
+## See also
+
+- [Backend — `chat.agent()`](/ai-chat/backend#chat-agent)
+- [Lifecycle hooks](/ai-chat/lifecycle-hooks)
+- [Frontend — transport & `useChat`](/ai-chat/frontend)
+- [API reference — `chat.withUIMessage`](/ai-chat/reference#chat-withuimessage)
+- [API reference — `chat.withClientData`](/ai-chat/reference#chat-withclientdata)
+- [Task-backed AI tools — `ai.toolExecute`](/tasks/schemaTask#task-backed-ai-tools)