|
| 1 | +--- |
| 2 | +title: "Types" |
| 3 | +sidebarTitle: "Types" |
| 4 | +description: "TypeScript types for AI Chat tasks, UI messages, and the frontend transport." |
| 5 | +--- |
| 6 | + |
| 7 | +TypeScript patterns for [AI Chat](/ai-chat/overview). This page will expand over time; it currently documents how to pin a custom AI SDK [`UIMessage`](https://sdk.vercel.ai/docs/reference/ai-sdk-core/ui-message) subtype with `chat.withUIMessage` and align types on the client. |
| 8 | + |
| 9 | +## Custom `UIMessage` with `chat.withUIMessage` |
| 10 | + |
| 11 | +`chat.task()` types the wire payload with the base AI SDK `UIMessage`. That is enough for many apps. |
| 12 | + |
| 13 | +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: |
| 14 | + |
| 15 | +- `onTurnStart`, `onTurnComplete`, and similar hooks expose correctly typed `uiMessages` |
| 16 | +- Stream options like `sendReasoning` align with your message shape |
| 17 | +- The frontend can treat `useChat` messages as the same subtype end-to-end |
| 18 | + |
| 19 | +`chat.withUIMessage<YourUIMessage>(config?)` returns `{ task }`, where `task(...)` accepts the **same options as** [`chat.task()`](/ai-chat/backend#chat-task) but fixes `YourUIMessage` as the UI message type for that chat task. |
| 20 | + |
| 21 | +### Defining a `UIMessage` subtype |
| 22 | + |
| 23 | +Build the type from AI SDK helpers and your tools object: |
| 24 | + |
| 25 | +```ts |
| 26 | +import type { InferUITools, UIDataTypes, UIMessage } from "ai"; |
| 27 | +import { tool } from "ai"; |
| 28 | +import { z } from "zod"; |
| 29 | + |
| 30 | +const myTools = { |
| 31 | + lookup: tool({ |
| 32 | + description: "Look up a record", |
| 33 | + inputSchema: z.object({ id: z.string() }), |
| 34 | + execute: async ({ id }) => ({ id, label: "example" }), |
| 35 | + }), |
| 36 | +}; |
| 37 | + |
| 38 | +type MyChatTools = InferUITools<typeof myTools>; |
| 39 | + |
| 40 | +type MyChatDataTypes = UIDataTypes & { |
| 41 | + "turn-status": { status: "preparing" | "streaming" | "done" }; |
| 42 | +}; |
| 43 | + |
| 44 | +export type MyChatUIMessage = UIMessage<unknown, MyChatDataTypes, MyChatTools>; |
| 45 | +``` |
| 46 | + |
| 47 | +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). |
| 48 | + |
| 49 | +### Backend: `chat.withUIMessage(...).task(...)` |
| 50 | + |
| 51 | +Call `withUIMessage` **once**, then chain `.task({ ... })` instead of `chat.task({ ... })`: |
| 52 | + |
| 53 | +```ts |
| 54 | +import { chat } from "@trigger.dev/sdk/ai"; |
| 55 | +import { streamText, tool } from "ai"; |
| 56 | +import { openai } from "@ai-sdk/openai"; |
| 57 | +import { z } from "zod"; |
| 58 | +import type { MyChatUIMessage } from "./my-chat-types"; |
| 59 | + |
| 60 | +const myTools = { |
| 61 | + lookup: tool({ |
| 62 | + description: "Look up a record", |
| 63 | + inputSchema: z.object({ id: z.string() }), |
| 64 | + execute: async ({ id }) => ({ id, label: "example" }), |
| 65 | + }), |
| 66 | +}; |
| 67 | + |
| 68 | +export const myChat = chat.withUIMessage<MyChatUIMessage>({ |
| 69 | + streamOptions: { |
| 70 | + sendReasoning: true, |
| 71 | + onError: (error) => |
| 72 | + error instanceof Error ? error.message : "Something went wrong.", |
| 73 | + }, |
| 74 | +}).task({ |
| 75 | + id: "my-chat", |
| 76 | + clientDataSchema: z.object({ userId: z.string() }), |
| 77 | + onTurnStart: async ({ uiMessages, writer }) => { |
| 78 | + // uiMessages is MyChatUIMessage[] — custom data parts are typed |
| 79 | + writer.write({ |
| 80 | + type: "data-turn-status", |
| 81 | + data: { status: "preparing" }, |
| 82 | + }); |
| 83 | + }, |
| 84 | + run: async ({ messages, signal }) => { |
| 85 | + return streamText({ |
| 86 | + model: openai("gpt-4o"), |
| 87 | + messages, |
| 88 | + tools: myTools, |
| 89 | + abortSignal: signal, |
| 90 | + }); |
| 91 | + }, |
| 92 | +}); |
| 93 | +``` |
| 94 | + |
| 95 | +### Default stream options |
| 96 | + |
| 97 | +The optional `streamOptions` object becomes the **default** [`uiMessageStreamOptions`](/ai-chat/reference#chat-task-options) for `toUIMessageStream()`. |
| 98 | + |
| 99 | +If you also set `uiMessageStreamOptions` on the inner `.task({ ... })`, the two objects are **shallow-merged** — keys on the **task** win on conflicts. Per-turn overrides via [`chat.setUIMessageStreamOptions()`](/ai-chat/backend#stream-options) still apply on top. |
| 100 | + |
| 101 | +### Frontend: `InferChatUIMessage` |
| 102 | + |
| 103 | +Import the helper type and pass it to `useChat` so `messages` and render logic match the backend: |
| 104 | + |
| 105 | +```tsx |
| 106 | +import { useChat } from "@ai-sdk/react"; |
| 107 | +import { useTriggerChatTransport, type InferChatUIMessage } from "@trigger.dev/sdk/chat/react"; |
| 108 | +import type { myChat } from "./myChat"; |
| 109 | + |
| 110 | +type Msg = InferChatUIMessage<typeof myChat>; |
| 111 | + |
| 112 | +export function Chat() { |
| 113 | + const transport = useTriggerChatTransport<typeof myChat>({ |
| 114 | + task: "my-chat", |
| 115 | + accessToken: getChatToken, |
| 116 | + }); |
| 117 | + |
| 118 | + const { messages } = useChat<Msg>({ transport }); |
| 119 | + |
| 120 | + return messages.map((m) => ( |
| 121 | + <div key={m.id}>{/* m.parts narrowed for your UIMessage subtype */}</div> |
| 122 | + )); |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +You can also import `InferChatUIMessage` from `@trigger.dev/sdk/ai` in non-React modules. |
| 127 | + |
| 128 | +### When plain `chat.task()` is enough |
| 129 | + |
| 130 | +If you do not rely on custom `UIMessage` generics (only default text, reasoning, and built-in tool UI types), **`chat.task()` alone is fine** — no need for `withUIMessage`. |
| 131 | + |
| 132 | +## See also |
| 133 | + |
| 134 | +- [Backend — `chat.task()`](/ai-chat/backend#chat-task) |
| 135 | +- [Frontend — transport & `useChat`](/ai-chat/frontend) |
| 136 | +- [API reference — `chat.withUIMessage`](/ai-chat/reference#chat-withuimessage) |
| 137 | +- [Task-backed AI tools — `ai.toolExecute`](/tasks/schemaTask#task-backed-ai-tools) |
0 commit comments