Messages

Overview

Messages are the fundamental building blocks of conversations in core-ai. They represent the dialogue between users, the assistant, and tools.

Message Types

core-ai supports five message types:

type Message =
    | SystemMessage
    | UserMessage
    | AssistantMessage
    | ToolResultMessage
    | ToolDiscoveryResultMessage;

System Message

System messages set the context and behavior for the assistant. Put them at the start of the conversation for standing instructions, or later in the conversation for instructions that apply from that point on. See System message placement for where each model accepts them.

type SystemMessage = {
    role: 'system';
    content: string;
    providerOptions?: SystemMessageProviderOptions;
    metadata?: Record<string, unknown>;
};

providerOptions is keyed by provider id, like the request-level providerOptions. For example, Anthropic accepts a per-message cacheControl. See the Anthropic provider reference. User, tool result, and discovery result messages accept providerOptions the same way. Example:

const systemMessage: SystemMessage = {
    role: 'system',
    content:
        'You are a helpful assistant that always responds in haiku format.',
};

User Message

User messages represent input from the user. They can be simple text or multi-modal content with images, files, and audio.

type UserMessage = {
    role: 'user';
    content: string | UserContentPart[];
    providerOptions?: UserMessageProviderOptions;
};

Simple Text:

const userMessage: UserMessage = {
    role: 'user',
    content: 'What is the capital of France?',
};

Multi-Modal Content:

const userMessage: UserMessage = {
    role: 'user',
    content: [
        { type: 'text', text: 'What is in this image?' },
        {
            type: 'image',
            source: {
                type: 'url',
                url: 'https://example.com/photo.jpg',
            },
        },
    ],
};

Assistant Message

Assistant messages contain the model’s responses, including text, reasoning, tool calls, and discovery calls.

type AssistantMessage = {
    role: 'assistant';
    parts: AssistantContentPart[];
};

type AssistantContentPart =
    | AssistantTextPart
    | ReasoningPart
    | ToolCallPart
    | ToolDiscoveryCallPart;

Example:

const assistantMessage: AssistantMessage = {
    role: 'assistant',
    parts: [{ type: 'text', text: 'The capital of France is Paris.' }],
};

Assistant messages use a parts array to support multiple content types (text, reasoning, tool calls, discovery calls) in a single message.

Tool Result Message

Tool result messages provide the results of tool calls back to the model.

type ToolResultMessage = {
    role: 'tool';
    toolCallId: string;
    content: string;
    isError?: boolean;
    providerOptions?: ToolResultMessageProviderOptions;
    metadata?: Record<string, unknown>;
};

Example:

const toolResult: ToolResultMessage = {
    role: 'tool',
    toolCallId: 'call_123',
    content: JSON.stringify({ temperature: 72, condition: 'sunny' }),
};

Tool Discovery Result Message

Tool discovery result messages answer a discovery call with the tools your application found. See Tool Discovery.

type ToolDiscoveryResultMessage = {
    role: 'tool-discovery';
    discoveryCallId: string;
    tools: ToolSnapshot[];
    note?: string;
    providerOptions?: ToolDiscoveryResultMessageProviderOptions;
    metadata?: Record<string, unknown>;
};

Example:

const discoveryResult: ToolDiscoveryResultMessage = {
    role: 'tool-discovery',
    discoveryCallId: 'call_456',
    tools: [
        {
            name: 'get_order_status',
            description: 'Look up the shipping status of an order by its id',
            parameters: {
                type: 'object',
                properties: { orderId: { type: 'string' } },
                required: ['orderId'],
            },
        },
    ],
};

Answer each discovery call with exactly one discovery result, placed with the step’s tool results. The tools it lists stay declared on later generate() and stream() requests while the message is in the history, unless tools declares the same name. When nothing matched, tools is empty and an optional note tells the model why.

User Content Parts

User messages can include multiple types of content:

type UserContentPart = TextPart | ImagePart | FilePart;

Text Part

Simple text content:

type TextPart = {
    type: 'text';
    text: string;
    metadata?: Record<string, unknown>;
};

Example:

const textPart: TextPart = {
    type: 'text',
    text: 'Explain this concept in detail.',
};

Image Part

Images can be provided as URLs or base64-encoded data:

type ImagePart = {
    type: 'image';
    source:
        | { type: 'base64'; mediaType: string; data: string }
        | { type: 'url'; url: string };
};

URL Image:

const urlImage: ImagePart = {
    type: 'image',
    source: {
        type: 'url',
        url: 'https://example.com/diagram.png',
    },
};

Base64 Image:

import { readFileSync } from 'fs';

const imageBuffer = readFileSync('./photo.jpg');
const base64Data = imageBuffer.toString('base64');

const base64Image: ImagePart = {
    type: 'image',
    source: {
        type: 'base64',
        mediaType: 'image/jpeg',
        data: base64Data,
    },
};

File Part

Files can be attached with mime type information:

type FilePart = {
    type: 'file';
    data: string; // Base64-encoded file data
    mimeType: string;
    filename?: string;
};

Example:

import { readFileSync } from 'fs';

