Puck AI BetaAI Configuration

AI Configuration

AI configuration allows further control of agent behavior via the ai parameter on both component and field configs.

Providing instructions

The instructions parameter allows you to provide natural language guidance that describe to the agent 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>,
    },
  },
};

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} />,
    },
  },
};

Getting Started

Business Context