docs: add core message reference (vercel#2330)

content/docs/07-reference/ai-sdk-core/30-core-message.mdx

@@ -0,0 +1,151 @@
+---
+title: CoreMessage
+description: Core message types for AI interactions (API Reference)
+---
+
+# `CoreMessage`
+
+`CoreMessage` 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.
+
+## `CoreMessage` Types
+
+### `CoreSystemMessage`
+
+A system message that can contain system information.
+
+```typescript
+type CoreSystemMessage = {
+  role: 'system';
+  content: string;
+};
+```
+
+<Note>
+  {' '}
+  Using the "system" part of the prompt is strongly recommended to enhance resilience
+  against prompt injection attacks and because not all providers support multiple
+  system messages.
+</Note>
+
+### `CoreUserMessage`
+
+A user message that can contain text or a combination of text and images.
+
+```typescript
+type CoreUserMessage = {
+  role: 'user';
+  content: UserContent;
+};
+
+type UserContent = string | Array<TextPart | ImagePart>;
+```
+
+### `CoreAssistantMessage`
+
+An assistant message that can contain text, tool calls, or a combination of both.
+
+```typescript
+type CoreAssistantMessage = {
+  role: 'assistant';
+  content: AssistantContent;
+};
+
+type AssistantContent = string | Array<TextPart | ToolCallPart>;
+```
+
+### `CoreToolMessage`
+
+A tool message that contains the result of one or more tool calls.
+
+```typescript
+type CoreToolMessage = {
+  role: 'tool';
+  content: ToolContent;
+};
+
+type ToolContent = Array<ToolResultPart>;
+```
+
+## `CoreMessage` 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 mime type of the image.
+   */
+  mimeType?: 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.
+   */
+  result: unknown;
+  /**
+   * Optional flag if the result is an error or an error message.
+   */
+  isError?: boolean;
+}
+```

content/docs/07-reference/ai-sdk-ui/31-convert-to-core-message.mdx

@@ -0,0 +1,56 @@
+---
+title: convertToCoreMessages
+description: Convert useChat messages to CoreMessages for AI core functions (API Reference)
+---
+
+# `convertToCoreMessages()`
+
+The `convertToCoreMessages` function is used to transform an array of UI messages from the `useChat` hook into an array of `CoreMessage` objects. These `CoreMessage` objects are compatible with AI core functions like `streamText`.
+
+```ts filename="app/api/chat/route.ts"
+import { openai } from '@ai-sdk/openai';
+import { convertToCoreMessages, streamText } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = await streamText({
+    model: openai('gpt-4o'),
+    messages: convertToCoreMessages(messages),
+  });
+
+  return result.toAIStreamResponse();
+}
+```
+
+## Import
+
+<Snippet text={`import { convertToCoreMessages } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'messages',
+      type: 'Message[]',
+      description: `An array of UI messages from the useChat hook to be converted`,
+    },
+  ]}
+/>
+
+### Returns
+
+An array of [`CoreMessage`](/docs/reference/ai-sdk-core/core-message) objects.
+
+<PropertiesTable
+  content={[
+    {
+      name: 'CoreMessage[]',
+      type: 'Array',
+      description: 'An array of CoreMessage objects',
+    },
+  ]}
+/>