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 four message types:

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

System Message

System messages set the context and behavior for the assistant.

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

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[];
};

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, and tool calls.

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

type AssistantContentPart = AssistantTextPart | ReasoningPart | ToolCallPart;

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) 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;
    metadata?: Record<string, unknown>;
};

Example:

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

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, and tool calls:

type AssistantContentPart = AssistantTextPart | ReasoningPart | ToolCallPart;

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.

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 and ToolCallPart.providerMetadata are provider-owned data used to round-trip reasoning blocks and tool calls with the same provider.
Application-owned metadata on system messages, text parts, reasoning parts, tool calls, and tool 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 });

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 } 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));

if (result1.toolCalls.length > 0) {
    // Step 2: Execute tool and provide result
    const toolCall = result1.toolCalls[0];
    const weatherData = await getWeather(toolCall.arguments.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

User Content Parts

Text Part

Image Part

File Part

Audio Parts

Assistant Content Parts

Text Part

Reasoning Part

Tool Call Part

Part metadata

Multi-Turn Conversations

Helper functions

Tool Call Flow

Best Practices

Next Steps

​Overview

​Message Types

​System Message

​User Message

​Assistant Message

​Tool Result Message

​User Content Parts

​Text Part

​Image Part

​File Part

​Audio Parts

​Assistant Content Parts

​Text Part

​Reasoning Part

​Tool Call Part

​Part metadata

​Multi-Turn Conversations

​Helper functions

​Tool Call Flow

​Best Practices

​Next Steps

Overview

Message Types

System Message

User Message

Assistant Message

Tool Result Message

User Content Parts

Text Part

Image Part

File Part

Audio Parts

Assistant Content Parts

Text Part

Reasoning Part

Tool Call Part

Part metadata

Multi-Turn Conversations

Helper functions

Tool Call Flow

Best Practices

Next Steps