---
title: Types
description: TypeScript types exported from the chat/ai subpath.
type: reference
related:
  - /docs/ai
  - /docs/ai/ai-sdk-tools
  - /docs/ai/to-ai-messages
---

# Types



Types exported from `chat/ai`. Importing from the subpath keeps the optional `ai` and `zod` peer dependencies out of bundles that don't use them.

```ts
import type {
  AiMessage,
  AiUserMessage,
  AiAssistantMessage,
  AiMessagePart,
  AiTextPart,
  AiImagePart,
  AiFilePart,
  ToAiMessagesOptions,
  ChatBinding,
  ChatTools,
  ChatToolName,
  ChatToolPreset,
  ChatWriteToolName,
  ChatApprovalToolName,
  ApprovalConfig,
  ToolOptions,
  ToolOverrides,
  ReadScope,
} from "chat/ai";
```

## Conversation messages

Used by [`toAiMessages`](/docs/ai/to-ai-messages) and any agent prompt you build by hand. The shapes are structurally compatible with AI SDK's `ModelMessage`, so the result can be passed as `prompt` or `messages`.

### AiMessage

```typescript
type AiMessage = AiUserMessage | AiAssistantMessage;
```

A single normalized turn in a conversation. AI SDK calls take an array of them.

### AiUserMessage

```typescript
interface AiUserMessage {
  role: "user";
  content: string | AiMessagePart[];
}
```

User content can be plain text, or a multipart array when attachments are present.

### AiAssistantMessage

```typescript
interface AiAssistantMessage {
  role: "assistant";
  content: string;
}
```

Assistant turns are always plain strings. `toAiMessages` produces one for any message authored by the bot (`author.isMe === true`).

### AiMessagePart

```typescript
type AiMessagePart = AiTextPart | AiImagePart | AiFilePart;
```

The discriminated union used inside multipart user messages.

### AiTextPart

```typescript
interface AiTextPart {
  type: "text";
  text: string;
}
```

### AiImagePart

```typescript
interface AiImagePart {
  type: "image";
  image: DataContent | URL;
  mediaType?: string;
}
```

`DataContent` matches AI SDK's type: `string | Uint8Array | ArrayBuffer | Buffer`.

### AiFilePart

```typescript
interface AiFilePart {
  type: "file";
  data: DataContent | URL;
  filename?: string;
  mediaType: string;
}
```

`toAiMessages` emits image attachments and text-like attachments (JSON, XML, YAML, source files, and similar) as file parts.

### ToAiMessagesOptions

```typescript
interface ToAiMessagesOptions {
  includeNames?: boolean;
  transformMessage?: (
    aiMessage: AiMessage,
    source: Message
  ) => AiMessage | null | Promise<AiMessage | null>;
  onUnsupportedAttachment?: (
    attachment: Attachment,
    message: Message
  ) => void;
}
```

See [`toAiMessages`](/docs/ai/to-ai-messages) for behavior and examples.

## Tools

Returned by [`createChatTools`](/docs/ai/ai-sdk-tools) and used to configure it.

### ChatBinding

```typescript
type ChatBinding = Chat<any, any>;
```

The [`Chat`](/docs/api/chat) instance the tools dispatch operations against. The generics are loose so that any strongly typed `Chat<TAdapters, TState>` is assignable.

### ChatTools

```typescript
type ChatTools = ReturnType<typeof createChatTools>;
```

Alias for the object returned by `createChatTools`. Use it to type a wrapper or pass the toolset around.

### ChatToolPreset

```typescript
type ChatToolPreset = "reader" | "messenger" | "moderator";
```

