Generate experiences with Puck AI
Read docs
CloudAIHeadless Generation

Headless Generation

Headless generation allows you to generate Puck pages from your server.

Generate a page

Use the ai.generate() API to generate Puck Data based on a prompt and Puck config.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a page about dogs",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
});
// { root: { props: { title: "Pawesome Friends" } }, content: [ { type: "HeadingBlock", props: { id: "Heading-12345", title: "Discover Man's Best Friend" } } ] }

The output data can be provided to <Puck> for human-modification, or rendered directly with <Render>.

Execution time will vary based on the complexity of your prompt.

Update an existing page

You can use ai.generate() to update existing data by providing it to the pageData parameter.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Replace all mentions of Dog with Cat",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  pageData: {
    root: { props: { title: "Dogs: Man's Best Friend" } },
    content: [],
  },
});
// { root: { props: { title: "Cats: Man's Best Friend" } }, content: [] }

Generate with design mode

Set mode to "design" to let the agent create new component types, as described in design mode.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a pricing section with three tiers",
  config: { components: {} }, // Design mode doesn't require any components
  mode: "design",
});

Recording generations

Generations can be recorded in order to be replayed inside a custom agent. Use onPart to access each AI Part as it’s generated:

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
await puck.ai.generate({
  prompt: "Add a pricing section",
  config,
  pageData,
  onPart: (part) => {
    // Store the part
  },
});

Multi-step headless generation

By default, the ai.generate API will run a single iteration. Increasing the number of iterations can improve the quality of the result.

Increase maxIterations to increase the number of iterations. When doing this, you must also respond to data-client-request parts via the onPart callback:

const { data } = await puck.ai.generate({
  // ...
  onPart: async (part, respond) => {
    if (part.type === "data-client-request") {
      if (part.data.action === "getPageData") {
        return respond(pageData); // Provide latest page data
      } else {
        // Handle all other data-client-request types
      }
    }
    // ...
  },
});

Further reading