`generateText()`

Generates text and calls tools for a given prompt using a language model.

It is ideal for non-interactive use cases such as automation tasks where you need to write text (e.g. drafting email or summarizing web pages) and for agents that use tools.

import { generateText } from 'ai';

const { text } = await generateText({
  model: "anthropic/claude-sonnet-4.5",
  prompt: 'Invent a new holiday and describe its traditions.',
});

console.log(text);

To see generateText in action, check out these examples.

Import

import { generateText } from "ai"

API Signature

Parameters

model:

LanguageModel

system:

string | SystemModelMessage | SystemModelMessage[]

prompt:

string | Array<SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage>

messages:

Array<SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage>

SystemModelMessage

role:

'system'

content:

string

UserModelMessage

role:

'user'

content:

string | Array<TextPart | ImagePart | FilePart>

TextPart

type:

'text'

text:

string

ImagePart

type:

'image'

image:

string | Uint8Array | Buffer | ArrayBuffer | URL

mediaType?:

string

FilePart

type:

'file'

data:

string | Uint8Array | Buffer | ArrayBuffer | URL

mediaType:

string

AssistantModelMessage

role:

'assistant'

content:

string | Array<TextPart | FilePart | ReasoningPart | ToolCallPart>

TextPart

type:

'text'

text:

string

ReasoningPart

type:

'reasoning'

text:

string

FilePart

type:

'file'

data:

string | Uint8Array | Buffer | ArrayBuffer | URL

mediaType:

string

filename?:

string

ToolCallPart

type:

'tool-call'

toolCallId:

string

toolName:

string

input:

object based on zod schema

ToolModelMessage

role:

'tool'

content:

Array<ToolResultPart>

ToolResultPart

type:

'tool-result'

toolCallId:

string

toolName:

string

output:

unknown

isError?:

boolean

tools:

ToolSet

Tool

description?:

string

inputSchema:

Zod Schema | JSON Schema

execute?:

async (parameters: T, options: ToolExecutionOptions) => RESULT

ToolExecutionOptions

toolCallId:

string

messages:

ModelMessage[]

abortSignal:

AbortSignal

toolChoice?:

"auto" | "none" | "required" | { "type": "tool", "toolName": string }

maxOutputTokens?:

number

temperature?:

number

topP?:

number

topK?:

number

presencePenalty?:

number

frequencyPenalty?:

number

stopSequences?:

string[]

seed?:

number

maxRetries?:

number

abortSignal?:

AbortSignal

timeout?:

number | { totalMs?: number; stepMs?: number }

headers?:

Record<string, string | undefined>

experimental_telemetry?:

TelemetrySettings

isEnabled?:

boolean

recordInputs?:

boolean

recordOutputs?:

boolean

functionId?:

string

metadata?:

providerOptions?:

Record<string,JSONObject> | undefined

activeTools?:

Array<TOOLNAME>

stopWhen?:

StopCondition<TOOLS> | Array<StopCondition<TOOLS>>

prepareStep?:

(options: PrepareStepOptions) => PrepareStepResult<TOOLS> | Promise<PrepareStepResult<TOOLS>>

PrepareStepFunction<TOOLS>

options:

object

PrepareStepOptions

steps:

Array<StepResult<TOOLS>>

stepNumber:

number

model:

LanguageModel

messages:

Array<ModelMessage>

experimental_context?:

unknown

PrepareStepResult<TOOLS>

model?:

LanguageModel

toolChoice?:

ToolChoice<TOOLS>

activeTools?:

Array<keyof TOOLS>

system?:

string | SystemModelMessage | SystemModelMessage[]

messages?:

Array<ModelMessage>

experimental_context?:

unknown

providerOptions?:

ProviderOptions

experimental_context?:

unknown

experimental_download?:

(requestedDownloads: Array<{ url: URL; isUrlSupportedByModel: boolean }>) => Promise<Array<null | { data: Uint8Array; mediaType?: string }>>

experimental_include?:

{ requestBody?: boolean; responseBody?: boolean }

Object

requestBody?:

boolean

responseBody?:

boolean

experimental_repairToolCall?:

