usePuckAi

Implement your own UI for Puck AI, or use Puck AI as a client-side subagent.

import { usePuckAi } from "@puckeditor/plugin-ai";
 
function MyAgentPlugin() {
  const { chat } = usePuckAi();
 
  return (
    <button
      disabled={chat.status === "streaming"}
      onClick={() => chat.sendMessage("Make the hero blue")}
    >
      Improve this page
    </button>
  );
}

Returns an object containing chat, generate and applyPart.

Params

Param	Example	Type	Status
`host`	`host: "/api/puck/chat"`	String	-
`mode`	`mode: "design"`	`"assembly" \| "design"`	-
`onError`	`onError: (error) => {}`	Function	-
`onFinish`	`onFinish: (result) => {}`	Function	-
`prepareRequest`	`prepareRequest: (opts) => {}`	Function	-

`host`

Configure the API host to call. This should be your server.

`mode`

Set the mode used for generating the page. Can be:

"assembly" (default) - generate pages based on the provided components
"design" - design new components, incorporating existing components where possible, as described in design mode

`onError`

A function called when a chat turn fails. generate rejects instead.

`onFinish`

A function called when a chat turn finishes.

`prepareRequest`

A callback to customize every request the hook makes before it’s sent. Use this to add custom headers, add metadata to the body, or change credentials.

const { chat } = usePuckAi({
  prepareRequest: async (options) => {
    return {
      headers: {
        Authorization: "Bearer my-token",
      },
    };
  },
});

Returns

Returns an object with the shape:

Param	Example	Type
`chat.error`	`error: "Out of credits"`	String
`chat.messages`	`messages: []`	Array
`chat.regenerate`	`regenerate: () => {}`	Function
`chat.sendMessage`	`sendMessage: (prompt, options) => {}`	Function
`chat.status`	`status: "ready"`	`"ready" \| "submitted" \| "streaming" \| "error"`
`chat.stop`	`stop: () => {}`	Function
`chat.toolStatus`	`toolStatus: { call_123: {} }`	Object
`applyPart`	`applyPart: (part, options) => {}`	Function
`generate`	`generate: (prompt, options) => {}`	Function

`chat.error`

The last chat error’s message, or undefined. Also passed to onError.

`chat.messages`

The conversation, as AI SDK UIMessages.

`chat.regenerate()`

Run the conversation’s last turn again.

`chat.sendMessage(prompt, options?)`

Send a new message to the agent.

await chat.sendMessage("Add a testimonials section");

`SendMessageOptions`

Param	Example	Type	Status
`files`	`files: [{ type: "file", mediaType, url }]`	Array	-
`mode`	`mode: "design"`	`"assembly" \| "design"`	-

`files`

Files to send with the prompt, as AI SDK file parts.

`mode`

Overrides the hook’s mode for this turn.

`chat.status`

The conversation’s AI SDK status.

`chat.stop()`

Stop the running turn.

`chat.toolStatus`

The live progress of the agent’s tools, keyed by tool call id. Each entry is a ToolStatus.

`applyPart(part, options?)`

Apply and process an AI Part.

for await (const part of parts) {
  // The page part ends every generation, so the whole stream is one undo step
  await applyPart(part, { recordHistory: part.type === "data-page" });
}

`ApplyPartOptions`

Param	Example	Type	Status
`recordHistory`	`recordHistory: true`	Boolean	-

`recordHistory`

Record the page as one undo step, covering every change since the last one recorded. Defaults to false.

`generate(prompt, options?)`

Run a generation against the current page. Returns the page’s Data once it’s applied.

const data = await generate("Rewrite this page for a technical audience");

Iterates once, unless the handler’s ai.maxIterations allows more.

`GenerateOptions`

Param	Example	Type	Status
`mode`	`mode: "design"`	`"assembly" \| "design"`	-
`signal`	`signal: controller.signal`	AbortSignal	-

`mode`

Set a mode for this generation. "design" needs ai.designMode.allowed on the handler.

`signal`

An AbortSignal that cancels the generation.

createAiPlugin

withDynamicConfig