const pdfBuffer = readFileSync('./document.pdf');
const base64Data = pdfBuffer.toString('base64');

const filePart: FilePart = {
    type: 'file',
    data: base64Data,
    mimeType: 'application/pdf',
    filename: 'document.pdf',
};

Audio Parts

Audio parts contain base64-encoded audio:

type AudioPart = {
    type: 'audio';
    source: {
        type: 'base64';
        mediaType: string;
        data: string;
    };
};

import { readFileSync } from 'fs';

const audioPart: AudioPart = {
    type: 'audio',
    source: {
        type: 'base64',
        mediaType: 'audio/wav',
        data: readFileSync('./recording.wav').toString('base64'),
    },
};

Not all providers support all content types. For example, Anthropic accepts PDF file parts only. Check the provider pages for model-specific input limits.

Assistant Content Parts

Assistant messages can contain text, reasoning, tool calls, and discovery calls:

type AssistantContentPart =
    | AssistantTextPart
    | ReasoningPart
    | ToolCallPart
    | ToolDiscoveryCallPart;

Text Part

Regular text responses:

type AssistantTextPart = {
    type: 'text';
    text: string;
    metadata?: Record<string, unknown>;
};

Reasoning Part

Extended thinking and reasoning content from the model:

type ReasoningPart = {
    type: 'reasoning';
    text: string;
    metadata?: Record<string, unknown>;
    providerMetadata?: Record<string, Record<string, unknown>>;
};

The metadata field is application-owned. Provider adapters ignore it. The providerMetadata object is provider-namespaced. The top-level key is the provider identifier, such as 'anthropic', 'google', 'openai', or 'azure-openai'. Adapters treat other providers’ keys as foreign and downgrade those reasoning blocks to plain text instead of forwarding opaque metadata.

Use getProviderMetadata() when you want typed access to provider-specific metadata.

Accessing Reasoning:

const result = await generate({
    model,
    messages: [{ role: 'user', content: 'Solve this complex problem...' }],
    reasoning: { effort: 'high' },
});

if (result.reasoning) {
    console.log('Internal reasoning:', result.reasoning);
}

Tool Call Part

Requests to call external tools:

type ToolCallPart = {
    type: 'tool-call';
    toolCall: ToolCall;
    providerMetadata?: Record<string, Record<string, unknown>>;
};

type ToolCall = {
    id: string;
    name: string;
    arguments: Record<string, unknown>;
    metadata?: Record<string, unknown>;
};

Pass tool call parts back into the next request unchanged. Some providers put data on them that has to return verbatim: Gemini 3 rejects a request when a function call from the current turn is replayed without its thought signature.

Tool Discovery Call Part

The model asking for tools the request does not declare yet, when the request sets toolDiscovery:

type ToolDiscoveryCallPart = {
    type: 'tool-discovery-call';
    discoveryCall: {
        id: string;
        names?: string[];
        query?: string;
        metadata?: Record<string, unknown>;
    };
    providerMetadata?: Record<string, Record<string, unknown>>;
};

names lists exact tool names, query describes the capability the model needs. Like a tool call part, the part wraps the call. Discovery calls appear in GenerateResult.discoveryCalls, never in toolCalls. Pass them back unchanged, like tool call parts, and answer each one with a tool discovery result message before the next request.

Part metadata

Text-bearing parts can carry optional metadata for application and middleware state. Use it for annotations such as classification results, provenance, validation status, or text transformation spans. This metadata stays with the part in message history and generated results. Provider adapters do not serialize it to provider APIs. core-ai has three metadata layers:

GenerateOptions.metadata is call-level context for observability and middleware.
ReasoningPart.providerMetadata, ToolCallPart.providerMetadata, and ToolDiscoveryCallPart.providerMetadata are provider-owned data used to round-trip reasoning blocks, tool calls, and discovery calls with the same provider.
Application-owned metadata on system messages, text parts, reasoning parts, tool calls, discovery calls, tool results, and discovery results.

Multi-Turn Conversations

Build conversations by passing message history:

import { generate } from '@core-ai/core-ai';

const messages: Message[] = [
    { role: 'system', content: 'You are a helpful math tutor.' },
    { role: 'user', content: 'What is 15 + 27?' },
];

const result1 = await generate({ model, messages });

// Add assistant response to history
messages.push({
    role: 'assistant',
    parts: result1.parts,
});

// Continue conversation
messages.push({
    role: 'user',
    content: 'Now multiply that by 2',
});

const result2 = await generate({ model, messages });

System message placement

System messages before the first non-system message are leading system messages. Every model accepts them. Anthropic and Google adapters send them as the top-level system prompt (Google joins them into one systemInstruction); the other adapters send them as messages. A system message after that is a later system message. It applies from its position on, which suits instructions that arrive mid-conversation, such as a mode switch. Models differ in where they accept one, and each model reports its rule in model.capabilities.messages.systemPlacement:

`systemPlacement`	Where later system messages are accepted
`'leading'`	Nowhere. All system messages must come first.
`'before-reply'`	Directly after a user or tool message, followed by an assistant message or at the end. Consecutive system messages count as one.
`'anywhere'`	Any position.