(options: ToolCallRepairOptions) => Promise<LanguageModelV3ToolCall | null>

ToolCallRepairOptions

system:

string | SystemModelMessage | SystemModelMessage[] | undefined

messages:

ModelMessage[]

toolCall:

LanguageModelV3ToolCall

tools:

TOOLS

parameterSchema:

(options: { toolName: string }) => JSONSchema7

error:

NoSuchToolError | InvalidToolInputError

output?:

Output

Output.text():

Output

Output.object():

Output

Options

schema:

Schema<OBJECT>

name?:

string

description?:

string

Output.array():

Output

Options

element:

Schema<ELEMENT>

name?:

string

description?:

string

Output.choice():

Output

Options

options:

Array<string>

name?:

string

description?:

string

Output.json():

Output

Options

name?:

string

description?:

string

experimental_onStart?:

(event: OnStartEvent) => PromiseLike<void> | void

OnStartEvent

model:

{ provider: string; modelId: string }

system:

string | SystemModelMessage | Array<SystemModelMessage> | undefined

prompt:

string | Array<ModelMessage> | undefined

messages:

Array<ModelMessage> | undefined

tools:

TOOLS | undefined

toolChoice:

ToolChoice<TOOLS> | undefined

activeTools:

Array<keyof TOOLS> | undefined

maxOutputTokens:

number | undefined

temperature:

number | undefined

topP:

number | undefined

topK:

number | undefined

presencePenalty:

number | undefined

frequencyPenalty:

number | undefined

stopSequences:

string[] | undefined

seed:

number | undefined

maxRetries:

number

timeout:

number | { totalMs?: number; stepMs?: number; chunkMs?: number } | undefined

headers:

Record<string, string | undefined> | undefined

providerOptions:

ProviderOptions | undefined

stopWhen:

StopCondition<TOOLS> | Array<StopCondition<TOOLS>> | undefined

output:

OUTPUT | undefined

abortSignal:

AbortSignal | undefined

include:

{ requestBody?: boolean; responseBody?: boolean } | undefined

functionId:

string | undefined

metadata:

Record<string, unknown> | undefined

experimental_context:

unknown

experimental_onStepStart?:

(event: OnStepStartEvent) => PromiseLike<void> | void

OnStepStartEvent

stepNumber:

number

model:

{ provider: string; modelId: string }

system:

string | SystemModelMessage | Array<SystemModelMessage> | undefined

messages:

Array<ModelMessage>

tools:

TOOLS | undefined

toolChoice:

LanguageModelV3ToolChoice | undefined

activeTools:

Array<keyof TOOLS> | undefined

steps:

ReadonlyArray<StepResult<TOOLS>>

providerOptions:

ProviderOptions | undefined

timeout:

number | { totalMs?: number; stepMs?: number; chunkMs?: number } | undefined

headers:

Record<string, string | undefined> | undefined

stopWhen:

StopCondition<TOOLS> | Array<StopCondition<TOOLS>> | undefined

output:

OUTPUT | undefined

abortSignal:

AbortSignal | undefined

include:

{ requestBody?: boolean; responseBody?: boolean } | undefined

functionId:

string | undefined

metadata:

Record<string, unknown> | undefined

experimental_context:

unknown

experimental_onToolCallStart?:

(event: OnToolCallStartEvent) => PromiseLike<void> | void

OnToolCallStartEvent

stepNumber:

number | undefined

model:

{ provider: string; modelId: string } | undefined

toolCall:

TypedToolCall<TOOLS>

messages:

Array<ModelMessage>

abortSignal:

AbortSignal | undefined

functionId:

string | undefined

metadata:

Record<string, unknown> | undefined

experimental_context:

unknown

experimental_onToolCallFinish?:

(event: OnToolCallFinishEvent) => PromiseLike<void> | void

OnToolCallFinishEvent

stepNumber:

number | undefined

model:

{ provider: string; modelId: string } | undefined

toolCall:

TypedToolCall<TOOLS>

messages:

Array<ModelMessage>

abortSignal:

AbortSignal | undefined

durationMs:

number

functionId:

string | undefined

metadata:

Record<string, unknown> | undefined

experimental_context:

unknown

