Tools
Tools enable Puck AI to query your system for information, executing functions directly on your server.
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: {
getImageUrl: tool({
description: "Get an image",
inputSchema: z.object(), // No arguments needed
execute: () => "https://www.example.com/example.png", // Call a function on your server
mode: "auto", // Use in either inline or preload modes
}),
},
},
});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.
Tool binding
By default, Puck AI will call the tool before generating a page based on the request, factoring in the result to the page. This is called āpreloadā mode.
You can also bind the result of a tool to a field using the bind API (called āinlineā mode):
// Puck config
const config = {
components: {
ImageBlock: {
fields: {
src: {
type: "text",
ai: {
// Strictly set this field the response of the `getImageUrl` tool
bind: "getImageUrl",
},
},
},
// ...
},
},
};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 images = {
dogs: ["http://example.com/dog.png"],
cats: ["http://example.com/cat.png"],
};
const getImageUrl = tool({
description: "Get an image",
inputSchema: z.object({
category: z.enum(["dogs", "cats"]), // The agent will respect the enum
}),
execute: ({ category }) => images[category][0], // Return the first image in the set
});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 getImageUrl = tool({
description: "Get an image",
inputSchema: z.object(),
execute: async () => {
const response = await fetch(`https://example.com/api/random-image`);
return await response.json();
},
});