Assembly Mode
Assembly mode allows Puck AI to create pages from your existing components.
You can control agent behavior via the ai parameter on both component and field configs.
Providing instructions
The instructions parameter provides the agent with natural-language guidance on how to use a component or field.
Here’s an example using instructions on components:
const config = {
components: {
HeadingBlock: {
ai: {
instructions: "Always place this first",
},
fields: {
title: {
type: "text",
},
},
render: ({ title }) => <h1>{title}</h1>,
},
},
};And using instructions on fields:
const config = {
components: {
HeadingBlock: {
fields: {
title: {
type: "text",
ai: {
instructions: "Always use caps",
},
},
},
render: ({ title }) => <h1>{title}</h1>,
},
},
};Setting a schema
Some field types like custom, external, or user fields, are not supported without further configuration. This is because the shape of the data produced by those fields is unknown to the agent.
To address this, provide a schema using JSON Schema:
const config = {
components: {
HeadingBlock: {
fields: {
title: {
type: "custom",
ai: {
schema: { type: "text" },
},
render: () => <input />,
},
},
render: ({ title }) => <h1>{title}</h1>,
},
},
};We recommend using Zod to help with producing JSON Schema for complex shapes:
import z from "zod/v4";
const config = {
components: {
HeadingBlock: {
fields: {
object: {
type: "custom",
ai: {
schema: z.toJSONSchema(
z.object({
title: z.string(),
})
),
},
render: () => <input />,
},
},
render: ({ object }) => <h1>{object.title}</h1>,
},
},
};Excluding components
To completely ignore a component when generating a page, use the exclude API:
const config = {
components: {
HeadingBlock: {
fields: {
title: { type: "text" },
},
ai: {
exclude: true,
},
render: ({ title }) => <h1>{title}</h1>,
},
},
};Disabling streaming
When using the AI plugin, Puck AI will stream field values wherever possible. This can sometimes result in unexpected behavior when rendering the preview, such as broken image URLs.
You can set the stream parameter to false to disable streaming of a field:
const config = {
components: {
HeadingBlock: {
fields: {
src: {
type: "text",
ai: {
stream: false,
},
},
},
render: ({ src }) => <img src={src} />,
},
},
};Setting required fields
By default, all fields provided in defaultProps are considered required by the agent.
You can explicitly mark a field as required or optional by using the required parameter.
const config = {
components: {
HeadingBlock: {
fields: {
src: {
type: "text",
ai: {
required: true, // Mark this as required, even though it doesn't exist in defaultProps
},
},
},
render: ({ src }) => <img src={src} />,
defaultProps: {},
},
},
};Excluding fields
To completely ignore a field when generating a page, use the exclude API:
const config = {
components: {
HeadingBlock: {
fields: {
src: {
type: "text",
ai: {
exclude: true,
},
},
},
render: ({ src }) => <img src={src} />,
},
},
};Registering reusable field types
A user field type can be shared by many fields. Rather than repeating ai.schema on each one, describe the type once via fieldTypes.
Field types can be provided to the AI plugin:
const aiPlugin = createAiPlugin({
fieldTypes: {
cta: {
// Included in the prompt, so describe any rules for using the field
description: "Renders a call-to-action button",
schema: {
type: "object",
properties: {
label: { type: "string" },
},
},
},
},
});or ai.generate:
const { data } = await puck.ai.generate({
prompt: "Create a page about our products",
config,
fieldTypes: {
cta: {
// Included in the prompt, so describe any rules for using the field
description: "Renders a call-to-action button",
schema: {
type: "object",
properties: {
label: { type: "string" },
},
},
},
},
});When using this field, Puck AI will generate against the schema.
Omit schema and provide a defaultValue to have Puck AI add a field without generating the value.
const aiPlugin = createAiPlugin({
fieldTypes: {
timer: {
defaultValue: { label: "Countdown" },
description: "Renders a countdown",
},
},
});Rendering components as fields
By combining fieldTypes with field transforms, Puck AI can render your components using fields. This works with design mode.
const fieldTransforms = {
cta: ({ value }) => <button>{value.label}</button>,
};
const Example = () => <Puck fieldTransforms={fieldTransforms} />;