---
title: ModelMessage
description: Message types for AI SDK Core (API Reference)
url: "https://ai-sdk.dev/v5/docs/reference/ai-sdk-core/model-message"
docs_index: /llms.txt
---

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

`ModelMessage` represents the fundamental message structure used with AI SDK Core functions.
It encompasses various message types that can be used in the `messages` field of any AI SDK Core functions.

You can access the Zod schema for `ModelMessage` with the `modelMessageSchema` export.

## `ModelMessage` Types

### `SystemModelMessage`

A system message that can contain system information.

```typescript
type SystemModelMessage = {
  role: 'system';
  content: string;
};
```

You can access the Zod schema for `SystemModelMessage` with the `systemModelMessageSchema` export.

Use the top-level `system` property instead of a system message for system
instructions. AI SDK functions allow system messages in `prompt` or
`messages` by default with a warning. Set `allowSystemInMessages` to `true`
to suppress the warning, or `false` to reject them. System messages in
`prompt` or `messages` can create a prompt injection attack risk.

### `UserModelMessage`

A user message that can contain text or a combination of text, images, and files.

```typescript
type UserModelMessage = {
  role: 'user';
  content: UserContent;
};

type UserContent = string | Array<TextPart | ImagePart | FilePart>;
```

You can access the Zod schema for `UserModelMessage` with the `userModelMessageSchema` export.

### `AssistantModelMessage`

An assistant message that can contain text, tool calls, or a combination of both.

```typescript
type AssistantModelMessage = {
  role: 'assistant';
  content: AssistantContent;
};

type AssistantContent = string | Array<TextPart | ToolCallPart>;
```

You can access the Zod schema for `AssistantModelMessage` with the `assistantModelMessageSchema` export.

### `ToolModelMessage`

A tool message that contains the result of one or more tool calls.

```typescript
type ToolModelMessage = {
  role: 'tool';
  content: ToolContent;
};

type ToolContent = Array<ToolResultPart>;
```

You can access the Zod schema for `ToolModelMessage` with the `toolModelMessageSchema` export.

## `ModelMessage` Parts

### `TextPart`

Represents a text content part of a prompt. It contains a string of text.

```typescript
export interface TextPart {
  type: 'text';
  /**
   * The text content.
   */
  text: string;
}
```

### `ImagePart`

Represents an image part in a user message.

```typescript
export interface ImagePart {
  type: 'image';

  /**
   * Image data. Can either be:
   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
   * - URL: a URL that points to the image
   */
  image: DataContent | URL;

  /**
   * Optional IANA media type of the image.
   * We recommend leaving this out as it will be detected automatically.
   */
  mediaType?: string;
}
```

### `FilePart`

Represents an file part in a user message.

```typescript
export interface FilePart {
  type: 'file';

  /**
   * File data. Can either be:
   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
   * - URL: a URL that points to the file
   */
  data: DataContent | URL;

  /**
   * Optional filename of the file.
   */
  filename?: string;

  /**
   * IANA media type of the file.
   */
  mediaType: string;
}
```

### `ToolCallPart`

Represents a tool call content part of a prompt, typically generated by the AI model.

```typescript
export interface ToolCallPart {
  type: 'tool-call';

  /**
   * ID of the tool call. This ID is used to match the tool call with the tool result.
   */
  toolCallId: string;

  /**
   * Name of the tool that is being called.
   */
  toolName: string;

  /**
   * Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
   */
  args: unknown;
}
```

### `ToolResultPart`

Represents the result of a tool call in a tool message.

```typescript
export interface ToolResultPart {
  type: 'tool-result';

  /**
   * ID of the tool call that this result is associated with.
   */
  toolCallId: string;

  /**
   * Name of the tool that generated this result.
   */
  toolName: string;

  /**
   * Result of the tool call. This is a JSON-serializable object.
   */
  output: LanguageModelV2ToolResultOutput;

  /**
  Additional provider-specific metadata. They are passed through
  to the provider from the AI SDK and enable provider-specific
  functionality that can be fully encapsulated in the provider.
  */
  providerOptions?: ProviderOptions;
}
```

### `LanguageModelV2ToolResultOutput`

```ts
export type LanguageModelV2ToolResultOutput =
  | { type: 'text'; value: string }
  | { type: 'json'; value: JSONValue }
  | { type: 'error-text'; value: string }
  | { type: 'error-json'; value: JSONValue }
  | {
      type: 'content';
      value: Array<
        | {
            type: 'text';

            /**
          Text content.
            */
            text: string;
          }
        | {
            type: 'media';

            /**
          Base-64 encoded media data.
            */
            data: string;

            /**
          IANA media type.
          @see https://www.iana.org/assignments/media-types/media-types.xhtml
            */
            mediaType: string;
          }
      >;
    };
```

---

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)