API ReferenceAICloud Clientchat

chat

Create a chat stream between the AI plugin and the Puck Cloud, and intercept chat requests made by the plugin.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      context: "We are Google",
    },
  });
}

Returns a Response object.

Args

Param	Example	Type	Status
`chatParams`	`{ config: {}, pageData: {} }`	ChatParams	Required
`cloudOptions`	`{ ai: {} }`	CloudOptions	-

Chat Params

Param	Example	Type	Status
`config`	`{components: {}}`	Config	Required
`pageData`	`{root: {}, content: []}`	Data	Required
`messages`	`[]`	UIMessage[]	Required

`config`

The Puck config for the page. Automatically provided by the AI plugin, but can be modified if necessary.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat({
    ...body,
    config: {
      components: {
        HeadingBlock: {
          fields: {
            title: { type: "text" },
          },
          render: ({ title }) => <h1>{title}</h1>,
        },
      },
    },
  });
}

`pageData`

The current page data. Automatically provided by the AI plugin, but can be modified if necessary.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat({
    ...body,
    pageData: {
      root: { props: { title: "My page" } },
      content: [],
    },
  });
}

`messages`

The entire message history for the chat, as an array of AI SDK UIMessages. Automatically provided by the AI plugin, but can be modified if necessary.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat({
    ...body,
    messages: [
      {
        id: "message-id",
        role: "user",
        parts: [{ text: "Create a landing page about dogs" }],
      },
    ],
  });
}

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.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      context: "We are Google. Your job is to 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 { chat, tool } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    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.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    apiKey: process.env.MY_PUCK_KEY,
  });
}

`host`

Set a custom Puck Cloud host.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    host: "https://www.example.com/api",
  });
}

Installation

generate