success:

boolean

output:

unknown

error:

unknown

onStepFinish?:

(stepResult: StepResult<TOOLS>) => Promise<void> | void

StepResult

stepNumber:

number

model:

{ provider: string; modelId: string }

functionId:

string | undefined

metadata:

Record<string, unknown> | undefined

experimental_context:

unknown

content:

Array<ContentPart<TOOLS>>

text:

string

reasoning:

Array<ReasoningPart>

reasoningText:

string | undefined

files:

Array<GeneratedFile>

sources:

Array<Source>

toolCalls:

Array<TypedToolCall<TOOLS>>

staticToolCalls:

Array<StaticToolCall<TOOLS>>

dynamicToolCalls:

Array<DynamicToolCall>

toolResults:

Array<TypedToolResult<TOOLS>>

staticToolResults:

Array<StaticToolResult<TOOLS>>

dynamicToolResults:

Array<DynamicToolResult>

finishReason:

rawFinishReason:

string | undefined

usage:

LanguageModelUsage

inputTokens:

number | undefined

inputTokenDetails:

LanguageModelInputTokenDetails

noCacheTokens:

number | undefined

cacheReadTokens:

number | undefined

cacheWriteTokens:

number | undefined

outputTokens:

number | undefined

outputTokenDetails:

LanguageModelOutputTokenDetails

textTokens:

number | undefined

reasoningTokens:

number | undefined

totalTokens:

number | undefined

raw?:

object | undefined

warnings:

CallWarning[] | undefined

request:

LanguageModelRequestMetadata

response:

LanguageModelResponseMetadata & { messages: Array<ResponseMessage>; body?: unknown }

Response

id:

string

modelId:

string

timestamp:

Date

headers?:

Record<string, string>

messages:

Array<ResponseMessage>

body?:

unknown

providerMetadata?:

ProviderMetadata | undefined

onFinish?:

(event: StepResult<TOOLS> & { steps: StepResult<TOOLS>[]; totalUsage: LanguageModelUsage }) => PromiseLike<void> | void

OnFinishEvent

stepNumber:

number

model:

{ provider: string; modelId: string }

functionId:

string | undefined

metadata:

Record<string, unknown> | undefined

finishReason:

rawFinishReason:

string | undefined

usage:

LanguageModelUsage

inputTokens:

number | undefined

inputTokenDetails:

LanguageModelInputTokenDetails

noCacheTokens:

number | undefined

cacheReadTokens:

number | undefined

cacheWriteTokens:

number | undefined

outputTokens:

number | undefined

outputTokenDetails:

LanguageModelOutputTokenDetails

textTokens:

number | undefined

reasoningTokens:

number | undefined

totalTokens:

number | undefined

raw?:

object | undefined

totalUsage:

LanguageModelUsage

inputTokens:

number | undefined

outputTokens:

number | undefined

totalTokens:

number | undefined

content:

Array<ContentPart<TOOLS>>

providerMetadata:

ProviderMetadata | undefined

text:

string

reasoningText:

string | undefined

reasoning:

Array<ReasoningDetail>

ReasoningDetail

type:

'text'

text:

string

signature?:

string

ReasoningDetail

type:

'redacted'

data:

string

sources:

Array<Source>

Source

sourceType:

'url'

id:

string

url:

string

title?:

string

providerMetadata?:

SharedV2ProviderMetadata

files:

Array<GeneratedFile>

GeneratedFile

base64:

string

uint8Array:

Uint8Array

mediaType:

string

toolCalls:

Array<TypedToolCall<TOOLS>>

staticToolCalls:

Array<StaticToolCall<TOOLS>>

dynamicToolCalls:

Array<DynamicToolCall>

toolResults:

Array<TypedToolResult<TOOLS>>

staticToolResults:

Array<StaticToolResult<TOOLS>>

dynamicToolResults:

Array<DynamicToolResult>

warnings:

CallWarning[] | undefined

request:

LanguageModelRequestMetadata

response:

LanguageModelResponseMetadata & { messages: Array<ResponseMessage>; body?: unknown }

Response

id:

string

modelId:

string

timestamp:

Date

headers?:

Record<string, string>

