API ReferenceAICloud ClientpuckHandler

puckHandler

Handle all endpoints for the /api/puck/* path (used by the AI plugin) and fine-tune behavior.

// app/api/puck/[...all]/route.ts

import { puckHandler } from "@puckeditor/cloud-client";

export const POST = (request) => {
  return puckHandler(request, {
    ai: {
      context: "We are Google. You create Google landing pages.",
    },
  });
};

Args

Param	Example	Type	Status
`request`	`new Request()`	Request	Required
`cloudOptions`	`{ ai: {} }`	CloudOptions	-

Cloud Options

Param	Example	Type	Status
`ai.context`	`"We are Google"`	String	-
`ai.tools`	`{}`	Object	-
`apiKey`	`"SECRET"`	String	-
`host`	`"https://www.example.com/api/"`	String	-

`ai.context`

Provide system context and instructions to the agent.

const handler = puckHandler({
  ai: {
    context: "We are Google. You create Google landing pages.",
  },
});

`ai.tools`

Define tools that enable the agent to execute functions on your server and retrieve data. The result of the tool will be factored into the request.

Each tool call incurs an additional charge. See pricing.

import { tool } from "@puckeditor/cloud-client";
 
const handler = puckHandler({
  ai: {
    tools: {
      getProducts: tool({
        description: "Get a list of product codes",
        inputSchema: z.object(),
        execute: async () => {
          return [
            {
              name: "Google Maps",
              product_code: "maps",
            },
            {
              name: "Google Calendar",
              product_code: "calendar",
            },
          ];
        },
      }),
    },
  },
});

`apiKey`

Set your API key. Will use the PUCK_API_KEY environment variable by default.

const handler = puckHandler({
  apiKey: process.env.MY_PUCK_KEY,
});

`host`

Set a custom Puck Cloud host.

const handler = puckHandler({
  host: "https://www.example.com/api",
});

generate

tool