Predefined toolset scopes. See [Presets](/docs/ai/ai-sdk-tools#presets) for the exact tool list per preset.

### ChatToolName

```typescript
type ChatToolName =
  | "fetchMessages"
  | "fetchChannelMessages"
  | "fetchThread"
  | "listThreads"
  | "getThreadParticipants"
  | "getChannelInfo"
  | "getUser"
  | "startTyping"
  | "postMessage"
  | "postChannelMessage"
  | "sendDirectMessage"
  | "editMessage"
  | "deleteMessage"
  | "addReaction"
  | "removeReaction"
  | "subscribeThread"
  | "unsubscribeThread";
```

The names of every generated tool. Useful when typing per-tool overrides.

### ChatWriteToolName

```typescript
type ChatWriteToolName =
  | "postMessage"
  | "postChannelMessage"
  | "sendDirectMessage"
  | "editMessage"
  | "deleteMessage"
  | "addReaction"
  | "removeReaction"
  | "subscribeThread"
  | "unsubscribeThread";
```

The names of every mutating tool. Useful when wiring per-tool approval overrides.

### ChatApprovalToolName

```typescript
type ChatApprovalToolName = ChatWriteToolName | "getUser";
```

The names of tools that require approval by default: every mutating tool plus the arbitrary user-profile lookup.

### ApprovalConfig

```typescript
type ApprovalConfig =
  | boolean
  | Partial<Record<ChatApprovalToolName, boolean>>;
```

Controls the `requireApproval` option:

* `true` (default): every write tool and `getUser` need approval.
* `false`: no tool needs approval.
* An object: per-tool overrides. Approval-gated tools you leave out fall back to `true`.

### ToolOptions

```typescript
interface ToolOptions {
  needsApproval?: boolean;
}
```

Common options accepted by every standalone write-tool factory (e.g. `postMessage(chat, { needsApproval: false })`).

### ToolOverrides

```typescript
type ToolOverrides = Partial<
  Pick<
    Tool,
    | "description"
    | "inputExamples"
    | "metadata"
    | "needsApproval"
    | "onInputAvailable"
    | "onInputDelta"
    | "onInputStart"
    | "providerOptions"
    | "strict"
    | "title"
    | "toModelOutput"
  >
>;
```

Per-tool overrides accepted by `createChatTools({ overrides })`. Core fields (`execute`, `inputSchema`, `outputSchema`, `supportsDeferredResults`, `type`, `id`, and `args`) are excluded so tool semantics stay stable across upgrades.

## TanStack AI

The `chat/ai/tanstack` subpath exports its own message and tool shapes, declared locally so nothing from `@tanstack/ai` is imported at runtime:

```ts
import type {
  TanStackMessage,
  TanStackUserMessage,
  TanStackAssistantMessage,
  TanStackContentPart,
  TanStackTextPart,
  TanStackImagePart,
  ToTanStackMessagesOptions,
  TanStackTool,
  TanStackToolOverrides,
  TanStackChatToolsOptions,
} from "chat/ai/tanstack";
```

| Type                        | Purpose                                                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TanStackMessage`           | `TanStackUserMessage \| TanStackAssistantMessage`, structurally assignable to TanStack AI's `ModelMessage`. Returned by `toTanStackMessages`.               |
| `TanStackContentPart`       | `TanStackTextPart \| TanStackImagePart`, the parts inside a multipart user message. Text parts use `content`, image parts carry base64 data under `source`. |
| `ToTanStackMessagesOptions` | `includeNames`, `transformMessage`, and `onUnsupportedAttachment`, mirroring `ToAiMessagesOptions`.                                                         |
| `TanStackTool`              | A plain tool object (`name`, `description`, `inputSchema`, `execute`, optional `needsApproval`, `metadata`, `lazy`) accepted by `chat({ tools })`.          |
| `TanStackToolOverrides`     | The subset of `TanStackTool` that `createTanStackTools({ overrides })` lets you change: `description`, `needsApproval`, `metadata`, `lazy`.                 |
| `TanStackChatToolsOptions`  | Options for `createTanStackTools`: `chat`, `preset`, `requireApproval`, `scope`, `strictScope`, `overrides`.                                                |

`ChatToolName`, `ChatToolPreset`, `ChatWriteToolName`, `ChatApprovalToolName`, `ApprovalConfig`, `ReadScope`, and `ChatBinding` are re-exported from `chat/ai/tanstack` unchanged. Their definitions are in [Tools](#tools) above, and `ReadScope` is described in the [`createChatTools` API](/docs/ai/ai-sdk-tools#api). The TanStack-specific shapes are defined in full on the [TanStack AI](/docs/ai/tanstack-ai#types) page.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)