messages:

Array<ResponseMessage>

steps:

Array<StepResult>

experimental_context:

unknown

Returns

content:

Array<ContentPart<TOOLS>>

text:

string

reasoning:

Array<ReasoningOutput>

ReasoningOutput

type:

'reasoning'

text:

string

providerMetadata?:

SharedV2ProviderMetadata

reasoningText:

string | undefined

sources:

Array<Source>

Source

sourceType:

'url'

id:

string

url:

string

title?:

string

providerMetadata?:

SharedV2ProviderMetadata

files:

Array<GeneratedFile>

GeneratedFile

base64:

string

uint8Array:

Uint8Array

mediaType:

string

toolCalls:

ToolCallArray<TOOLS>

toolResults:

ToolResultArray<TOOLS>

staticToolCalls:

Array<StaticToolCall<TOOLS>>

dynamicToolCalls:

Array<DynamicToolCall>

staticToolResults:

Array<StaticToolResult<TOOLS>>

dynamicToolResults:

Array<DynamicToolResult>

finishReason:

rawFinishReason:

string | undefined

usage:

LanguageModelUsage

inputTokens:

number | undefined

inputTokenDetails:

LanguageModelInputTokenDetails

noCacheTokens:

number | undefined

cacheReadTokens:

number | undefined

cacheWriteTokens:

number | undefined

outputTokens:

number | undefined

outputTokenDetails:

LanguageModelOutputTokenDetails

textTokens:

number | undefined

reasoningTokens:

number | undefined

totalTokens:

number | undefined

raw?:

object | undefined

totalUsage:

LanguageModelUsage

inputTokens:

number | undefined

outputTokens:

number | undefined

totalTokens:

number | undefined

reasoningTokens?:

number | undefined

cachedInputTokens?:

number | undefined

request?:

LanguageModelRequestMetadata

body:

string

response?:

LanguageModelResponseMetadata

id:

string

modelId:

string

timestamp:

Date

headers?:

Record<string, string>

body?:

unknown

messages:

Array<ResponseMessage>

warnings:

Warning[] | undefined

providerMetadata:

ProviderMetadata | undefined

output?:

Output

steps:

Array<StepResult<TOOLS>>

StepResult

stepNumber:

number

model:

{ provider: string; modelId: string }

functionId:

string | undefined

metadata:

Record<string, unknown> | undefined

experimental_context:

unknown

content:

Array<ContentPart<TOOLS>>

text:

string

reasoning:

Array<ReasoningPart>

ReasoningPart

type:

'reasoning'

text:

string

reasoningText:

string | undefined

files:

Array<GeneratedFile>

GeneratedFile

base64:

string

uint8Array:

Uint8Array

mediaType:

string

sources:

Array<Source>

Source

sourceType:

'url'

id:

string

url:

string

title?:

string

providerMetadata?:

SharedV2ProviderMetadata

toolCalls:

ToolCallArray<TOOLS>

toolResults:

ToolResultArray<TOOLS>

finishReason:

rawFinishReason:

string | undefined

usage:

LanguageModelUsage

inputTokens:

number | undefined

inputTokenDetails:

LanguageModelInputTokenDetails

noCacheTokens:

number | undefined

cacheReadTokens:

number | undefined

cacheWriteTokens:

number | undefined

outputTokens:

number | undefined

outputTokenDetails:

LanguageModelOutputTokenDetails

textTokens:

number | undefined

reasoningTokens:

number | undefined

totalTokens:

number | undefined

raw?:

object | undefined

warnings:

Warning[] | undefined

request:

LanguageModelRequestMetadata

body:

string

response:

LanguageModelResponseMetadata

id:

string

modelId:

string

timestamp:

Date

headers?:

Record<string, string>

body?:

unknown

messages:

Array<ResponseMessage>

providerMetadata:

ProviderMetadata | undefined

Examples

Learn to generate text using a language model in Next.js

Learn to generate a chat completion using a language model in Next.js

Learn to call tools using a language model in Next.js

Learn to render a React component as a tool call using a language model in Next.js

Learn to generate text using a language model in Node.js

Learn to generate chat completions using a language model in Node.js