Each rule accepts everything the stricter rules accept. A tool discovery result counts as a tool message.

Provider	`systemPlacement`
OpenAI, Azure OpenAI, Mistral, xAI, Kimi, OpenAI-compatible	`'anywhere'`
Anthropic, Anthropic on Vertex	`'before-reply'` from Claude Opus 4.8, Sonnet 5, and Haiku 5.5 on; `'leading'` for earlier models
Google GenAI, Google Vertex	`'leading'`

Adapters send a later system message where you put it; they never move it or merge it into the leading system prompt. The Anthropic adapter drops system messages without non-whitespace text, which Anthropic rejects. When a system message breaks the model’s rule, the request fails with UnsupportedSystemMessagePlacementError before anything is sent:

import {
    generate,
    UnsupportedSystemMessagePlacementError,
} from '@core-ai/core-ai';

try {
    await generate({ model, messages });
} catch (error) {
    if (error instanceof UnsupportedSystemMessagePlacementError) {
        console.log(error.placement); // 'leading'
        console.log(error.issues); // [{ index: 3, reason: 'not-leading' }]
    }
}

To add an instruction for the next reply on any model that accepts later system messages, append it directly after the latest user or tool message. On 'leading' models, send the instruction as part of a user message instead:

const instruction = 'Answer in one word.';

if (model.capabilities.messages.systemPlacement === 'leading') {
    messages.push({ role: 'user', content: `${question}\n\n${instruction}` });
} else {
    messages.push({ role: 'user', content: question });
    messages.push({ role: 'system', content: instruction });
}

To check a conversation without sending it, call getSystemMessagePlacementIssues(). Pass a stricter rule than your current model’s to keep the conversation portable across models:

import { getSystemMessagePlacementIssues } from '@core-ai/core-ai';

const issues = getSystemMessagePlacementIssues(messages, 'before-reply');
// [] when every later system message follows a user or tool message

Helper functions

For message helpers like resultToMessage() and assistantMessage(), see the utilities reference.

Tool Call Flow

Here’s a complete example of handling tool calls:

import {
    defineTool,
    generate,
    resultToMessage,
    validateToolCall,
} from '@core-ai/core-ai';
import type { Message } from '@core-ai/core-ai';
import { z } from 'zod';

const tools = {
    getWeather: defineTool({
        name: 'getWeather',
        description: 'Get weather for a location',
        parameters: z.object({
            location: z.string(),
        }),
    }),
};

const messages: Message[] = [
    { role: 'user', content: "What's the weather in Tokyo?" },
];

// Step 1: Model requests tool call
const result1 = await generate({ model, messages, tools });
messages.push(resultToMessage(result1));

const toolCall = result1.toolCalls[0];
if (toolCall) {
    // Step 2: Validate the call, execute the tool, and provide the result
    const validation = await validateToolCall(tools.getWeather, toolCall);
    if (validation.issues) {
        // Or send the issues back to the model as an error tool result
        throw new Error(`Invalid arguments for ${toolCall.name}`);
    }

    const weatherData = await getWeather(validation.value.location);

    messages.push({
        role: 'tool',
        toolCallId: toolCall.id,
        content: JSON.stringify(weatherData),
    });

    // Step 3: Model generates final response
    const result2 = await generate({ model, messages, tools });
    console.log(result2.content);
}

Best Practices

Keep system messages concise: System messages set the tone but shouldn’t contain too much information. For large context, consider using user messages with retrieved content.

Use resultToMessage for history: Always convert generation results to messages using resultToMessage() to maintain proper conversation history with all content parts.

Multi-modal order matters: When combining text and images, place the text part first to provide context for what you’re asking about the image.

Next Steps

Configure generation with Configuration options
Learn about Error Handling
Explore Providers for provider-specific features

Get Started

Core Concepts

Guides

Observability

Examples

Overview

Message Types

System Message

User Message

Assistant Message

Tool Result Message

Tool Discovery Result Message

User Content Parts

Text Part

Image Part

File Part

Audio Parts

Assistant Content Parts

Text Part

Reasoning Part

Tool Call Part

Tool Discovery Call Part

Part metadata

Multi-Turn Conversations

System message placement

Helper functions

Tool Call Flow

Best Practices

Next Steps

​Overview

​Message Types

​System Message

​User Message

​Assistant Message

​Tool Result Message

​Tool Discovery Result Message

​User Content Parts

​Text Part

​Image Part

​File Part

​Audio Parts

​Assistant Content Parts

​Text Part

​Reasoning Part

​Tool Call Part

​Tool Discovery Call Part

​Part metadata

​Multi-Turn Conversations

​System message placement

​Helper functions

​Tool Call Flow

​Best Practices

​Next Steps

Overview

Message Types

System Message

User Message

Assistant Message

Tool Result Message

Tool Discovery Result Message

User Content Parts

Text Part

Image Part

File Part

Audio Parts

Assistant Content Parts

Text Part

Reasoning Part

Tool Call Part

Tool Discovery Call Part

Part metadata

Multi-Turn Conversations

System message placement

Helper functions

Tool Call Flow

Best Practices

Next Steps