generateobject core

11 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Output.object() for structured data generation

Use Output.object({ schema }) to generate a structured object based on a schema (Zod, Valibot, or JSON schema). The output is type-validated to ensure the returned result matches the schema. Example: const { output } = await generateText({ output: Output.object({ schema: z.object({ name: z.string(), age: z.number().nullable(), labels: z.array(z.string()) }) }), prompt: 'Generate information for a test user.' }).

Output.array() for array generation

Use Output.array({ element, minItems, maxItems }) to specify that you expect an array of typed objects from the model. Each element must conform to the element schema. minItems and maxItems must be non-negative integers, and minItems cannot be greater than maxItems. Use the same value for both options to require an exact length. The bounds are sent to providers as part of the structured output schema when supported, and the AI SDK independently validates the final output.

Output.choice() for classification from options

Use Output.choice({ options }) when you expect the model to choose from a specific set of string options, such as for classification or fixed-enum answers. The output will always be a single string value that matches one of the specified options. The AI SDK validates that the result matches one of your options and will throw if the model returns something invalid.

Output.json() for unstructured JSON

Use Output.json() when you want to generate and parse unstructured JSON values from the model, without enforcing a specific schema. This is useful for capturing arbitrary objects or flexible structures. The AI SDK only checks that the response is valid JSON; it doesn't validate the structure or types of the values.

Output name and description for LLM guidance

You can optionally specify a name and description for the output in Output.object({ name, description, schema }), Output.array({ name, description, element, minItems, maxItems }), Output.choice({ name, description, options }), and Output.json({ name, description }). These are used by some providers for additional LLM guidance via tool or schema name.

Property descriptions with .describe() for schema hints

You can add .describe('...') to individual schema properties to give the model hints about what each property is for. This helps improve the quality and accuracy of generated structured data. Example: z.string().describe('The amount of the ingredient (grams or ml)'). Property descriptions are particularly useful for clarifying ambiguous property names, specifying expected formats or conventions, and providing context for complex nested structures.

Structured output step counting in multi-turn execution

Structured output generation counts as a step in the AI SDK's multi-turn execution model (where each model call or tool execution is one step). When combining with tools, account for this in your stopWhen configuration.

AI_NoObjectGeneratedError for parsing failures

If the model response cannot be parsed or validated against the schema, generateText rejects with an AI_NoObjectGeneratedError. The error preserves text (the text that was generated by the model), response (metadata about the language model response including response id, timestamp, and model), usage (request token usage), and cause (the cause of the error such as a JSON parsing error).

AI_NoOutputGeneratedError when result has no output

If generateText returns a result without an output, accessing result.output throws an AI_NoOutputGeneratedError. This can happen when the final step does not finish with a stop reason, for example when it finishes with tool-calls. The output property is a getter, so destructuring it also triggers this access.

Accessing reasoning from structured output generation

You can access the reasoning used by the language model to generate the object via the reasoning property on the result. This property contains a string with the model's thought process, if available. This requires using a reasoning model.

Schema validation with Zod, Valibot, or JSON schemas

The AI SDK standardises structured object generation across model providers using the output property on generateText and streamText. You can use Zod schemas, Valibot, or JSON schemas to specify the shape of the data that you want, and the AI model will generate data that conforms to that structure.

Give your agent this brain