generate()

Overview

The generate() function generates a single response from a chat model. It’s the core function for synchronous text generation with support for tool calls, reasoning, and structured conversations.

Function signature

export async function generate(
    params: GenerateParams
): Promise<GenerateResult>

export type GenerateParams = GenerateOptions & {
    model: ChatModel;
};

Parameters

ChatModel

required

The chat model instance to use for generation.

Message[]

required

Array of messages in the conversation. Must not be empty.

number

Sampling temperature (0-2). Higher values make output more random.

number

Total output allowance for the response, covering reasoning tokens and the visible answer. When omitted, the model’s output ceiling applies. If the value cannot hold the reasoning budget of the requested effort, the call throws a ValidationError. See maxTokens.

number

Nucleus sampling parameter (0-1).

ReasoningConfig

Configuration for extended thinking/reasoning capabilities.

Show ReasoningConfig

ReasoningEffort

required

The effort level for reasoning: 'minimal', 'low', 'medium', 'high', or 'max'.

ToolSet

Object mapping tool names to tool definitions. Enables the model to call functions.

ToolChoice

Controls how the model uses tools:

'auto' - Model decides whether to use tools
'none' - Model won’t use tools
'required' - Model must use a tool
{ type: 'tool', toolName: string } - Force specific tool

With tool discovery in use, toolName may only name a tool in tools. 'none' also keeps the model from discovering tools, and a discovery call satisfies 'required'.

ToolDiscoveryOptions

Enables tool discovery: core-ai declares a discovery tool, and the model’s calls to it arrive as tool-discovery-call parts in parts. Answer each one with a tool-discovery message before the next request. Keep it set consistently within a conversation; switching it costs a prompt cache rewrite. See Tool Discovery.

Show ToolDiscoveryOptions

string

Appended to the discovery tool’s default description, for example a list of the discoverable tool names.

GenerateProviderOptions

Provider-specific options, namespaced by provider name (e.g. { openai: { user: '...' } }).

AbortSignal

AbortSignal for cancelling the request.

Return value

Returns a Promise<GenerateResult> with the following properties:

AssistantContentPart[]

Array of content parts in the response (text, reasoning, tool calls, discovery calls).

string | null

Concatenated text content from all text parts. null if no text was generated.

string | null

Concatenated reasoning content. null if no reasoning was generated.

ToolCall[]

Array of tool calls made by the model, including calls to discovered tools. Discovery calls appear in discoveryCalls instead.

ToolDiscoveryCall[]

Calls from the model asking to discover tools, when the request sets toolDiscovery. Answer each one before the next request. See Tool Discovery.

FinishReason

Why generation stopped: 'stop', 'length', 'tool-calls', 'content-filter', or 'unknown'. 'tool-calls' means tool calls or discovery calls are pending: answer both toolCalls and discoveryCalls before the next request.

ChatUsage

Token usage statistics including input/output tokens and cache details.

Show ChatUsage

number

Total input tokens, including cached and cache-write tokens.

number

Total output tokens, including both visible text and reasoning.

ChatInputTokenDetails

Breakdown of input token categories (cacheReadTokens, cacheWriteTokens).

ChatOutputTokenDetails

Breakdown of output token categories (reasoningTokens if available).

Examples

Basic text generation

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

const openai = createOpenAI();
const model = openai.chatModel('gpt-5-mini');

const result = await generate({
  model,
  messages: [
    { role: 'user', content: 'What is the capital of France?' }
  ]
});

console.log(result.content);

With configuration

const result = await generate({
  model,
  messages: [
    { role: 'user', content: 'Write a creative story' }
  ],
  temperature: 1.5,
  maxTokens: 500,
});

With tools

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

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

const result = await generate({
  model,
  messages: [
    { role: 'user', content: 'What\'s the weather in Paris?' }
  ],
  tools: {
    get_weather: weatherTool
  }
});

if (result.toolCalls.length > 0) {
  console.log('Tool called:', result.toolCalls[0].name);
  console.log('Arguments:', result.toolCalls[0].arguments);
}

Multi-turn conversation

const result = await generate({
  model,
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' },
    { role: 'assistant', parts: [{ type: 'text', text: 'Hi! How can I help?' }] },
    { role: 'user', content: 'Tell me a joke' }
  ]
});

Error handling

Throws ValidationError if:

Messages array is empty
The request breaks a tool discovery rule, such as an unanswered discovery call. See Validation.

May also throw:

ProviderError if the provider returns an error during generation

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

try {
  const result = await generate({
    model,
    messages: []
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Generation failed:', error.message);
  }
}

Core

Providers

Overview

Function signature

Parameters

Return value

Examples

Basic text generation

With configuration

With tools

Multi-turn conversation

Error handling

​Overview

​Function signature

​Parameters

​Return value

​Examples

​Basic text generation

​With configuration

​With tools

​Multi-turn conversation

​Error handling

Overview

Function signature

Parameters

Return value

Examples

Basic text generation

With configuration

With tools

Multi-turn conversation

Error handling