`ModelMessage`

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.

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

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

Use the top-level instructions property instead of a system message for system instructions. AI SDK functions reject system messages in prompt or messages by default unless allowSystemInMessages is set to true. Opting in can create a prompt injection risk if users can inject system messages.

`UserModelMessage`

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

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.

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

type AssistantContent = string | Array<TextPart | CustomPart | 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.

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.

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

`ImagePart`
Deprecated

ImagePart is deprecated. Use FilePart with mediaType: 'image' (or a more specific image/* subtype) instead.

Represents an image part in a user message.

/**
 * @deprecated Use `FilePart` with `mediaType: 'image'` instead.
 */
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
   * - ProviderReference: a provider reference from `uploadFile`
   */
  image: DataContent | URL | ProviderReference;

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

`FilePart`

Represents a file part in a user message.

export interface FilePart {
  type: 'file';

  /**
   * File data. Use the tagged `FileData` shape.
   * Bare `DataContent`, `URL`, and `ProviderReference` shorthands are also supported.
   */
  data: FileData | DataContent | URL | ProviderReference;

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

  /**
   * Either a full IANA media type (`type/subtype`, e.g. `image/png`) or just
   * the top-level IANA segment (e.g. `image`, `audio`, `video`, `text`).
   */
  mediaType: string;
}

export type FileData =
  // Raw bytes as a base64 string, Uint8Array, ArrayBuffer, or Buffer.
  | { type: 'data'; data: DataContent }
  // A URL that points to the file.
  | { type: 'url'; url: URL }
  // A provider reference from `uploadFile`.
  | { type: 'reference'; reference: ProviderReference }
  // Inline text content.
  | { type: 'text'; text: string };

`CustomPart`

Represents a provider-specific custom content part. The kind field identifies the content type in the format {provider}.{provider-type}.

export interface CustomPart {
  type: 'custom';

  /**
   * The kind of custom content, in the format `{provider}.{provider-type}`.
   */
  kind: `${string}.${string}`;

  /**
   * Additional provider-specific metadata.
   */
  providerOptions?: ProviderOptions;
}

`ToolCallPart`

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

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.

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: LanguageModelV4ToolResultOutput;

  /**
  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;
}

`LanguageModelV4ToolResultOutput`

/**
 * Output of a tool result.
 */
export type ToolResultOutput =
  | {
      /**
       * Text tool output that should be directly sent to the API.
       */
      type: 'text';
      value: string;

      /**
       * Provider-specific options.
       */
      providerOptions?: ProviderOptions;
    }
  | {
      type: 'json';
      value: JSONValue;

      /**
       * Provider-specific options.
       */
      providerOptions?: ProviderOptions;
    }
  | {
      /**
       * Type when the user has denied the execution of the tool call.
       */
      type: 'execution-denied';

      /**
       * Optional reason for the execution denial.
       */
      reason?: string;

      /**
       * Provider-specific options.
       */
      providerOptions?: ProviderOptions;
    }
  | {
      type: 'error-text';
      value: string;

      /**
       * Provider-specific options.
       */
      providerOptions?: ProviderOptions;
    }
  | {
      type: 'error-json';
      value: JSONValue;

      /**
       * Provider-specific options.
       */
      providerOptions?: ProviderOptions;
    }
  | {
      type: 'content';
      value: Array<
        | {
            type: 'text';

            /**
Text content.
*/
            text: string;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * @deprecated Use image-data or file-data instead.
             */
            type: 'media';
            data: string;
            mediaType: string;
          }
        | {
            type: 'file-data';

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

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

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

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            type: 'file-url';

            /**
             * URL of the file.
             */
            url: string;

            /**
             * IANA media type of the file.
             * Used by providers to determine how to handle the file (e.g. image vs document).
             * Optional; if omitted, the SDK will attempt to infer it from the URL file extension.
             */
            mediaType?: string;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * @deprecated Use file-reference instead.
             */
            type: 'file-id';

            /**
             * ID of the file.
             *
             * If you use multiple providers, you need to
             * specify the provider specific ids using
             * the Record option. The key is the provider
             * name, e.g. 'openai' or 'anthropic'.
             */
            fileId: string | Record<string, string>;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            type: 'file-reference';

            /**
             * Provider-specific references for the file.
             * The key is the provider name, e.g. 'openai' or 'anthropic'.
             */
            providerReference: ProviderReference;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * @deprecated Use file-data instead.
             * Images that are referenced using base64 encoded data.
             */
            type: 'image-data';

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

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

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * @deprecated Use file-url instead.
             * Images that are referenced using a URL.
             */
            type: 'image-url';

            /**
             * URL of the image.
             */
            url: string;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * @deprecated Use file-reference instead.
             * Images that are referenced using a provider file id.
             */
            type: 'image-file-id';

            /**
             * Image that is referenced using a provider file id.
             *
             * If you use multiple providers, you need to
             * specify the provider specific ids using
             * the Record option. The key is the provider
             * name, e.g. 'openai' or 'anthropic'.
             */
            fileId: string | Record<string, string>;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * @deprecated Use file-reference instead.
             * Images that are referenced using a provider reference.
             */
            type: 'image-file-reference';

            /**
             * Provider-specific references for the image file.
             * The key is the provider name, e.g. 'openai' or 'anthropic'.
             */
            providerReference: ProviderReference;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * Custom content part. This can be used to implement
             * provider-specific content parts.
             */
            type: 'custom';

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
      >;
    };