Puck AI BetaTools

Tools

Tools enable Puck AI to query your system for information, executing functions directly on your server.

Tool calls incur an additional charge. See pricing for further information.

Configuring a tool

Use the tool() function to configure a tool and provide it to the puckHandler() or generate() APIs:

import { puckHandler, tool } from "@puckeditor/cloud-client";
import z from "zod/v4";
 
const handler = puckHandler({
  ai: {
    tools: {
      getProducts: tool({
        description: "Get a list of products",
        inputSchema: z.object(), // No arguments needed
        execute: () => [
          { code: "google_maps", title: "Google Maps" },
          { code: "google_calendar", title: "Google Calendar" },
        ],
      }),
    },
  },
});

Each tool receives a description, which Puck AI will use to understand when to use it. A Zod inputSchema describes the shape of the args the AI will provide to the execute function.

When using prompting the agent to create a page about our products, it should first query the available products via the getProducts tool.

The execute function is called on your server. Only the return value is provided to the agent.

Providing input schema

Use inputSchema to describe the arguments the agent should provide to the execute function:

import { tool } from "@puckeditor/cloud-client";
import z from "zod/v4";
 
const products = {
  consumer: [
    { code: "google_maps", title: "Google Maps" },
    { code: "google_calendar", title: "Google Calendar" },
  ],
  business: [
    { code: "google_workspace", title: "Google Workspace" },
    { code: "google_cloud", title: "Google Cloud" },
  ],
};
 
const getProducts = tool({
  description: "Get a list of products",
  inputSchema: z.object({
    category: z.enum(["consumer", "business"]), // The agent will respect the enum
  }),
  execute: ({ category }) => products[category],
});

Async execution

Tools can implement async code, query databases, and trigger side-effects:

import { tool } from "@puckeditor/cloud-client";
import z from "zod/v4";
 
const getProducts = tool({
  description: "Get a list of products",
  inputSchema: z.object(),
  execute: async () => {
    const response = await fetch(`https://example.com/api/products`);
 
    return await response.json();
  },
});

Providing hints to use tool data

You can provide instructions to your fields to encourage the agent to use tool data:

const config = {
  components: {
    ProductBlock: {
      fields: {
        title: {
          type: "text",
          ai: {
            instructions: "Always use a title provided by the getProducts tool",
          },
        },
      },
      render: ({ title }) => <h1>{title}</h1>,
    },
  },
};

This behavior can be unpredictable. We are exploring additional APIs to make this deterministic.