`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 { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: 'Invent a new holiday and describe its traditions.',
});

console.log(text);

Import

import { generateText } from "ai"

API Signature

model:

LanguageModel

The language model to use. Example: openai('gpt-4-turbo')

system:

string

The system prompt to use that specifies the behavior of the model.

prompt:

string

The input prompt to generate the text from.

messages:

Array<CoreSystemMessage | CoreUserMessage | CoreAssistantMessage | CoreToolMessage>

A list of messages that represent a conversation.

CoreSystemMessage

role:

'system'

The role for the system message.

content:

string

The content of the message.

CoreUserMessage

role:

'user'

The role for the user message.

content:

string | Array<TextPart | ImagePart>

The content of the message.

TextPart

type:

'text'

The type of the message part.

text:

string

The text content of the message part.

ImagePart

type:

'image'

The type of the message part.

image:

string | Uint8Array | Buffer | ArrayBuffer | URL

The image content of the message part. String are either base64 encoded content, base64 data URLs, or http(s) URLs.

CoreAssistantMessage

role:

'assistant'

The role for the assistant message.

content:

string | Array<TextPart | ToolCallPart>

The content of the message.

TextPart

type:

'text'

The type of the message part.

text:

string

The text content of the message part.

ToolCallPart

type:

'tool-call'

The type of the message part.

toolCallId:

string

The id of the tool call.

toolName:

string

The name of the tool, which typically would be the name of the function.

args:

object based on zod schema

Parameters generated by the model to be used by the tool.

CoreToolMessage

role:

'tool'

The role for the assistant message.

content:

Array<ToolResultPart>

The content of the message.

ToolResultPart

type:

'tool-result'

The type of the message part.

toolCallId:

string

The id of the tool call the result corresponds to.

toolName:

string

The name of the tool the result corresponds to.

result:

unknown

The result returned by the tool after execution.

isError?:

boolean

Whether the result is an error or an error message.

tools:

Record<string, CoreTool>

Tools that are accessible to and can be called by the model. The model needs to support calling tools.

CoreTool

description?:

string

Information about the purpose of the tool including details on how and when it can be used by the model.

parameters:

Zod Schema | JSON Schema

The schema of the input that the tool expects. The language model will use this to generate the input. It is also used to validate the output of the language model. Use descriptions to make the input understandable for the language model. You can either pass in a Zod schema or a JSON schema (using the `jsonSchema` function).

execute?:

async (parameters) => any

An async function that is called with the arguments from the tool call and produces a result. If not provided, the tool will not be executed automatically.

toolChoice?:

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

The tool choice setting. It specifies how tools are selected for execution. The default is "auto". "none" disables tool execution. "required" requires tools to be executed. { "type": "tool", "toolName": string } specifies a specific tool to execute.

maxTokens?:

number

Maximum number of tokens to generate.

temperature?:

number

Temperature setting. The value is passed through to the provider. The range depends on the provider and model. It is recommended to set either `temperature` or `topP`, but not both.

topP?:

number

Nucleus sampling. The value is passed through to the provider. The range depends on the provider and model. It is recommended to set either `temperature` or `topP`, but not both.

topK?:

number

Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. Recommended for advanced use cases only. You usually only need to use temperature.

presencePenalty?:

number

Presence penalty setting. It affects the likelihood of the model to repeat information that is already in the prompt. The value is passed through to the provider. The range depends on the provider and model.

frequencyPenalty?:

number

Frequency penalty setting. It affects the likelihood of the model to repeatedly use the same words or phrases. The value is passed through to the provider. The range depends on the provider and model.

stopSequences?:

string[]

Sequences that will stop the generation of the text. If the model generates any of these sequences, it will stop generating further text.

seed?:

number

The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.

maxRetries?:

number

Maximum number of retries. Set to 0 to disable retries. Default: 2.

abortSignal?:

AbortSignal

An optional abort signal that can be used to cancel the call.

headers?:

Record<string, string>

Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.

maxAutomaticRoundtrips?:

number

Maximum number of automatic roundtrips for tool calls. An automatic tool call roundtrip is another LLM call with the tool call results when all tool calls of the last assistant message have results. A maximum number is required to prevent infinite loops in the case of misconfigured tools. By default, it is set to 0, which will disable the feature.

experimental_telemetry?:

TelemetrySettings

Telemetry configuration. Experimental feature.

TelemetrySettings

isEnabled?:

boolean

Enable or disable telemetry. Disabled by default while experimental.

functionId?:

string

Identifier for this function. Used to group telemetry data by function.

metadata?:

Additional information to include in the telemetry data.

Returns

text:

string

The generated text by the model.

toolCalls:

array

A list of tool calls made by the model.

toolResults:

array

A list of tool results returned as responses to earlier tool calls.

finishReason:

The reason the model finished generating the text.

usage:

CompletionTokenUsage

The token usage of the generated text.

CompletionTokenUsage

promptTokens:

number

The total number of tokens in the prompt.

completionTokens:

number

The total number of tokens in the completion.

totalTokens:

number

The total number of tokens generated.

rawResponse:

RawResponse

Optional raw response data.

RawResponse

headers:

Record<string, string>

Response headers.

warnings:

Warning[] | undefined

Warnings from the model provider (e.g. unsupported settings).

responseMessages:

Array<CoreAssistantMessage | CoreToolMessage>

The response messages that were generated during the call. It consists of an assistant message, potentially containing tool calls. When there are tool results, there is an additional tool message with the tool results that are available. If there are tools that do not have execute functions, they are not included in the tool results and need to be added separately.

roundtrips:

Array<Roundtrip>

Response information for every roundtrip. You can use this to get information about intermediate steps, such as the tool calls or the response headers.

Roundtrip